In this tutorial, you’ll learn how to start block development in WordPress in easy steps. Block development in WordPress centers on a Block-based content editor known as the Gutenberg Editor. The Gutenberg editor uses blocks to create content and offers more flexible and visually consistent content than the classic editor. It is a more modern and advanced editor that replaced the traditional classic editor.
This guide is meant for developers, freelancers, educators, content creators, technical content creators, and WordPress enthusiasts.
To develop blocks effectively, you need to know several programming languages which include;
To create a development environment for block and WordPress development, you’ll need the following:
Gutenberg blocks are the basic/primary units of content within the WordPress block editor. It was introduced to WordPress in version 5.0. It provides a more flexible and visual way to create content using the block-based approach. It has changed how content is created and managed in WordPress, its approach to content creation and management is more modernized. It enhances your experience as a user with extensive customization choices and a broad range of content layouts and types.
The Gutenberg Block Editor differs significantly from the Site Editor, and understanding these differences is crucial. Read our comprehensive guide on Site Editor vs. Block Editor to learn more.
Now let’s take a look at the Key components and structure of a Block.
A block is known to be the modular unit of content that can be inserted, edited, rearranged, and styled within a WordPress block editor. In simple terms, they are the smallest unit of content that can be integrated to form a whole content. However, they can act independently.
The key components of a block include;
Each block is structured to have save functions, edit functions, attribute functions (appearance), styles functions, metadata, Icon, and categories.
There are various types of blocks in the WordPress block editor they include;
There are other different types of blocks but for this blog, this should suffice. To learn more about using these blocks, check out our post on the basics of the block editor.
The first thing to do when setting up your development environment is to install the required software (Node.js and npm). For you to install this visit the official Node.js website, when you visit the site you will see a button for download, download it, and install it on your PC.
The next thing to do is to install WordPress if you haven’t before.
There are plenty of ways to dive into block development, but here’s a straightforward, highly recommended method to get started with creating blocks in WordPress. Follow these simple steps and you’ll be developing your own blocks in no time.
Navigate to your wp-content/plugins directory and run this command in your terminal:
npx @wordpress/create-block@latest hello-world-block
This command installs the create-block package (if not already installed) and sets up a block plugin complete with all essential files and folders. Once installed, activate the plugin and check out the Gutenberg editor. You’ll find a new “Hello World Block” component in the widgets section.
To start customizing your block plugin, familiarize yourself with the generated file and folder structure. The create-block package produces the following key files and directories:
Here’s a quick rundown of the important files and folders for block development:
npm build command.Before making any changes, run the following command to watch for file updates:
npm start
Next, open src/edit.js and modify the Edit() function to test your development environment.
export default function Edit() {
return (
<p { ...useBlockProps() }>
{ __(
'Hello World Block – Checking if development environment is setup properly.!',
'hello-world-block'
) }
</p>
);
}
Now, when you drag the Hello World Block component into the content area, you’ll see the following output.
The default background is ugly in this hello world block. Right? Open the src/style.scss and change the styling of the block output.
.wp-block-create-block-hello-world-block {
background-color: #f1f1f1;
color: #000;
padding: 10px 5px;
}
What if we add a backend setting to modify the text color? let’s do this.
Open the src/block.json and just add the color properties in supports dictionary.
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "create-block/hello-world-block",
"version": "0.1.0",
"title": "Hello World Block",
"category": "widgets",
"icon": "smiley",
"description": "Example block scaffolded with Create Block tool.",
"example": {},
"supports": {
"html": false,
"color": {
"background": false,
"text" : true
}
},
"textdomain": "hello-world-block",
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./style-index.css",
"viewScript": "file:./view.js"
}
and you’re done! Below is the expected output.
Now can you add settings to modify the background color? You got it right! just change “background”: false to “background”: true
Next, We will be looking at how to customize the block edit component, add block attributes, implement block controls and inspector settings, and save and render block content.
In addition to the built-in settings for colors, background, typography, and more, you can also add your own custom settings. In this example, we’ll add a content input box to modify the content of the block. Follow these steps:
Open src/block.json and add a custom content attribute as shown below. This will store the user’s input in the content variable, which we’ll use in the Edit() function in edit.js.
"attributes": {
"content": {
"type": "string"
}
},
To create a text input for this content, we’ll use InspectorControls, PanelBody, and TextControl components. Here’s the modified code in edit.js:
import { __ } from '@wordpress/i18n';
import { InspectorControls,useBlockProps } from '@wordpress/block-editor';
import { PanelBody, TextControl, ToggleControl } from '@wordpress/components';
import './editor.scss';
export default function Edit( { attributes, setAttributes } ) {
const { content } = attributes;
return (
<>
<InspectorControls>
<PanelBody title={ __( 'Settings', 'hello-world-block' ) }>
<TextControl
label={ __(
'Write Content',
'hello-world-block'
) }
value={ content || '' }
onChange={ ( value ) =>
setAttributes( { content: value } )
}
/>
</PanelBody>
</InspectorControls>
<p { ...useBlockProps() }>
{ content }
</p>
</>
);
}
After saving, you should see a content setting as shown below:
To access the attributes defined in block.json, pass attributes and setAttributes to the Edit() function.
export default function Edit( { attributes, setAttributes } ) {
const { content } = attributes;
// TODO
}
Next, use setAttributes to assign the value of the content on text input change.
<TextControl
label={ __(
'Write Content',
'hello-world-block'
) }
value={ content || '' }
onChange={ ( value ) =>
setAttributes( { content: value } )
}
/>
Finally, use the content variable to output in the paragraph.
<p { ...useBlockProps() }>
{ content }
</p>
With this approach, you can easily add custom attributes and access them in the Edit file to further customize your block.
Though, you need to make changes in save.js as well otherwise you’ll not see saved changes in the frontend. Same as edit.js, we have to pass the attributes and then use the content variable to output.
import { useBlockProps } from '@wordpress/block-editor';
export default function save( { attributes, setAttributes }) {
const {content} = attributes;
return (
<p { ...useBlockProps.save() }>
{ content }
</p>
);
}
The usage of the React component on your blocks.
React components are reusable pieces of code that do the description of a part of the user interface in a React application.
There are two types of React components, they include;
Class and Function react components.
The class react component determines the usage of class ES6.
The function react component determines the usage of JavaScript functions.
To create a react component, it is important to know which of the types you are creating.
The function react component is easy to create and is used when you don’t want to manage methods. While class react is used when you want to manage methods.
Here are the steps involved in handling dynamic data with API requests.
When you talk about enhancing the functionality and customization options of a custom block then you are referring to custom control and inspection panel.
Custom Control allows for direct integration into the block toolbar or sidebar. custom controls allow users to customize the block’s settings or content directly within the editor interface, and they include;
Inspector Panel: they are sections within the block sidebar that provide a more detailed view or editing capabilities beyond what is made available in the toolbar of the block. They have additional settings related to the block. However, they are defined using a panel body from the WordPress component library.
Before you handle any media uploads, you first need to add some features that encourage users to upload media files like videos, images, and likes, and also add links to an external resource e.g. URLs.
WordPress provides built-in support for handling media uploads through the Media Library. Custom blocks can leverage this functionality using the MediaUpload component from @wordpress/block-editor and @wordpress/components.
A nested content is referred to as a content structure where elements are embedded in other elements hierarchically. It allows for the embedding of blocks within another block. Thereby creating more complex and organized layouts.
How do you implement it? To implement an inner block for nested content, you are required to get two blocks.
After you have gotten the blocks, you then register the parent block. To do this, Simply create a Javascript file for your block and name it parent-block.js. After the registration is successful, you specify the block you want to be nested inside the parent block in the InnerBlocks component, your code should look like this.
The next thing is to style the block. You can style the block by creating a CSS file to style both the parent block and the nested block.
However, note that you can separately register the parent clock and the nested block if the block to be nested is a custom clock and this brings us to the end of the implementation of the inner block for nested content.
Testing and debugging is a very important part of block building, it is crucial for ensuring that all errors and bugs are fixed right from their root cause. It also ensures that blocks are fully optimized, and it ensures that your blocks behave in the expected way in various scenarios.
Testing blocks in different environments: blocks can be tested in various environments ranging from the local environment, themes, various plugins, different WordPress versions, different browsers, different devices, different operating systems, and the like.
To test your block in the local environment: you install the script for building and testing blocks that are compatible with your local environment and run the test.
To test with various browsers, you can use Google Chrome, Mozilla Firefox, Safari, and likes. Use the developer tool of any of the above browsers to test your blocks for any errors or bugs.
Testing it for various WordPress versions:
Run your block in any of the WordPress versions be it the previous or latest version to test for bugs and errors. You can also test with themes like the Twenty-Twenty-one or Twenty-twenty-two.
Note: the issues and debugging techniques are not limited to the aforementioned.
Here are some of the reliable testing tools because I have been using them for quite some time now. They include
They include:-
VScode: The VScode supports various programming languages including javascript, it uses code to identify and fix errors.
There are many other debugging tools they include. Logfile, PHP error debug, and many others.
However, I prefer using VScode for its programming capabilities.
They include;
The performance of custom blocks or any other blocks can be optimized.
Optimization of performance is crucial for smooth running and maintaining the overall speed and user experience. It allows for quick loading.
Some of the best practices used in performance optimization include.
After you have done your final review checking, your content accuracy, grammar and style, and must have performed various testing and debugging, the next thing to do is to deploy your blocks. Before deploying, make sure all necessary content is backed up. Then set up the environment to make sure it is ready for the new development. Deploy your block to a staging or testing environment and verify that it works perfectly with the testing environment and that the block integrates well with other components of the system, you conduct a final review deploy the code, and merge it into the main branch and drag it to the production server.
When writing documentation for your block, it is important to note your document structure, use simple language, highlight the important parts, and make use of images.
Here are the steps to take.
After you have thoroughly tested your block to ensure it is stable and bug-free, and it adheres to WordPress coding standards and best practices, you include the (readme.txt) file and the (Plugin PHP), Javascript file, and likes.
To upload the plugin on wordpress.org, go to the WordPress plugin submission page, and fill out the form with your plugin details, including the plugin name, description, and a link to your plugin’s zip file, and submit. An approval mail will be sent to you it contains your SVN repository details.
Once your plugin is approved, Use the SVN to upload the plugin on wordpress.org and place your files & folders in the trunk folder.
Create a tag for release in the tags directory and verify if your file and information have been uploaded. Make sure that all files and information are correctly displayed. To do this, check your plugin page on the WordPress plugin repository.
Conclusion
In conclusion, when dealing with a block editor, there are some things you should always take note of and they include;
Having basic knowledge about block editors, and developing the right environment setup like node. js,npm, etc., pay close and meticulous attention to your block structure and component, and try as much as possible to make use of advanced customization like react, do not in any way forget to test and debug, styling and customization should be properly done, and write clear documentation and prepare your blocks for deployment making sure it complies to WordPress coding standard and submit to WordPress plugin repository.
Trying to stay on top of it all? Get the best tools, resources and inspiration sent to your inbox every Wednesday.
