A comprehensive development guide and practical advanced tutorial for the WordPress Gutenberg Block Editor

WordPress’s Gutenberg Block Editor has revolutionized the way content is created, giving editors direct control over the flexibility and structure of their pages. For developers, this represents a completely new approach to development, centered around React and modern JavaScript. This article will delve into how to create custom blocks from scratch, and then move on to more advanced topics such as developing dynamic blocks and applying block variants, providing you with a comprehensive practical guide for development.

Understanding the core architecture of the block editor

The Gutenberg Editor is not a single, monolithic application; rather, it is an ecosystem composed of multiple independent packages. Understanding its architecture is fundamental for effective development.

The separation of the editor from the data layer

The editor interface itself is separate from WordPress’s data layer. The core… @wordpress/editor The package provides the UI components for the editor. @wordpress/data The package implements state management similar to Redux. This separation allows developers to focus on the view and interaction logic of the blocks, while data persistence is handled automatically by WordPress’s core mechanisms.

Recommended Reading Mastering WordPress Custom Post Types: A Comprehensive Practical Guide from Creation to Publication。

Block Registration and Lifecycle

Each block needs to be approved or passed through a certain process. registerBlockType The function is registered. This function accepts two parameters: the unique name of the block (for example,... my-plugin/my-custom-block) and an object that contains all the configuration information for the block.
After registration, the block goes through a lifecycle that includes initialization, rendering, editing, and saving. Developers mainly control these processes by defining the necessary settings and behaviors. edit and save Two key functions are used to control the behavior of these blocks both in the editor and on the front end.

UltaHost WordPress Hosting

30-day refund guarantee, unlimited bandwidth and database usage, free DDoS protection; purchase for 3 years and get a discount of 50%.

access page

Create your first custom block from scratch.

We will create a simple “highlighted tip” block that allows users to add a tip box with a background color and a title.

Setting up the development environment and basic files

First, make sure your development environment is set up properly. You need the Node.js and npm environments. Create a new plugin folder within the plugins directory, for example: my-custom-blocksIn this folder, create the following core files:
- my-custom-blocks.php (Plugin main file)
- package.json (Used for managing Node.js dependencies and build scripts)
- src/ Directory (used for storing source code)
- build/ Table of Contents (Directory generated by the build tool, read by WordPress)

In package.json In this process, configure the build script and incorporate it into the system. @wordpress/scripts Packages can greatly simplify the configuration of tools such as Webpack and Babel.

{
  "name": "my-custom-blocks",
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
  },
  "devDependencies": {
    "@wordpress/scripts": "^26.0.0"
  }
}

In the plugin main file my-custom-blocks.php In this case, you need to use register_block_type A function is used to inform WordPress where to retrieve the content. build Assets for the directory loading section.

Recommended Reading WordPress Theme Development Guide: Building High-Performance Custom Themes from Scratch。

<?php
/**
 * Plugin Name: My Custom Blocks
 */
function my_custom_blocks_register_block() {
    register_block_type( __DIR__ . '/build/highlight-box' );
}
add_action( 'init', 'my_custom_blocks_register_block' );

The JavaScript source code for creating the block is as follows:

In src Create a file in the directory. highlight-box/index.js File: This is the main entry file for the block.

import { registerBlockType } from '@wordpress/blocks';
import { RichText, useBlockProps, InspectorControls, ColorPalette } from '@wordpress/block-editor';
import { PanelBody, PanelRow } from '@wordpress/components';

