Block Type Registration UI

ACF Engine provides an interface in the WordPress admin to register Block Types.

ACF Engine’s Block Type Registration UI is a convenient way to quickly build out Gutenberg Block Types for a project without having to write code. The blocks you build with the Block Type Registration UI can also be fairly easily ported over to a coded block that extends the ACFG Block Type PHP class.

If you’re a developer and interested in understanding the underlying technical specifications please visit the official documentation for ACF’s Block Registration function at acf_register_block_type().

Where to Find the Block Type Registration UI

With ACF Engine installed, the Block Type Registration UI lives at WP Admin > ACF Engine > Block Types. You can navigate there simply by choosing ACF Engine from the WP Admin. This will usually be low in the main menu items, close to the very bottom near the WordPress core “Settings” menu item.

ACF Advanced Custom Fields Engine plugin for WordPress.

What is a Gutenberg Block Type?

If you’re not familiar with Block Types that’s okay. Maybe you’re coming from another page builder like Elementor. Different builders have different terms that mean a similar thing, in Elementor there are “Widgets” for example. In Gutenberg, the official editor for WordPress, there are “blocks”. And we often refer to Block Types as just being “blocks”. However, this isn’t technically correct. A singular block is an “instance of a block type”. For example when you add an image to Gutenberg using the core image block type, you can then say this thing is an “image block”. The one you make is a block, but the “Image Block” is really an “Image Block Type”. This distinction doesn’t matter much when you’re just installing and using blocks, but it does matter when you want to go deeper into building custom blocks.

When you register a new block type, it becomes an equal player both with core WordPress blocks and any other registered blocks that you’ve installed using a plugin. And this is true of ACF Engine blocks as much as any other form of custom Gutenberg block. What this means is that your new block will show up everywhere that blocks are available. That includes the new Site Editor that is available if your site uses a Block Theme. One of the most useful aspects of registering custom block types is being able to use dynamic blocks in Site Editor to build the headers, footers and page template layouts for your site. With custom block types and Site Editor, you have full control over not just the content rendering, but also your site template sections as well.

Block Types List

When you first enter the Block Type Register UI you’ll see a familiar post list. ACF Engine stores Block Types registered with the UI as a custom post type with the key “acfg_block_type”. Creating a new Block Type begins by clicking on the “Add New” button.

ACF Engine Block Types list in the Block Type Register UI.
Yes you can make a Gutenberg block named “Fish Sticks” if you wish. Some people like fish sticks, do you have a problem with that?

Block Type Registration Form

There are 18 fields in the Block Type Registration Form. Most of the time, you’ll only need to use about 5-8 of them. We include all the options available from ACF’s block registration in order to make using the Block Type Registration UI equal in capability to writing the same block in code.

ACF Engine Block Type Register UI form. Fields for registering a custom Gutenberg block type.
Block Type Register UI – the register form upper section includes the unique key, title, description, render code, category and icon for the custom Block Type.

Form Fields Reference

Key (key) – enter a unique snake-cased key for your block such as “my_block_type”. Conflicts can occur if 2 or more blocks are registered using the same key, so try your best to make this unique, possibly prefixing it using your site name if needed like “mysite_block_reviews”.

Title (title) – this is the title that will appear everywhere in Gutenberg, any string can be used here, just try to make the name distinct from any existing blocks to make your custom block type easier to find in searches. Block lists can begin to get cluttered if you have a lot of block suites installed that have similar purpose blocks.

Description (description) – this is the description text that will be shown under your block title. Keep it fairly short to avoid using up valuable space in the block settings panel.

Render Code (render_code) – this is the markup (HTML) that will actually be rendered out in your block type. You can use inline CSS or inline Javascript here if you need too, but it is certainly better to enqueue a stylesheet or script file instead, and both those are options in fields later in the registration form. You cannot (no no no) use PHP here, sorry. It’s just too serious of a security risk to do PHP parsing from a code editor, and it would also be pretty impractical. If you know PHP and want to use it, you’re going to want to use our code-level solution for registering your block type.

Category (category) – this is the Block Category where your Block Type will appear in Gutenberg. Choosing the right category a bit easier to find when looking over the options manually. The default is “common”. This option (common) will actually make your block relatively easy to find, but if you make a lot of custom blocks you may want to avoid overloading the common category as it will eventually become cluttered.

Icon (icon) – choose any Dashicon (the WordPress icon font). Or, for something more custom set this as the full URL for an SVG that you’ve uploaded.

Keywords (keywords) – Enter up to 3 keywords separated by commas to assist with users finding the block type.

Post Types (post_types) – By default the new block is available for all post types. If you enter specific post types here, the block will only be available for the types you list.

Mode (mode) – Default option is “preview”. You can skip this field if you’re happy with the preview setting. With the mode set to “preview”, the preview is always shown. Edit form appears in sidebar when block is selected. The other options are “auto” and “edit”.

Align (align) – The default block alignment. Available settings are “left”, “center”, “right”, “wide” and “full”. Defaults to an empty string.

  • Auto: Preview is shown by default but changes to edit form when block is selected.
  • Edit: Edit form is always shown.

Align Text (align_text) – The default block text alignment (see supports setting for more info). Available settings are “left”, “center” and “right”. Defaults to the current language’s text alignment.

Align Content – The default block content alignment (see supports setting for more info). Available settings are “top”, “center” and “bottom”. When utilising the “Matrix” control type, additional settings are available to specify all 9 positions from “top left” to “bottom right”. Defaults to “top”.

Render Template (render_callback) – This can either be a relative path to a file within the active theme or a full path to any file.

Render Callback (render_callback) – Instead of providing a render_template, a callback function name may be specified to output the block’s HTML.

Enqueue Style (enqueue_style) – The url to a .css file to be enqueued whenever your block is displayed (front-end and back-end).

Enqueue Script (enqueue_script) – The url to a .js file to be enqueued whenever your block is displayed (front-end and back-end).

Enqueue Assets (enqueue_assets) Assign a callback function that runs only when the block is loaded, in order to selectively enqueue scripts and/or styles.

Supports (supports) – An array of features to support. All properties from the JavaScript block supports documentation may be used. The following options are supported:

  • align
  • align_text
  • align_content
  • full_height
  • mode
  • multiple default true.

Example (example) – An array of structured data used to construct a preview shown within the block-inserter.

Creating an ACF Field Group for the Block Type

What your new custom block type usually needs, is an ACF field group where the users of the block can enter their data. This is where the simplicity and power of the ACF block types shine through. It takes just minutes to build and assign a new ACF field group to your block type. Any ACF field type can be used, although some of the most advanced types might take some additional consideration in the planning phase.

The entire purpose of a block type is to render out content, including dynamic content stored in meta by Advanced Custom Fields. With ACF field groups you can map out any data support required, and even include conditional fields, tabs, groups and any other feature needed to take your Block Type to the next level.

ACF field groups assigned to your custom block type using location settings, will automatically appear in the right sidebar of Gutenberg whenever the block is selected.