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.

postFieldGroups

Edit post-level ACF field groups inside a block. List the field group keys under acf:

• Each group must have a post_type location rule. Groups that don't show on the current post are skipped.
• While the block is on the post, the group's meta box is hidden, along with the Meta Boxes pane if nothing else is showing in it. The block gets an Edit fields / Preview toolbar toggle. Edit lays the meta box's fields over the block; Preview renders the block with the current unsaved values.
• Values still save to the post through the meta box, so get_field( 'name', $post_id ) reads them as usual.
• ACF validation covers the fields in either mode. If a save fails on one of them while the block is in Preview, it switches to Edit and is selected so the error shows.
• The block can only be used once per post (supports.multiple is set to false). Any extra copy shows a notice in Edit mode.
• These groups always have Show in REST API and every field's Allow Access to Value in Editor UI turned on.

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:

Block Icons

Icons are sized relative to the text, 1em wide and 0.7em tall. Set --vgtbt-icon-width and --vgtbt-icon-height on the block to change that.

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.

The vgtbt_breakpoint_visibility_breakpoints filter changes the breakpoints. Each one gets a toggle, and hides its blocks while a selector (for an ancestor, like a class a script adds to html) or a media query applies, or both. Themes can add their own, and change the label or media of Desktop (1024px and up), Tablet (768px-1023px), and Mobile (up to 767px).

hidden takes a toggle out of the panel. Blocks that already use it keep hiding, and the toggle still shows on them so it can be turned off. Desktop, Tablet, and Mobile can't be removed or renamed, since static blocks save their attributes.

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.