Block Registry

This documentation page focuses on the registration of ACF Engine core blocks, and the filtering mechanism available to add or remove block types from the plugin during the registration process.

ACF Engine has a range of blocks (ACF Block Types) that it registers. These blocks are registered by default, but we provide a UI that enables the user to shut off block type registration for blocks that are not needed. Filters are provided to enable developers to view the block type registration list and make changes to it prior to registration of the block types.

BlockType is a namespace segment found as a directory under the main /src directory the ACF Engine plugin.

GitHub repo directory /src/BlockType/ GitHub – ACF Engine Blocks

ACF Engine block types layer on top of the ACF Pro block registration system and use this to register both internal block types and block types created through the Block Type Registration UI at WP Admin > ACF Engine > Block Types. If you plan to work with ACFG block types at a code level it may help to be familiar with ACF Block Type registration first. See the official documentation for ACF Block Types at https://www.advancedcustomfields.com/resources/acf_register_block_type/.

BlockType PHP Class

Namespace: AcfEngine\Core\BlockType\BlockType

GitHub: https://github.com/saberwp/acf-engine/blob/main/src/BlockType/BlockType.php

ABSTRACT class. This abstract class defines a “Block Type” from the ACF Engine perspective. Both block types registered in code and registered via the UI are registered via this abstract class.

The class BlockTypeCustom extends BlockType and this is then available during the registration to initiate block types created via the Block Type UI (WP Admin > ACF Engine > Block Types).

@TODO add link to a docs page about the Block Type UI.

Class Property Reference

  • $protected (protected)
  • $postType (protected)
    • default: acfg_block_type
  • $renderCode
  • $category
  • $icon
    • default: “columns”
  • $keywords
  • $postTypes
  • $mode
  • $align
  • $alignText
  • $alignContent
  • $renderTemplate
  • $renderContent
  • $enqueueStyle;
  • $enqueueScript;
  • $enqueueAssets;
  • $supports;

Class Method Reference

init()

Public function. Parses arguments (for a single block type) and then calls the registration function register().

register()

Organizes settings for the block type registration and then calls acf_register_block_type(). This performs registration of a single block type, and this process is handled for each block type registered.

setRenderTemplate()

Setter method for the $renderTemplate property.

renderTemplate()

Getter method for $renderTemplate property. When set this property maps to the “render_template” option for the ACF Block Type registration.

setRenderCallback()

Setter method for the $renderCallback property.

renderCallback()

Getter method for the $renderCallback property. If set, this property is used to set the callback for the ACF Block.

defaultCallback( $block, $content = ”, $isPreview, $editorPostId )

The default callback for the block type render. If the block type is registered using the Block Type Register UI, then the render_code field from the UI is automatically parsed and rendered. Block types registered in code will define a callback instead of using this default method.


BlockTypeManager PHP Class

Namespace \\

AcfEngine\Core\BlockType\BlockTypeManager

Class Method Reference

setup()

Public function. Adds actions save_post and acf/init. Called during init hook run.

savePost( $postId, $post, $update )

Callback for the action “save_post”. Targets only the post type “acfg_block_type” which is used internally to track Block Types registered by the UI. When a user creates or edits a Block Type in the WordPress admin, this callback processes the post data during save.

The last line of this method shown below saves the Block Type registration data to a JSON file. This file path is normally under /wp-content/acf-engine/block-types/ unless the save location has been changed by a filter hook.

\file_put_contents( \AcfEngine\Plugin::dataStoragePath() . 'block-types/' . $data->key . '.json', $json );

registerBlockTypes()

Handles the initial registration of core ACF Engine block types and registration of custom block types created using the Block Type Registration UI.

registerInternalBlockTypes()

Method that loops over the available core (internal) block types and registers them. There are plans to add a filter hook to this method to enable developers to add or remove block types for their projects. This filter addition is on the roadmap for v1.6.0.

registerDefinedBlockTypes()

Iterates over the defined block types (JSON block type definition files) and registers the available block types. This should allow developers to register different block types simply by dropping a JSON definition file into the block type storage location. However, there may currently be a limitation that the database also needs to have the block type defined for the block type to function as expected.

fetchByKey( $key )

Fetch a single Block Type definition from the database using a meta query for the “acfg_block_type” post type. This only works for UI defined block types or “Custom Block Types”, it does not work for internal (Core ACFG Block Types) because those are only defined in code and not in the database.

initObject( $data )

@return (object) AcfEngine\Core\BlockType\BlockTypeCustom

This method instantiates a BlockTypeCustom object using the $data provided. This method is used during the block type registrations. BlockTypeCustom extends the abstract class BlockType. Developers that want to instantiate BlockTypeCustom objects (in order to register block types manually) can follow the same process as shown in this method.

loadDataFile( $filename )

@return stdClass object with defined data for a single block type.

Loads the JSON definition file for a single defined block types, using the given $filename. The file contents are decoded, returning the data as a stdClass object. This method is used during the block type registration process to load the data for each block type defined by the Block Type Register UI.

findBlockTypeDataFiles()

Searches through the data storage location for block types and finds all available JSON definition files.

@todo refactor to enable the use of a flag “inactive” or similar option, so that blocks can exist but not be registered if the user wants to shut them off.


BlockTypeCustom PHP Class

Namespace: AcfEngine\Core\BlockType\BlockTypeCustom

BlockTypeCustom extend the BlockType class, which is an abstract class. This allows us to define block types in code, and also to parse and create block types. The class has no methods of it’s own, all it’s methods are inherited from BlockType. See BlockType for the properties and method documentation.