WordPress has become one of the most popular website platforms thanks to its flexibility, ease of use, and large number of plugins and themes. One of the most powerful features of WordPress is the Block Editor (also known as Gutenberg), which allows you to create highly customizable layouts for your content.
In this article, we’ll walk you through creating a complex custom block for the WordPress Block Editor. The block we’ll build will feature multiple nested inner blocks and dynamic content. You’ll learn the basics of using the register_block_type() function in PHP and how to use JavaScript for advanced functionality, including nesting blocks with InnerBlocks.
Let’s break this down into simple, actionable steps. By the end of this guide, you’ll have a good understanding of how to create custom blocks that go beyond the basics and include both dynamic content and nested inner blocks.
What is a Custom Block in WordPress?
Before we dive into the code, it’s important to understand what a custom block is in the context of WordPress. A block is a component of the content that can be contributed to the WordPress editor. The Block Editor (Gutenberg) is built around the concept of blocks, and each block can represent a different type of content, such as paragraphs, images, buttons, and so on.
Custom blocks allow developers to extend the Block Editor with their unique content types. These blocks can include anything from simple Text to more complex layouts with nested blocks, like a testimonial slider, a custom gallery, or a pricing table. When we add dynamic content, the block can even fetch data from the server and display it, ensuring the content is up-to-date.
What You’ll Need for This Tutorial
- WordPress Installation – You need a working WordPress environment. You can use local development tools like Local by Flywheel or XAMPP to set up a local development environment.
- Basic Knowledge of PHP and JavaScript – This tutorial will involve both PHP (for server-side dynamic content) and JavaScript (for client-side block creation).
- Basic Understanding of the Gutenberg Block Editor: It helps if you’re familiar with the WordPress editor, but don’t worry if you’re not. We’ll walk through each step carefully.
Step 1: Register the Block in PHP
The first step in any block creation is to actually register the block in WordPress. This process is done in your theme or plugin’s functions.php file (or an appropriate plugin file if you are developing a plugin).
We’ll use the register_block_type() function to register our block and define various attributes, including the block’s editor script, style handles, and render_callback, which generate dynamic content on the front end.
Here’s a basic example of how you can register your block:
function my_custom_block() {
register_block_type( 'my-plugin/my-custom-block', array(
'editor_script' => 'my-custom-block-editor-script',
'editor_style' => 'my-custom-block-editor-style',
'render_callback' => 'my_custom_block_render_callback',
'attributes' => array(
'title' => array(
'type' => 'string',
'default' => 'Default Title'
),
),
) );
}
add_action( 'init', 'my_custom_block' );
function my_custom_block_render_callback( $attributes ) {
// Dynamically fetch or process content
$dynamic_content = get_dynamic_content();
return sprintf(
'<div class="my-custom-block"><h2>%s</h2><div>%s</div></div>',
esc_html( $attributes['title'] ),
esc_html( $dynamic_content )
);
}
function get_dynamic_content() {
// You can fetch dynamic content from a database, an API, or any other source.
return 'This is dynamically generated content!';
}Explanation:
- register_block_type() is used to register your custom block.
- The render_callback function handles the dynamic content. In this case, my_custom_block_render_callback() generates the block HTML output.
- Attributes, such as the block title, are defined to allow content to be customizable from the Block Editor.
Step 2: Create the Block JavaScript
Next, let’s focus on how to create the JavaScript for your custom block. WordPress provides powerful JavaScript libraries, including @wordpress/blocks, @wordpress/block-editor, and @wordpress/scripts, to help you develop custom blocks. We’ll use these libraries to define the block structure in the editor.
Here’s how to create the JavaScript file for the block:
import { registerBlockType } from '@wordpress/blocks';
import { InnerBlocks } from '@wordpress/block-editor';
import { TextControl } from '@wordpress/components';
registerBlockType( 'my-plugin/my-custom-block', {
title: 'My Custom Block',
icon: 'admin-post',
category: 'common',
attributes: {
title: {
type: 'string',
default: 'Default Title',
},
},
edit( props ) {
const { attributes, setAttributes } = props;
return (
<div className="my-custom-block">
<TextControl
label="Block Title"
value={ attributes.title }
onChange={ ( value ) => setAttributes( { title: value } ) }
/>
<InnerBlocks
allowedBlocks={ ['core/paragraph', 'core/image'] }
/>
</div>
);
},
save( props ) {
const { attributes } = props;
return (
<div className="my-custom-block">
<h2>{ attributes.title }</h2>
<div className="inner-blocks">
<InnerBlocks.Content />
</div>
</div>
);
},
} );Explanation:
- Attributes: Here, we define a title attribute that can be modified in the block editor interface.
- InnerBlocks: This is where the magic happens. InnerBlocks allows us to nest other blocks within our custom block. We use allowedBlocks to specify which blocks can be nested inside our block.
- TextControl: A simple input field that allows the user to change the block title.
The edit() function defines the block interface in the editor, while the save() function specifies what gets saved in the content. In this case, the saved content will include the dynamic title and any nested blocks.
Step 3: Handle Dynamic Content on the Frontend
While the above code allows us to display a customizable title and nested blocks, we also need to make sure that any dynamic content is generated on the front end. For this, we use the render_callback in PHP.
In the PHP code provided earlier, the render_callback fetches dynamic content (in this case, get_dynamic_content()), processes it, and outputs it on the front end. It ensures that the content displayed to users is always up-to-date, even if the block content changes after the page is published.
Step 4: Enqueue Scripts and Styles
Finally, we need to enqueue the necessary JavaScript and CSS files so that our block will look and behave as expected in both the editor and on the front end.
Please paste the following at the specific area of your plugin or theme functions.php file.
function my_plugin_enqueue_block_assets() {
wp_enqueue_script(
'my-custom-block-editor-script',
plugins_url( 'block.js', __FILE__ ),
array( 'wp-blocks', 'wp-element', 'wp-editor', 'wp-components' ),
filemtime( plugin_dir_path( __FILE__ ) . 'block.js' )
);
wp_enqueue_style(
'my-custom-block-editor-style',
plugins_url( 'editor-style.css', __FILE__ ),
array( 'wp-edit-blocks' ),
filemtime( plugin_dir_path( __FILE__ ) . 'editor-style.css' )
);
}
add_action( 'enqueue_block_editor_assets', 'my_plugin_enqueue_block_assets' );This function ensures that the block JavaScript is properly loaded in the editor and that its styles are applied correctly.
FAQs
Conclusion
Creating a custom block for the WordPress Block Editor (Gutenberg) is a powerful way to extend your site’s flexibility and functionality. By combining nested inner blocks and dynamic content, you can create highly interactive and personalized content elements that cater to specific needs. Whether you’re adding editable Text, allowing for flexible block nesting, or generating dynamic content based on real-time data, the Gutenberg editor gives you the tools to enhance the user experience.
As we’ve seen, registering the block in PHP, setting up the editor interface with JavaScript, and handling dynamic content through a render callback provides the foundation for building a complex and customized block. Follow these steps to understand the underlying concepts. You’ll be able to craft blocks that go beyond simple content and add real value to your WordPress site.
With practice, you’ll unlock even more advanced features like block attributes, custom styling, and reusable components. So, whether you’re a beginner or an experienced developer, diving into custom Gutenberg blocks is an excellent way to expand your WordPress development skills. Keep experimenting, and happy coding!
About the writer
Hassan Tahir wrote this article, drawing on his experience to clarify WordPress concepts and enhance developer understanding. Through his work, he aims to help both beginners and professionals refine their skills and tackle WordPress projects with greater confidence.
