WordPress Block and Editor Filters

Summary: Learning about different Block and Editor filters in WordPress.

Block Filters

WordPress block filters play an essential role in altering or enhancing the behavior, appearance, and functionality of blocks in the Gutenberg editor. These filters give developers a way to hook into various processes and modify blocks without touching the core code, maintaining a modular approach to development.

In WordPress, filters are used to modify data before it is processed or displayed. Block filters allow us to modify various aspects of blocks, such as the block settings, attributes, save output, or even how they are rendered. This is done by hooking into specific stages of block registration or rendering using JavaScript filters (via the wp.hooks package) or PHP filters.

  • Filters vs Actions: While actions are meant to perform tasks (like sending an email or adding a CSS class), filters modify data before it’s processed. In block development, filters are primarily used to tweak how blocks are structured or rendered.
  • Modular: Filters allow us to modify blocks without altering core files. This makes it easier to keep our customizations maintainable across WordPress updates.

Block Filters for Block Settings

These filters allow us to modify the settings of a block. Settings can include attributes like whether a block is available in certain contexts, its icon, or other defining properties.

wp.hooks.addFilter(
    'blocks.registerBlockType',
    'my-plugin/modify-paragraph-block',
    function (settings, name) {
        if (name === 'core/paragraph') {
            // Change block icon
            settings.icon = 'smiley';
        }
        return settings;
    }
);

Block Attributes Filters

These filters allow us to add or modify the attributes of a block. Attributes define the data a block stores, such as text, alignment, or color.

wp.hooks.addFilter(
    'blocks.registerBlockType',
    'my-plugin/extend-block-attributes',
    (settings, name) => {
        if (name === 'core/paragraph') {
            settings.attributes.myCustomAttribute = {
                type: 'string',
                default: 'defaultValue'
            };
        }
        return settings;
    }
);

Block Editor Filters

These filters are used to customize the block editor itself, changing how blocks are displayed in the editor. We can modify the toolbar options, inspector controls, and block settings panels.

wp.hooks.addFilter(
    'editor.BlockEdit',
    'my-plugin/custom-toolbar-controls',
    (BlockEdit) => (props) => {
        if (props.name === 'core/paragraph') {
            return (
                <>
                    <BlockEdit {...props} />
                    <Toolbar>
                        <ToolbarButton
                            icon="admin-customizer"
                            label="Custom Button"
                            onClick={() => alert('Button clicked!')}
                        />
                    </Toolbar>
                </>
            );
        }
        return <BlockEdit {...props} />;
    }
);

Block Save Filters

These filters allow us to modify the saved output of a block before it is rendered on the front end. This is where we can manipulate the HTML or structure of the block’s save function.

wp.hooks.addFilter(
    'blocks.getSaveElement',
    'my-plugin/modify-save-output',
    (element, blockType, attributes) => {
        if (blockType.name === 'core/paragraph') {
            return (
                <p className="custom-class">{attributes.content}</p>
            );
        }
        return element;
    }
);

Server-Side Block Rendering Filters

WordPress blocks can also be rendered server-side using PHP. Filters like render_block allow developers to modify the server-side rendering of a block.

add_filter('render_block', 'my_plugin_modify_block_content', 10, 2);
function my_plugin_modify_block_content($block_content, $block) {
    if ($block['blockName'] === 'core/paragraph') {
        $block_content = '<div class="custom-wrapper">' . $block_content . '</div>';
    }
    return $block_content;
}

Block Category Filters

This filter allows us to register custom categories or modify existing ones, helping us organize blocks in the editor.

wp.hooks.addFilter(
    'blocks.registerBlockType',
    'my-plugin/add-custom-category',
    function (settings) {
        return [
            {
                slug: 'custom-category',
                title: 'Custom Category',
                icon: 'wordpress',
            },
            ...settings
        ];
    }
);

Editor Filters

Editor filters modify or extend the functionality of the block editor interface in WordPress.

  • Customize the block settings (e.g., changing attributes, block controls, etc.).
  • Add custom options or fields to block inspector panels.
  • Alter block toolbar components.
  • Modify the block editor experience without changing the front-end HTML output of blocks.

blocks.registerBlockType Filter

This filter allows us to modify the settings of a block at the time of its registration. It is one of the most commonly used editor filters for altering block settings like block attributes, default values, or even adding/removing categories.

wp.hooks.addFilter(
    'blocks.registerBlockType',
    'my-plugin/modify-block-attributes',
    function(settings, name) {
        if (name === 'core/paragraph') {
            settings.attributes = Object.assign(settings.attributes, {
                customAlignment: {
                    type: 'string',
                    default: 'left'
                }
            });
        }
        return settings;
    }
);

editor.BlockEdit Filter

This filter allows us to modify the block editor’s UI (including controls and sidebars) for a specific block. It’s a powerful way to add custom controls, such as buttons, dropdowns, or input fields in the block toolbar or inspector panel.

const { Fragment } = wp.element;
const { InspectorControls } = wp.blockEditor;
const { PanelBody, ToggleControl } = wp.components;

wp.hooks.addFilter(
    'editor.BlockEdit',
    'my-plugin/custom-paragraph-controls',
    (BlockEdit) => (props) => {
        if (props.name === 'core/paragraph') {
            return (
                <Fragment>
                    <BlockEdit {...props} />
                    <InspectorControls>
                        <PanelBody title="Custom Settings">
                            <ToggleControl
                                label="Enable Custom Feature"
                                checked={props.attributes.customFeature}
                                onChange={(newValue) =>
                                    props.setAttributes({ customFeature: newValue })
                                }
                            />
                        </PanelBody>
                    </InspectorControls>
                </Fragment>
            );
        }
        return <BlockEdit {...props} />;
    }
);

editor.BlockListBlock Filter

This filter modifies how blocks are rendered in the block list (the editing interface). It can be used to add custom wrapper elements or apply custom classes while in the block editor, without affecting the front-end output.

wp.hooks.addFilter(
    'editor.BlockListBlock',
    'my-plugin/custom-editor-class',
    (BlockListBlock) => (props) => {
        if (props.name === 'core/paragraph') {
            return (
                <div className="custom-editor-class">
                    <BlockListBlock {...props} />
                </div>
            );
        }
        return <BlockListBlock {...props} />;
    }
);

editor.BlockControls Filter

This filter allows us to modify the toolbar options available for a specific block. It can be used to add custom buttons or controls to the block toolbar, giving users more control over how they interact with blocks in the editor.

const { Toolbar, ToolbarButton } = wp.blockEditor;

wp.hooks.addFilter(
    'editor.BlockControls',
    'my-plugin/custom-toolbar-button',
    (BlockControls, props) => {
        if (props.name === 'core/paragraph') {
            return (
                <BlockControls>
                    <Toolbar>
                        <ToolbarButton
                            icon="admin-generic"
                            label="Custom Action"
                            onClick={() => alert('Custom action triggered!')}
                        />
                    </Toolbar>
                </BlockControls>
            );
        }
        return <BlockControls {...props} />;
    }
);

blocks.getBlockDefaultClassName Filter

This filter allows us to modify or override the default class name that is applied to a block. It is particularly useful when we want to consistently apply a custom class to specific blocks in the editor and front-end.

wp.hooks.addFilter(
    'blocks.getBlockDefaultClassName',
    'my-plugin/custom-default-class',
    (className, blockName) => {
        if (blockName === 'core/paragraph') {
            return 'custom-paragraph-block';
        }
        return className;
    }
);
«
»

Leave a Reply

Your email address will not be published. Required fields are marked *