Preset block bindings with variations

Skill Level:

⏲️ 5 minutes

Overview

In this recipe, we’ll whip up a block variation that presets block binding to streamline workflows and save time for you and your clients. Just like prepping ingredients in advance speeds up cooking, block variations help you preset and reuse and block bindings effortlessly. Let’s get cooking! 🍳🔧

Setup

You can choose to either use the repository which provides a development environment or to just download the standalone plugin

Standalone

Instructions

Run the following command in a terminal of your choice from inside the plugins directory of your local WordPress installation.

Zsh
npx @wordpress/create-block@latest preset-block-bindings --template @block-developer-cookbook/preset-block-bindings

Once the scaffold has completed completed, start the build process from inside the newly created plugin

Zsh
cd preset-block-bindings && npm run start

Finally, make sure to activate the plugin.

Repository

Instructions

Checkout the repository (skip this step if already done)

Zsh
git clone git@github.com:ryanwelcher/block-developer-cookbook.git

Install the dependencies

Zsh
npm install

Start the development environment (make sure you have Docker installed )

Zsh
npm run env start

Run the following script from the root of the repository

Zsh
npm run prep:preset-block-bindings

Once the scaffold has completed completed, start the build process from inside the newly created plugin

Zsh
cd plugins/preset-block-bindings && npm run start

Step 1 – Registering the custom data

This is pretty quick recipe to complete but it can save you and your clients a lot of time. It can be very error prone and tedious to set up a block binding using the Block Editor and this approach allows your client to quickly insert a block with the meta already preset.

The first things you need to do is register some custom post meta in the preset-block-bindings.php file. There is already some code in there to register enqueue the script we’re going to be working.

Update the code as shown below:

preset-block-bindings.php
<?php
/**
 * Plugin Name:       Preset Block Bindings
 * Description:       Use a block binding variation to preset block bindings.
 * Requires at least: 6.1
 * Requires PHP:      7.0
 * Version:           1.0.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       preset-block-bindings
 *
 * @package block-developers-cookbook
 */

namespace BlockDevelopersCookbook;

/**
 * Register custom post meta for block binding
 */
add_action(
	'init',
	function() {
		register_post_meta(
			'post',
			'my_custom_data',
			array(
				'show_in_rest'  => true,
				'single'        => true,
				'type'          => 'string',
				'auth_callback' => function() {
					return current_user_can( 'edit_posts' );
				},
				'default'       => 'This is a default value',
			)
		);
	}
);


/**
 * Register the block editor assets.
 */
add_action(
	'enqueue_block_editor_assets',
	function() {
		$block_binding_shortcut_file = plugin_dir_path( __FILE__ ) . '/build/block-binding-shortcut.asset.php';

		if ( file_exists( $block_binding_shortcut_file ) ) {
			$assets = include $block_binding_shortcut_file;
			wp_enqueue_script(
				'block-binding-shortcut',
				plugin_dir_url( __FILE__ ) . '/build/block-binding-shortcut.js',
				$assets['dependencies'],
				$assets['version'],
				true
			);
		}
	}
);

This code is registering a my_custom_data field with a default value of This is a default value.

Step 2 – Register the block variation

For this example, you’re going to use a Paragraph block to display the custom meta. It’s important to know that only the Paragraph, Header, Image, Button blocks currently support block bindings so you will need to use one of those four blocks for now.

Open the block-binding-shortcut.js file and have a look. It only contains some imports for now so go ahead and add the code to register the block variation

block-binding-shortcut.js
/**
 * WordPress dependencies
 */
import { registerBlockVariation } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

/**
 * Register a paragraph block variation with meta binding
 */
registerBlockVariation( 'core/paragraph', {
	name: 'show-my-data',
	title: __( 'Show My Data', 'block-binding-shortcut' ),
	description: __(
		'Display custom meta data in a paragraph',
		'block-binding-shortcut'
	),
	scope: [ 'inserter', 'transform' ],
} );

Rebuild the plugin and refresh the page. You should now see a new block called “Show My Data” is available in the inserter. At this point it is only a renamed copy of the Paragraph block so lets add the binding source

block-binding-shortcut.js
/**
 * WordPress dependencies
 */
import { registerBlockVariation } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

/**
 * Register a paragraph block variation with meta binding
 */
registerBlockVariation( 'core/paragraph', {
	name: 'show-my-data',
	title: __( 'Show My Data', 'block-binding-shortcut' ),
	description: __(
		'Display custom meta data in a paragraph',
		'block-binding-shortcut'
	),
	attributes: {
		metadata: {
			bindings: {
				content: {
					source: 'core/post-meta',
					args: {
						key: 'my_custom_data',
					},
				},
			},
		},
	},
	scope: [ 'inserter', 'transform' ],
} );

This might seem a little confusing but this code sets the attributes.bindings property for this variation. It is tell the block that the content property of the block should be bound to the my_custom_data key that is found in the core/post-meta source.

By default, the core/post-meta source is the only one available but it is possible create custom block binding sources.

Next, we need give the block editor a way to determine if the block is the actual Paragraph block or if it’s this variation. This can be done via the isActive property.

block-binding-shortcut.js
/**
 * WordPress dependencies
 */
import { registerBlockVariation } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';

/**
 * Register a paragraph block variation with meta binding
 */
registerBlockVariation( 'core/paragraph', {
	name: 'show-my-data',
	title: __( 'Show My Data', 'block-binding-shortcut' ),
	description: __(
		'Display custom meta data in a paragraph',
		'block-binding-shortcut'
	),
	attributes: {
		metadata: {
			bindings: {
				content: {
					source: 'core/post-meta',
					args: {
						key: 'my_custom_data',
					},
				},
			},
		},
	},
	isActive: [ 'metadata.bindings.content.args.key' ],
	scope: [ 'inserter', 'transform' ],
} );

isActive can receive a function that receives the blockAttributes and variationAttributes that can be used to determine if the variation is active but for most uses, you can use an array of attributes that should match.

This has been greatly simplified since WordPress 6.0 and you can now use dot syntax. In our case, the isActive is checking that the key attribute of the block exists and that is matches the value in our variation. If it does, then the variation is active.

Rebuild the plugin and refresh the page. Your block should now display “This is a default value” and you should be able to edit the value directly in the block.

Well done!