Download the PHP package viget/viget-blocks-toolkit without Composer

Viget Blocks Toolkit

This toolkit was made to simplify the process of registering custom blocks with ACF Pro. It also adds several additional features to the block editor such as Block Icons and Breakpoint Visibility.

Creating Custom Blocks in your Theme

To create a block in your theme, simply create a blocks folder in the root of your theme directory. Each block should have its own folder and a block.json file. The block.json file should contain the block configuration. You can then use a render.php file (or render.twig file if Timber/Twig is supported) to render the block. By default, the blocks that support jsx will automatically render using the plugin's jsx.php file.

Customizations

block.json

tagName

Useful when using the built-in render file for jsx supported blocks, tagName can be set in block.json to specify the outer tag for the block. (By default it uses section).

innerContainer

You can disable the inner container wrapper by setting the value of innerContainer in supports to false.

autoId

Blocks do not render a generated html id attribute by default. Opt in by setting autoId in supports to true:

When enabled, block_attrs() outputs an id built from the block name and ACF's block id (for example id="hero_67f3a1b2c4d5e"), giving every instance a stable target for in-page links and scoped styles without anyone having to type one. When disabled, no generated id is written.

autoId is not required for the HTML anchor field. Core's anchor support is separate: it adds the HTML anchor field under the block's Advanced panel and renders whatever the editor types there. That works on its own, and an anchor always wins over a generated id.

Three things render an id regardless of this setting:

• An anchor set by the editor in the block's Advanced panel.
• An id passed directly to block_attrs(), e.g. block_attrs( $block, '', [ 'id' => 'contact' ] ).
• The vgtbt_default_auto_id or vgtbt_block_has_id filters (see Hooks).

The value resolves in this order: editor anchor, then the blockId attribute, then a generated blockname_acfid string.

blockId

Assign each block a unique, persistent blockId simply by adding the attribute to the block.json file.

mediaPosition

Adding the mediaPosition attribute will enable the Media Position toggle buttons in the block toolbar and apply transforms based on the mediaPosition: transformations array in the supports object. The transformations rules will apply:

• Root level transformations will apply to all child blocks.
• reverse will reverse the order of the child blocks.
• attributes will modify the block's attributes.
  • Each value will be determined based on the value of mediaPosition. See example below.
• Nested innerBlocks will apply transformations only to child blocks when present within the parent block.

In the following example scenario:

• All columns will be reversed.
• All buttons will have their layout justified based on the mediaPosition value. (mediaPosition is on the left, the attribute value is on the right)
• Any images within a column block will have their alignment switched based on the mediaPosition value.

This is an example of a block.json file with all the supported customizations.

blockPattern

You can set a blockPattern attribute default in block.json to seed <InnerBlocks /> from block markup instead of template.json.

Resolution order:

1. Registered pattern slug (exact match).
2. If the value contains /, the basename is checked as a registered slug.
3. If still not found, look for a local file in patterns/:
   • {slug}.php
   • {slug}.html
   • {slug}.twig (when Timber is available)

Both namespaced (wp-starter/cta-default) and basename (cta-default) values are supported.

templateLock

Set a templateLock attribute default in block.json to pass through to <InnerBlocks />.

When set to "contentOnly", the toolkit automatically passes that lock value to inner_blocks() render calls so ACF blocks can behave like content-only container blocks.

lock

Set a default lock object on the parent block and it will be recursively applied to seeded child blocks unless a child already defines its own lock value.

sync

Set a sync attribute to true when the blockPattern markup should be the render-time source of truth (instead of saved inner block content). This is optional and defaults to false.

template.json fallback

If there is a template.json file present, the contents of template are used as the innerBlocks template when blockPattern is not provided. Example:

block.php

If there a block.php file present, it will automatically be loaded during block registration.

render.php

There are several variables available in the render.php file:

The $block variable also has some additional values:

Breakpoint Visibility

This block settings panel is available on any supported block in the Full Site Editor and in post block editor. It allows you to set visibility for each block at different breakpoints, so blocks can be hidden or shown based on the screen size. There is a setting to also specify a breakpoint and whether the block should be hidden or shown at that breakpoint.

When a parent block is using templateLock: "contentOnly", quick visibility and icon controls remain available in block toolbar controls.

Main Helper Functions

vgtbt()

Returns an instance of the Viget Blocks Toolkit Core class.

block_attrs()

Outputs the block attributes as a string. Supported arguments:

• $block array - The block data.
• $custom_class string - Additional classes to add to the block.
• $attrs array - Additional attributes to add to the block.

Passing an id in $attrs always renders that id, regardless of the supports.autoId setting.

inner_blocks()

Outputs the <innerBlocks /> element of a block. Supported arguments:

• $props array - The properties of innerBlocks
  • template array - The template for the inner blocks. This value is automatically json_encoded.
  • templateLock string - The lock value for the inner blocks.
  • allowedBlocks array - The allowed blocks for the inner blocks. This value is automatically json_encoded.

Hooks

vgtbt_default_inner_container (Filter)

Sets the default for supports.innerContainer on blocks that don't declare one. Defaults to false.

vgtbt_default_auto_id (Filter)

Sets the default for supports.autoId on blocks that don't declare one. Defaults to false. Use this to turn generated html ids on globally, which restores the pre-1.1.7 behavior:

Blocks that declare supports.autoId explicitly are unaffected by this filter.

vgtbt_block_has_id (Filter)

Final say on whether an individual block renders its html id attribute, applied after the supports.autoId and anchor checks. Use this for per-block exceptions:

vgtbt_block_locations (Filter)

Filter the block locations. This allows you to add or change where custom blocks can be found.

vgtbt_button_icons (Filter)

Filter the button icons.

vgtbt_supported_icon_blocks (Filter)

Filter the supported icon blocks. Note: the frontend and editor CSS may need to be manually added for additional blocks.

vgtbt_button_icons_editor_css (Filter)

Filter the editor CSS for the button icons. This is useful when some icons do not use outline fill the fill property causes issues. Or can also be used to specify icon dimensions using max-height.

vgtbt_unregister_block_styles (Filter)

Unregister block styles from core blocks.

vgtbt_unregister_block_variations (Filter)

Unregister block variations from core blocks.

Auto-Updates

This plugin automatically checks for updates from GitHub releases every 12 hours and can be updated directly from the WordPress dashboard.