How To Create A Custom Block For Gutenberg
Organic Themes has developed a custom Profile Block for Gutenberg using ES5 Javascript. Plus, we’re giving away the plugin, and showing you how to re-create it!
Update: With the upcoming release of WordPress 5.0, we have recently updated the Organic Profile Block plugin and this tutorial for Gutenberg 4.2.0+ compatibility.
A rebirth of WordPress is underway. Like it or not, Gutenberg is coming, and it is going to change things. So, with all the buzz about Gutenberg, we decided to build our first custom block. In this post I’ll outline how the block was created, the resources used, and my feelings on the subject.
Let me preface this post by stating that I’m primarily a WordPress theme designer and developer. I’ve dabbled in a few plugins as well, but my JavaScript experience is limited to simple jQuery.
When I discovered that blocks were primarily developed in the ES5 and ESNext JavaScript languages, I was intimidated. Despite my ignorance of JavaScript and the lack of documentation on blocks, I managed to build a custom block. I learned a great deal in the process.
A Custom Block For Profiles
I found a handful of helpful resources for building custom blocks. However, the examples were extremely simple. I wanted to create something more practical. So, I settled on building a Profile Block for displaying a personal profile with social media links.
The Profile Block features an image, name, title, bio and social media links. It provided the opportunity to create a “RichText” block with custom controls and inspector options. Essentially, it utilizes every aspect of blocks.
The Profile Block plugin is available on Github and the WordPress plugin directory.
Note: The Profile Block requires the active Gutenberg plugin at this time.
Building The Block With ES5
I chose to build the Profile Block using ES5 JavaScript for a couple reasons. First, it was the easiest for me to understand. Second, ES5 is supported by modern browsers. So, I can develop locally without needing a compiler like Babel.
The Block Plugin Structure
Before we dig into the code, I think it’s important to look at the overall file structure of our plugin. It will give us a better understanding of the necessary components that make up a block.
- organic-profile-block.php – Register our plugin and call our block files.
- includes – Folder for any global block resources. In this case, our fonts.
- fonts – Folder for Font Awesome font files.
- block – Folder for custom blocks.
- profile – Folder for the profile block.
- block.js – The JavaScript file where we register our custom block.
- editor.css – The styles for viewing the block within the Gutenberg editor.
- font-awesome.css – The styles for our Font Awesome icons.
- index.php – The file for enqueuing the block assets.
- style.css – The styles for the front-end appearance of the block.
- profile – Folder for the profile block.
Enqueuing Scripts and Styles
We’ll start by registering and enqueuing the scripts and styles for our custom block in the index.php file. This process should be familiar to theme and plugin developers, and it’s the bulk of the PHP we will be working with.
First, we’ll register the scripts and styles for our custom block. Here, we will assign each registered file with a unique handle, and include any dependencies:
Next, we’ll use the register_block_type() function to enqueue the scripts and styles. Here, you will use the unique handles defined in your previously registered scripts and styles.
Enqueue the scripts and styles by assigning the appropriate handles to the following registration settings:
- editor_script – Scripts loaded only within the editor. This is where you will enqueue the block.js file.
- editor_style – Styles loaded only within the editor.
- script – Scripts loaded both within the editor and the frontend of the site.
- style – Styles loaded both within the editor and the frontend of the site.
Registering The Block
Within the block.js file, we’ll start by wrapping our block in a function with its dependencies. The dependencies should match what was previously defined in our index.php file:
Next, we’ll import the components needed for our block. There are many components available. Unfortunately, I haven’t found a library listing all the components with descriptions. So, finding and using the right components has been a process of trial and error.
Now, we register the custom block:
Edit And Save
Now that we have registered our custom block, we need to build the interface. The block interface is comprised of 2 parts. The edit function is the interface for the block within the editor. The save function saves the output of the block for the front-end.
If you’re like me, and JavaScript isn’t a strength, it may be easier to think of defining the elements in the same way you would structure tags for HTML.
For instance, let’s take this simple block element:
It’s essentially the same as this HTML:
The Edit Function
I’m going to break down the edit function into 4 parts — declaring variables, block controls, inspector controls, and the elements of our block.
First, we’ll setup our edit function and declare the variables:
Next, let’s setup our block controls. This section defines the controls available within the TinyMCE editor for the block. In this case, we are adding content alignment controls and a media upload button for adding and changing our profile image:
Next, we’ll add our inspector controls. These are the additional block options that can be set by clicking the “Block” tab within the editor. For the Profile Block, the social media links are added within the inspector controls:
Now, we will build the elements of block within the editor:
The Save Function
Now, we need to save the block. This function defines the output of the block on the front-end:
Finishing Up
There you have it! That’s the bulk of creating a custom block for the upcoming Gutenberg editor. Just add styles, and you will have a fully functioning custom block!
My Feelings
When I began working with WordPress in 2008, I was ignorant of PHP development and building custom themes. I struggled to find resources on the subject. As a result, I taught myself with the little bits of information I could find. Over time, I honed my skills. I became comfortable and confident with what I learned.
The announcement of Gutenberg was somewhat frightening because it disrupted my comfort zone. I knew it would force me to learn new ways of development, and it would force our business to evolve.
Any immediate dislike towards the new direction of WordPress was based in fear. However, that’s not a valid reason for disliking Gutenberg.
The fact of the matter is that developing for Gutenberg is much more difficult. It introduces new languages and dependencies to the platform. Some developers will evolve, some will flourish, some will resist change, and some will be left behind completely. New businesses will be born, and old businesses will die.
I believe the average WordPress user is still very unaware of the changes that are taking place. However, I think Gutenberg will be a very positive change. It’s a major step towards simplifying the platform. It will provide users with considerably more control over their content. Additionally, it will eliminate the need for many shortcodes, custom post types, page templates, and other WordPress relics. Eventually the old admin will fade away, as mentioned in my post about the Future of WordPress.
The more I work with blocks, the more potential I see. It feels like a rebirth of WordPress is on the verge of taking place. Frankly, it’s needed. I was feeling stagnant in my work as of late. Now, WordPress is new again.
WordPress was built by a community of people who just started poking around in the open source software. We bent the platform to meet our needs, and we learned along the way. Gutenberg is forcing us to do that all over again. If you can get over the shock of such a big change, it has the potential to be exciting.
The Future
Organic Themes is taking Gutenberg seriously. We believe blocks are the future of building pages and websites with WordPress. As a result, we intend to align our products with the upcoming editor. We are excited about the possibilities, and looking forward to a rebirth of our company with the integration of Gutenberg into core.
We anticipate our themes becoming a framework for blocks. They will focus on simplicity, with styles and layouts catered to the usage of blocks. Additionally, we have begun development on a suite of custom blocks for Gutenberg that will seamlessly integrate with any theme. Similar to widgets with our Customizer Widgets plugin, blocks will be used to display a variety of content sections on your site.
Block Resources
The links below are the resources I found most useful when building a custom block. Additionally, this post from WP Tavern lists several Gutenberg resources.
- Writing Your First Block
- WordPress Gutenberg Examples
- Gutenberg Boilerplate by Ahmad Awais
- Existing Core Gutenberg Blocks
- Google Map Block (French)
- Gutenberg Docs
A huge thanks to the developers that have provided these resources!
Please feel free to contribute to the Git repo, and offer any constructive criticism in the comments below.
