– 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 to add an additional control to the cover block, which will allow the user to choose the “True Parallax” option. To do this, we will filter the cover block code, using a Block Filter,

Customising a Block using Block Filters

Use of block filters requires more sophisticated javascript and use of the build process, similar to developing a new block. Once the compiled javascript (and CSS) files are obtained, they can be included within the theme, or added as a plugin.

For further information about the build process and environment, see:-
Getting Started with the Block Development Environment
Setting up your Theme to use the WordPress Scripts Package and Build Environment

Enqueue the Block Filter Javascript

In functions.php, we enqueue the compiled block filter javascript (block-filter-min.js).

// Block Customisation using Block Filter
// Enqueue the Block Filter Javascript
function cover_true_parallax_editor_assets() {
    wp_register_script(
        'cover-true-parallax',
        get_stylesheet_directory_uri() . '/assets/js/block-filter-min.js',
        array('react', 'wp-block-editor', 'wp-components', 'wp-hooks', 'wp-i18n'),
        '0.0.1'
    );
    wp_enqueue_script('cover-true-parallax');
}
add_action('enqueue_block_editor_assets', 'cover_true_parallax_editor_assets');

While enqueueing the javascript, we also enqueue some editor css, to position the toggle button nicely. We could also enqueue front-end css here, if we needed it.

// Enqueue the Block Filter Javascript
function cover_true_parallax_editor_assets() {
    ...
    wp_enqueue_style(
        'cover-true-parallax-editor-style',
        get_stylesheet_directory_uri() . '/assets/css/block-filter-editor.css',
        [],
        '0.0.1'
    );
}
add_action('enqueue_block_editor_assets', 'cover_true_parallax_editor_assets');

Filter the Block on the Front End

In functions.php, as well as enqueueing the javascript (as we did for Block Style and Block Variation), we also add a function to filter and change the code which renders the block on the front end.

For our purpose, we check if the “True Parallax” option is selected, and, if so, add the is-style-true-parallax class to the block. See the WP_HTML_Tag_Processer reference for an explanation of this class, which is very useful when modifying front end rendering functions.

We could also have added our parallax javascript as part of this function. However, for simplicity and for comparison purposes, I chose to add it separately, in the same way as for the other block customisation methods.

// Render on the frontend
function cover_true_parallax_render($block_content, $block) {
    $true_parallax = isset($block['attrs']['isTrueParallax']) ? $block['attrs']['isTrueParallax'] : false;

    if (!$true_parallax) {
        return $block_content;
    }

    // Append the custom class to the block

    $p = new WP_HTML_Tag_Processor($block_content);
    if ($p->next_tag()) {
        $p->add_class('is-style-true-parallax');
    }
    $block_content = $p->get_updated_html();

    return $block_content;
}
add_filter('render_block_core/cover', 'cover_true_parallax_render', 10, 2);

The Block Filter Javascript

In the block-filter.js file, we register and define the block filter actions. Included here is the javascript file src code, but of course this must be compiled with the appropriate build process before enqueueing in the theme or plugin.

/**
 * External dependencies
 */
import classnames from 'classnames';

/**
 * WordPress dependencies
 */
import { __ } from '@wordpress/i18n';
import { addFilter } from '@wordpress/hooks';
import { InspectorControls } from '@wordpress/block-editor';
import { ToggleControl } from '@wordpress/components';

/**
 * Add the attribute needed for selecting true parallax.
 */
function addAttributes( settings ) {
    if ( 'core/cover' !== settings.name ) {
	return settings;
    }

    // Add the attribute.
    const coverAttributes = {
	isTrueParallax: {
	    type: 'boolean',
	    default: false,
	},
    };

    const newSettings = {
	...settings,
	attributes: {
	    ...settings.attributes,
	    ...coverAttributes,
	},
    };

    return newSettings;
}

addFilter(
    'blocks.registerBlockType',
    'cover-true-parallax/add-attributes',
    addAttributes
);

/**
 * Filter the BlockEdit object and add icon inspector controls to cover blocks.
 */
function addInspectorControls( BlockEdit ) {
    return ( props ) => {
	if ( props.name !== 'core/cover' ) {
	    return <BlockEdit { ...props } />;
	}

	const { attributes, setAttributes } = props;
	const { isTrueParallax } = attributes;

	return (
	    <>
		<BlockEdit { ...props } />
		<InspectorControls>
		    <div className="true-parallax-container">
			<ToggleControl
			    label={ __(
				'True Parallax',
				'cover-true-parallax'
			    ) }
			    checked={ isTrueParallax }
			    onChange={ () => {
				setAttributes( {
				    isTrueParallax:
					! isTrueParallax,
				} );
			    } }
			/>
		    </div>
		</InspectorControls>
	    </>
	);
    };
}

addFilter(
    'editor.BlockEdit',
    'cover-true-parallax/add-inspector-controls',
    addInspectorControls
);

/**
 * Add true-parallax class in the Editor.
 */
function addClasses( BlockListBlock ) {
    return ( props ) => {
	const { name, attributes } = props;

	if (
	    'core/cover' !== name ||
	    ! attributes?.isTrueParallax
	) {
	    return <BlockListBlock { ...props } />;
	}

	const classes = classnames( props?.className, {
	    'is-style-true-parallax':
		attributes?.isTrueParallax,
	} );

	return <BlockListBlock { ...props } className={ classes } />;
    };
}

addFilter(
    'editor.BlockListBlock',
    'cover-true-parallax/add-classes',
    addClasses
);

And here is the block-filter-editor.css to position the control nicely:-

.true-parallax-container{margin-top:-8px;padding:0 16px 16px}   

Alternative Methods for Customising a Block

Adding a Block Style
Adding a Block Variation