Upgrading from 2.x to 3.x

Changes

Removal of the Legacy Blocks

Legacy Blocks will be removed the library in this release, if the project you are upgrading is using these plugins. Please ensure you integrate them into the theme. The following blocks have been removed:

• Legacy Header
• Search and Filter

Child Block Constructor Changes

Child Block arguments have been restructured in this release. This is to ensure that only required fields are provided up front and any optional fields come last. The following changes have been made to the Child_Block constructor:

Parameter Changes

Made Optional:

• $fields - Previously required, now optional with a default value of an empty array (array())

Updated Default Values:

• $icon - Changed from a default value of 'block-default' to null (nullable string). If not provided, the icon will now be inherited from the parent block instead of using a default icon.

Removed:

• $supports - This parameter has been completely removed from the constructor signature. Details for how to change this is covered here.

New Parameters:

• $background_color_configurable - New optional boolean parameter (default: false) that controls whether the background color is configurable for the child block
• $text_color_configurable - New optional boolean parameter (default: false) that controls whether the text color is configurable for the child block

Migration Example

Before (2.x):

new Child_Block(
    'block-name',
    'Block Label',
    array(/* fields */),
    'path/to/template.php',
    array(/* child blocks */),
    'block-icon',
    array(/* supports */)
);

After (3.x):

new Child_Block(
    'block-name',
    'Block Label',
    'path/to/template.php',
    array(/* fields */),       // Now optional
    array(/* child blocks */), // Optional
    null,                      // Icon now defaults to null (inherits from parent)
    false,                     // background_color_configurable
    false                      // text_color_configurable
);

Note: Since $fields are now optional, you can omit them if they're empty. The $supports parameter should be removed entirely from your constructor calls. The next section covers how to add it back in if required.

Child Block Wrapper Templates

Previously child blocks always needed to be defined using a template. These templates were often the same and copy/pasted from others with slightly different options and class names. These have been reworked in this release to use a wrapper template (similar to Blocks) where a lot of the default options are already configured and taken care of for you prior to making a new template. This was introduced to try and take out some of the complexity for Child Block creation and make it quicker and easier to create Child Blocks.

Child Block Supports

If you still need to apply supports not covered by background colour or text colour, this can still be done but will require a slight change to how you construct the child block.

See the example below for how this would be accomplished:

/**
 * {@inheritdoc}
 */
protected function child_blocks(): array {
	$child_blocks = array();

	$example_child_block = new Child_Block(
		'example',
		'Example',
		__DIR__ . '/templates/example.php',
		array(),
		array(),
		null,
		true,
		true
	);

	$example_child_block->update_supports(
		function ( $supports ) {
			$supports['spacing'] = true;
			return $supports;
		}
	);

	$child_blocks[] = $example_child_block;

	return $child_blocks;
}

Rector Ruleset

As with previous releases a new set of Rector Rules (see here for setup instructions) have been created to aid with the upgrade process of a site.

This is slightly more complex than previous upgrades and you need to ensure that we run a 2-1 configuration prior to the 3-0 one. The steps for doing so will be covered below:

This rule will add versions to all blocks to give them a clear migration path in future.

vendor/bin/rector process wp-content/themes/{theme-name} --config=vendor/creode/wordpress-blocks-rector/config/blocks-2-1.php

This rule will carry out the upgrades required to aid with the argument switches.

vendor/bin/rector process wp-content/themes/{theme-name} --config=vendor/creode/wordpress-blocks-rector/config/blocks-3-0.php

WARNING

If your child block has supports or provides an array argument for supports, these won't be covered in the rector ruleset and will need addressing manually.

We've left this by default so the site will throw an exception about an unsupported argument to child blocks. It should point you to the correct block and line in that file to make the change.

We expect that this change will only affect a very small number of blocks per site, with some, not requiring this at all.