– an exercise in block customisation

This post is part of a series exploring how to customise a core block in the WordPress Block Editor. Our example is aiming to offer the option of a “true parallax” effect on the Block Editor Cover Block.

---

Having added the parallax javascript, a cover block on the page with class of “is-style-true-parallax” will cause the parallax Javascript to take effect.

We now investigate how to add a Block Variation. A variation is a version of a block which is pre-configured with particular attribute values, and, optionally, pre-set inner blocks. Our variation will be pre-configured with the “is-style-true-parallax” class.

Block Variation

Setting up a Block Variation requires javascript, which we enqueue in functions.php (similarly to the javascript method for Block Style):-

// Enqueue Block Variations
function webl_blockvar_enqueue() {
    wp_enqueue_script(
        'webl-block-variations',
        get_stylesheet_directory_uri() . '/assets/js/block-var.js',
	array( 'wp-blocks', 'wp-dom-ready', 'wp-element', 'wp-primitives' ),
	'0.0.1' 
    );
}
add_action( 'enqueue_block_editor_assets', 'webl_blockvar_enqueue' );

In the block-var.js file, we register the block variation.

wp.blocks.registerBlockVariation (
    'core/cover',
    {
	name: 'true-parallax',
	title: 'Cover with Parallax',
	description: 'Cover block with optional parallax (movement) on background image.',
	attributes: {
	    providerNameSlug: 'webl',
	    className: 'true-parallax',
	    hasParallax: false,
	    isRepeated: false
	},
	isActive: [ 'className' ]
    }
);

Declaration of the variation is based on the declaration of the original block. If an attribute is not specifically declared here, the original block version will be used. (Remember that the last item in this variation definition must not have a trailing comma, since it is an object.)

The “attributes” setting allows you to set specific values for the block attributes – in our case, the className value is the important one.

The “isActive” setting allows you to choose which attributes determine if the variation is active – this helps to show clearly in the editor which variation is being used for any particular block.

Some additional settings which can also be helpful are:-

icon – the block variation will use the default icon for the block, but it is possible to set a distinct icon for the block variation. This can make it easier for the user to distinguish the variation.

example – these are the settings used in the little preview of the block (which appears when you hover over the block icon in the Block Inserter).

wp.blocks.registerBlockVariation (
    'core/cover',
    {
	...
	icon: trueParallaxIcon,
	example: {
	    attributes: {
		customOverlayColor: '#FFDCA3',
		dimRatio: 40,
		url: 'https://s.w.org/images/core/5.3/Windbuchencom.jpg',
	    },
	    innerBlocks: [
	    {
		name: 'core/paragraph',
		attributes: {
		    content: '<strong>Cover with Parallax</strong>',
		    align: 'center',
		    style: {
		        typography: {
			    fontSize: 48,
		        },
		        color: {
			    text: 'white',
		        },
		    },
	        },
	    },
	    ],
	},
	...
    }
);

Variation Example Setting

For the example, I copied the example settings from the core Cover block index.js, then modified them slightly. To give a clear visual indication that this is a different block, I changed the content wording and the overlay colour.

Variation Icon

The icon can either be chosen from the existing Dashicons, in which case only the name is needed. Or it can be an SVG icon, which requires an object to be declared and passed to the icon property. 

For my purposes, I copied and then modified the Cover block icon, and saved the modified version in SVG format. A new icon, trueParallaxIcon, can then be declared as below, and then used by name as the icon setting for the block variation.

// Define the icon for the Cover block variation.
const trueParallaxIcon = wp.element.createElement(
    wp.primitives.SVG,
    { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24" },
    wp.element.createElement(
	wp.primitives.Path,
	{
	d: "M18.7 3H5.3C4 3 3 4 3 5.3V18.7C3 20 4 21 5.3 21H18.7C20 21 21 20 21 18.7V5.3C21 4 20 3 18.7 3ZM19.5 18.7C19.5 19.1 19.1 19.5 18.7 19.5H5.3C4.9 19.5 4.5 19.1 4.5 18.7V5.3C4.5 4.9 4.9 4.5 5.3 4.5H11.5V13.4L14 10.3L16.5 13.4V4.5H18.7C19.1 4.5 19.5 4.9 19.5 5.3V18.7ZM8.64645 18.3536C8.84171 18.5488 9.15829 18.5488 9.35355 18.3536L12.5355 15.1716C12.7308 14.9763 12.7308 14.6597 12.5355 14.4645C12.3403 14.2692 12.0237 14.2692 11.8284 14.4645L9 17.2929L6.17157 14.4645C5.97631 14.2692 5.65973 14.2692 5.46447 14.4645C5.2692 14.6597 5.2692 14.9763 5.46447 15.1716L8.64645 18.3536ZM8.5 11L8.5 18L9.5 18L9.5 11L8.5 11ZM9.35355 7.64645C9.15829 7.45118 8.84171 7.45118 8.64645 7.64645L5.46447 10.8284C5.2692 11.0237 5.2692 11.3403 5.46447 11.5355C5.65973 11.7308 5.97631 11.7308 6.17157 11.5355L9 8.70711L11.8284 11.5355C12.0237 11.7308 12.3403 11.7308 12.5355 11.5355C12.7308 11.3403 12.7308 11.0237 12.5355 10.8284L9.35355 7.64645ZM9.5 12V8H8.5V12H9.5Z"
	}
    )
);

See also An Introduction to Variations and the WordPress Handbook for more information on block variations.

Alternative Methods for Customising a Block

Adding a Block Style
Using Block Filters