registerBlockType('my-custom-blocks/highlight-box', {
    title: '高亮提示框',
    icon: 'warning', // 从 Dashicons 中选择
    category: 'design',
    attributes: {
        title: {
            type: 'string',
            source: 'html',
            selector: '.highlight-title',
        },
        content: {
            type: 'string',
            source: 'html',
            selector: '.highlight-content',
        },
        backgroundColor: {
            type: 'string',
            default: '#fff3cd',
        },
    },
    edit: ({ attributes, setAttributes }) => {
        const blockProps = useBlockProps();
        const { title, content, backgroundColor } = attributes;

const onChangeTitle = (newTitle) => {
            setAttributes({ title: newTitle });
        };
        const onChangeContent = (newContent) => {
            setAttributes({ content: newContent });
        };
        const onChangeBackgroundColor = (newColor) => {
            setAttributes({ backgroundColor: newColor });
        };

return (
            <>
                <inspectorcontrols>
                    <panelbody title="Color Settings">
                        <panelrow>
                            <colorpalette
                                value="{backgroundColor}"
                                onchange="{onChangeBackgroundColor}"
                            />
                        </panelrow>
                    </panelbody>
                </inspectorcontrols>
                <div {...blockprops} style="{{" backgroundcolor, padding: '20px', borderradius: '5px' }}>
                    <richtext
                        tagname="h3"
                        classname="highlight-title"
                        onchange="{onChangeTitle}"
                        value="{title}"
                        placeholder="输入标题..."
                    />
                    <richtext
                        tagname="p"
                        classname="highlight-content"
                        onchange="{onChangeContent}"
                        value="{content}"
                        placeholder="输入提示内容..."
                    />
                </div>
            </>
        );
    },
    save: ({ attributes }) =&gt; {
        const blockProps = useBlockProps.save();
        const { title, content, backgroundColor } = attributes;
        return (
            <div {...blockprops} style="{{" backgroundcolor, padding: '20px', borderradius: '5px' }}>
                <RichText.Content tagName="h3" className="highlight-title" value={title} />
                <RichText.Content tagName="p" className="highlight-content" value={content} />
            </div>
        );
    },
});

Run npm start Start the development mode (to monitor file changes) or npm run build Proceed with the production build. After that, in the WordPress editor, you will be able to find and use the “Highlighting Tooltip” block under the “Design” category.

Advanced Development: Dynamic Blocks and Server-Side Rendering

The content of static blocks is directly saved within the article text. However, for blocks that require real-time data (such as a list of the latest articles or user information), we need to create dynamic blocks. When dynamic blocks are saved, only certain attributes (such as the total number of articles) are stored. The content is then dynamically generated on the front end using PHP templates.

hosting.com Shared Hosting

High performance with AMD EPYC CPUs, NVMe SSD storage and LiteSpeed, 24/7, 24x7 expert in-house support, advanced security measures including SSL, brute force, malware and DDoS protection, savings of up to 73%

access page

Convert static blocks into dynamic blocks.

First, modify the registration configuration for the block to… save The function has been modified to return a value. nullAnd add one more. render_callback Attributes.

// 在 registerBlockType 的配置对象中
save: () => {
    return null; // 动态区块不在内容中保存 HTML
},

Then, update the registration code on the PHP side to specify the rendering callback function.

function my_custom_blocks_register_dynamic_block() {
    register_block_type( __DIR__ . '/build/latest-posts', [
        'render_callback' => 'my_custom_blocks_render_latest_posts'
    ] );
}
add_action( 'init', 'my_custom_blocks_register_dynamic_block' );

