Day 27: Creating Custom Block Collections in Gutenberg

Introduction

Welcome to Day 27 of the Gutenberg development series! Today, we’ll cover custom block collections, a method of organizing related blocks together in the WordPress Block Editor. By creating a custom block collection, you can group similar blocks under a single category, making it easier for users to find the blocks they need and improving the overall user experience in the editor.

In this guide, you’ll learn how to:

• Register custom block categories.
• Group related blocks into collections.
• Improve block discoverability and usability in the Block Editor.

What are Custom Block Collections in Gutenberg?

Custom block collections are a way to group blocks that share a common purpose or design into a single category in the Block Editor. This makes it easier for users to find blocks that serve similar functions or fit within a particular theme. For example, you might create a Marketing collection that includes blocks for call-to-action buttons, promotional banners, and testimonials.

Block collections are particularly useful for:

• Theming: Group blocks that match a specific design or branding style.
• Functionality: Organize blocks by their role, like Content Blocks, Layout Blocks, or Social Media Blocks.
• Plugin Integration: Group blocks created by a plugin under a branded category for easy access.

Step 1: Creating a Custom Block Category

Let’s start by creating a custom category for My Theme Blocks, which will include all the custom blocks we’ve built throughout this series.

1. Register a Custom Category

In your theme’s functions.php file or a custom plugin, use the block_categories_all filter to add a custom block category.

function my_theme_register_block_category( $categories ) {
    return array_merge(
        array(
            array(
                'slug'  => 'my-theme-blocks',
                'title' => __( 'My Theme Blocks', 'my-theme' ),
            ),
        ),
        $categories
    );
}
add_filter( 'block_categories_all', 'my_theme_register_block_category', 10, 1 );

Explanation:

• block_categories_all: This filter allows you to add custom categories to the block inserter in the WordPress Block Editor.
• array_merge: Adds the new category to the existing list of categories.
• slug: The unique identifier for the category.
• title: The label that will be displayed in the Block Editor.

Step 2: Assign Blocks to the Custom Category

Now that we’ve created a custom category, let’s assign some of our custom blocks, like the Testimonial Block and Button Block, to this new category.

1. Update the Block Registration

For each block you want to include in the custom category, update the category parameter in its registration:

registerBlockType('my-theme/testimonial-block', {
    title: 'Testimonial Block',
    icon: 'format-quote',
    category: 'my-theme-blocks', // Assign to custom category
    attributes: {
        content: {
            type: 'string',
        },
        author: {
            type: 'string',
        },
    },
    edit: ({ attributes, setAttributes }) => {
        // Block edit function
    },
    save: ({ attributes }) => {
        // Block save function
    },
});

registerBlockType('my-theme/button-block', {
    title: 'Button Block',
    icon: 'button',
    category: 'my-theme-blocks', // Assign to custom category
    attributes: {
        label: {
            type: 'string',
            default: 'Click Me',
        },
    },
    edit: ({ attributes, setAttributes }) => {
        // Block edit function
    },
    save: ({ attributes }) => {
        // Block save function
    },
});

Explanation:

• category: Set to 'my-theme-blocks' to ensure that the block appears under the My Theme Blocks category in the Block Editor.

Step 3: Testing the Custom Block Collection

After registering the custom category and assigning blocks to it, let’s test it in the WordPress Block Editor.

1. Rebuild the Blocks:
   • Run your build command to ensure the updated block registration is properly loaded.

npm run build

2. Test in the Editor:
   • Open a new or existing post in the Block Editor.
   • Click the + icon to add a new block.
   • Navigate to the My Theme Blocks category in the block inserter.
   • Verify that your Testimonial Block, Button Block, and any other assigned blocks appear under this category.
3. Insert and Customize Blocks:
   • Insert the blocks from your custom category into the post.
   • Confirm that they function as expected and are easy to find.

Step 4: Enhancing the Block Collection with Block Variations

To provide users with more options, you can also add block variations within the same collection, making it even easier for them to select the right style or configuration.

1. Add Variations to Blocks

For example, let’s add a variation for the Testimonial Block that includes a different layout:

wp.blocks.registerBlockVariation('my-theme/testimonial-block', {
    name: 'compact-testimonial',
    title: 'Compact Testimonial',
    description: 'A more compact version of the testimonial block.',
    icon: 'editor-quote',
    attributes: {
        className: 'compact-testimonial',
    },
});

Explanation:

• registerBlockVariation: Adds a new variation of the Testimonial Block, giving users an option to select a more compact style directly from the block settings.

Step 5: Customizing Block Previews in the Editor

To improve the user experience even further, you can add custom previews for your blocks in the inserter.

1. Provide a Block Preview

Update the block registration to include a example key with a sample of the block’s output:

registerBlockType('my-theme/button-block', {
    title: 'Button Block',
    icon: 'button',
    category: 'my-theme-blocks',
    attributes: {
        label: {
            type: 'string',
            default: 'Click Me',
        },
    },
    example: {
        attributes: {
            label: 'Example Button',
        },
    },
    edit: ({ attributes, setAttributes }) => {
        // Block edit function
    },
    save: ({ attributes }) => {
        // Block save function
    },
});

Best Practices for Custom Block Collections

1. Group Blocks Logically: Organize blocks into collections that make sense for your users, such as grouping all content blocks together or creating a category for layout blocks.
2. Use Descriptive Category Names: Ensure that the category name is clear and describes the purpose or theme of the blocks, making it easy for users to find the right blocks.
3. Provide Previews: Adding custom previews helps users quickly understand what each block does before inserting it into their content.

Conclusion: Organizing Blocks with Custom Collections

Custom block collections make it easier for users to find and use related blocks, enhancing the overall editing experience in WordPress. By grouping blocks into categories, you can improve discoverability, streamline content creation, and ensure that blocks are organized in a logical way.

In this article, you’ve learned how to:

• Create custom block categories in the Block Editor.
• Assign blocks to specific categories for better organization.
• Enhance the user experience with variations and block previews.

In Day 28, we’ll explore creating dynamic block templates, allowing you to create templates that adjust based on user input or conditions.