function my_custom_blocks_render_latest_posts( $attributes ) {
    $posts = get_posts( [
        'posts_per_page' => $attributes['numberOfPosts'] ?? 5,
    ] );

if ( empty( $posts ) ) {
        return '<p>No articles available yet.</p>'$output = '<ul class="wp-block-my-custom-blocks-latest-posts">';
    foreach ( $posts as $post ) {
        $output .= sprintf(
            '<li><a href="/en/%s/">%s</a></li>'php
    esc_url(get_permalink($post));
    esc_html(get_the_title($post));
    $output .= '';'</ul>';

return $output;
}

Rendering using block template files.

For more complex dynamic blocks, it is recommended to use template files. Create them in the plugin directory. templates/latest-posts.phpMove the above rendering logic into that file, and then… render_callback Use it in Chinese ob_get_clean and include This approach allows for the loading of templates, which makes the PHP and HTML logic clearer and easier to maintain.

Recommended Reading WooCommerce Plugin Usage Guide: A Comprehensive Step-by-Step Guide from Installation and Configuration to Store Operation。

Advanced Topics and Best Practices

After mastering the basics and dynamic blocks, the following topics will enable you to develop more powerful and professional blocks.

Implementing the variant functionality for blocks

Block Variations allow you to create multiple predefined styles or configurations based on a single base block. For example, you can create variants such as “Success,” “Warning,” and “Error” for a “Highlighting Prompt Box.”

InterServer Shared Hosting

Shared hosting $2.50 USD per month , first month $0.1 USD promo code tryinterserver, 461 cloud apps scripts, one click install.

access page

import { registerBlockVariation } from '@wordpress/blocks';

registerBlockVariation('my-custom-blocks/highlight-box', [
    {
        name: 'success',
        title: '成功提示',
        icon: 'yes-alt',
        attributes: {
            title: '操作成功',
            backgroundColor: '#d4edda',
        },
        isDefault: false,
    },
    {
        name: 'error',
        title: '错误警告',
        icon: 'dismiss',
        attributes: {
            title: '发生错误',
            backgroundColor: '#f8d7da',
        },
    },
]);

Utilizing block styles and editor styles

utilization registerBlockStyle Functions can add different visual styles to blocks, and users can switch between these styles in the sidebar. Additionally, add_editor_style It is possible to ensure that the preview within the editor matches the front-end styles, providing a “what you see is what you get” experience.

Performance Optimization and Code Splitting

As the number of blocks increases, packaging all the JavaScript code into a single file can affect loading performance. It’s possible to use other approaches to improve this situation. @wordpress/dependency-extraction-webpack-plugin(Included already) @wordpress/scripts (II) Ensure that external dependencies on WordPress packages are correctly declared. For large plugins, consider using techniques such as on-demand loading or code splitting.

summarize

The development of the Gutenberg Block Editor involved integrating modern front-end technologies (React, JSX, Webpack) with traditional WordPress PHP knowledge. The process began with understanding its architecture, followed by mastering the core APIs through the creation of static blocks. Next, the editor’s ability to handle dynamic data was enhanced, and finally, the user experience and development efficiency were improved through advanced features such as block variants and styling. By adhering to best practices—clear code organization, performance optimization, and thorough internationalization preparation—you can create powerful, maintainable, and user-friendly custom blocks, thus fully leveraging the potential of the Gutenberg Editor.

FAQ Frequently Asked Questions

Do you have to use React to develop the Gutenberg blocks?

Yes, the official development approach for the Gutenberg editor is currently entirely based on React. Although other frameworks could theoretically be used, all the components, hooks, and tools provided by the WordPress core are built around the React ecosystem. Using another framework would introduce significant complexity and compatibility issues.

How can I add custom sidebar controls to my block?

You can use <code>InspectorControls</code> Components. Within the block… edit Within the function, return it together with the main preview content. <code>InspectorControls</code> Internally, you can use it. <code>PanelBody</code>、<code>TextControl</code>、<code>SelectControl</code>、<code>RangeControl</code></code> 等来自 Components from the @wordpress/components package are used to create a rich and customizable settings interface.

What are the performance differences between dynamic and static blocks?

The HTML content of static blocks is directly stored in the database’s post data, which results in fast loading times on the front end. However, static blocks cannot display dynamic data. Dynamic blocks require the execution of PHP code to query the database during rendering, which introduces a slight performance overhead; nevertheless, they provide real-time data. For content that does not change frequently, it is advisable to use static blocks in combination with a regular caching strategy. For content that requires high levels of real-time updates, dynamic blocks are essential.

Can I use these blocks in the traditional sidebar area or in the article meta box?

Sure, these are known as “block widgets” and “block meta boxes.” Starting from WordPress 5.8, the widget area is also entirely powered by the Gutenberg block editor. You can also use them. register_block_type The widget_types Use parameters (or related APIs) to make the blocks available in the widget editor. For article meta boxes, you can use…register_post_meta The API, in conjunction with blocks, is used to create a more intuitive metadata editing interface.