This post aims to help you understand the key concepts for developing for the new editor in WordPress; Gutenberg. Gutenberg is still fairly new at the time of writing this. And as with all new technologies in their birth phase, the documentation and standards are unfortunately a bit lacking.
WordPress’ documentation site does have a large section dedicated to Gutenberg for developers; called the Gutenberg editor handbook. It contains quite a bit of information already. But it might be a tad confusing or intimidating for someone who’s brand new to Javascript-based technologies. For PHP-focused developers that might just have basic Javascript/jQuery knowledge, the new technologies of WordPress might seem intimidating. But trust me, once you learn the key concepts, you’ll see what new possibilities you now have as a WordPress developer.
Let’s start with the absolute basics. Which programming language(s) and tools would you need to use or learn to best develop for Gutenberg?
The language and libraries you’ll need to know
The short answer to what language you need to use for developing to Gutenberg is: Javascript. However within the world of Javascript, there are quite a few concepts, extensions and tools you should be aware of.
First and foremost there’s a matter of Javascript version. There’s an official standardization of Javascript; ECMAScript. ECMAScript 5 (often shortened to ES5) came out around 10 years ago, and is the Javascript version most of all us developers are familiar with. Then we have ECMAScript 6 (often shortened to ES6) that came out in 2015. Some people refer to this version as ES2015. And finally there’s ESNext, which is a dynamic name covering the upcoming version, containing proposals that we hope to be included in whatever next standardized version of Javascript.
You might be thinking along the lines of “so that’s all good and all, newer versions of Javascript just means more features. So I’ll just use the newest one.” But there’s a very important thing you need to know regarding Javascript versions and it’s this: Most browsers today can only understand ES5.
This means that if you want to write Javascript in ES6 or ESNext, you need to set up tools that transforms your code into ES5 so that browsers can understand it. But before you start thinking about skipping learning ES6 and ESNext altogether, remember that ES5 is 10 years old. And it will require you to write a lot more code. It will also be much less readable and more complex than if you’d write it in ES6 or ESNext.
In addition, for Gutenberg’s concepts, you also want to use JSX – a syntax-extension to Javascript. JSX is also a language that browsers cannot understand without transforming it.
So why bother with ES6, ESNext or JSX?
If you’re still not convinced that ES6/ESNext is worth the extra step for transforming it, let me show you a code comparison. With ES6 and JSX you can write this for returning a simple paragraph; with a class and dynamic output from a variable;
return <p className="example">Hello, my name is {name}</p>;
For those of you who are new to this and think I have forgotten quotes – no, I have not. This is the simpleness of JSX. Let’s compare the above with how you’d write with ES5 and WordPress’ Javascript libraries:
return wp.element.createElement(
'p',
{ className: 'example' },
'Hello, my name is ' + name
);
All of the above code is required for outputting what ES6 and JSX can do in a singular very easy to read line! Imagine building more complex UI with events and conditionals, when just a simple paragraph requires this cumbersome piece of code.
Convinced? Good!
Tranformation tools and React JS
The most common tool, and the one WordPress uses, for transforming ES6/ESNext is Babel. Commonly you’d use Babel as a plugin to Webpack, which is a tool that bundles and minifies your Javascript files. Both tools are using Node.js, which gives you some tools to run scripts for Webpack and Babel in the command line. If this sounds all confusing, I have a post that explains in depth how to set up all these tools for Gutenberg development.
The second thing you need to know regarding technologies is that Gutenberg is based on an abstraction layer on top of React JS. React JS is an open-source Javascript library maintained by Facebook, and was released around year 2013. Because React has been around a while there are plenty of tutorials, guides and documentation for this library. React’s official site has a good, detailed tutorial for you who are new to React. You definitely don’t need to be an expert in React to develop for Gutenberg, but the basics of how it works with components and states will help you a great deal in understanding Gutenberg.
To conclude:
- Learning React JS will go a long way for understanding how to develop for Gutenberg. Especially if you want to create your own custom blocks or customize the existing ones.
- You can make by using only ES5 Javascript, but it’s definitely recommended to learn ES6, ESNext and JSX.
- Get familiar with the tools needed so you can transform your ES6 / ESNext / JSX code. Those tools are npm, Webpack, and Babel.
The new way of storing post content, and why
One of the biggest benefits of Gutenberg is moving away from fixed HTML in post content. WordPress, before Gutenberg, and most web-based CMS store article content in pure HTML. This is generally not a problem with simple content (titles and paragraphs). But might be a bigger problem with more complex and dynamic rich content.
Any CMS that allow dynamic content within article content will encounter problems in how to save this as valid HTML. This could be anything from an image that refers to its ID within the system instead of the full URL. Or a widget that dynamically displays latest posts within a given category. Normally this will be solved by outputting custom cryptic HTML that makes no sense being output normally. And then let the CMS parser handle transforming those HTML pieces into something meaningful or dynamic. The disadvantage with this is that if you transfer your content into another CMS, it will often result in ugly HTML. The content would be filled with un-parsed HTML that you manually have to clean up. This issue is what Gutenberg aims to solve.
With Gutenberg WordPress has chosen to save additional and dynamic information as HTML comments. HTML comments are never visible for users on the website, and basically anything is allowed within the comment block. A HTML comment starts with <!-- and ends with -->, and Gutenberg stores data in a certain structure with JSON format. Each block in Gutenberg is wrapped by a starting HTML comment and a closing HTML comment after it.
The new way post content is stored
I won’t go into detail about how the comment blocks are structured – you’ll find a detailed guide about this in WordPress Editor Handbook. But as an example, a simple paragraph in Gutenberg post content will be saved in the database as:
<!-- wp:paragraph --> <p>Lorem ipsum dolor sit amet consectetur adipiscing elit.</p> <!-- /wp:paragraph -->
As for dynamic content, usually no HTML will be output at all. All information WordPress needs to understand what this block is doing, is found inside HTML comments. This is how Gutenberg stores a block of “Latest posts”:
<!-- wp:latest-posts {"categories":"17","displayPostContent":true,"excerptLength":30,"postLayout":"grid"} /-->
Since everything is a HTML comment, transferring your posts into another WordPress without Gutenberg or another CMS will make sure no ugly un-parsed HTML is being spat out. It will simply be ignored and skipped.
As you’ve probably figured out by now is that the comment blocks start with the name of the block, prefixed with ‘wp‘. If there are any custom settings they will be output after the name in JSON, as you can see in the example of Latest posts-block. Gutenberg refers to these as attributes, and this concept is something you’ll get very familiar with when you start learning to develop for Gutenberg.
What you as developer can do in Gutenberg
You have a couple of options in how you go about customizing your themes or plugins for Gutenberg. Listed below are the most common customizations you’d probably do as a developer.
Extend and customize existing blocks
WordPress Gutenberg comes with a large bundle of block types, and you can extend any of these. You can also remove some of them, or decide for certain cases to allow or remove only some of them.
The most common method of extending a block is adding custom block styles – which are style variations of a block. Block styles are not that common in default WordPress, but there are some. Take a look at the Quote block. In Gutenberg editor you’ll have a box in the right-side sidebar called “Styles”.
Another way of customizing existing blocks are by using filters. You are probably familiar with filters using PHP in WordPress, but with Gutenberg there are now Javascript-based filters on blocks. For example you can add your own custom attributes (settings) to all or specific types of blocks or filter how they are saved or output.
You can also manipulate the block categories, as well as removing or allowing certain blocks in certain situations. Or you can for example make sure only a handful of block types are allowed for a custom post type.
Create your own custom blocks
Creating custom blocks is perhaps the first thought most WordPress developers have. The default blocks in WordPress can go a long way, but if you are building a more complex theme or plugin you probably have specific needs. For example using Gutenberg to create a nice-looking frontpage with shortcuts to content and dynamic content. It is possible to achieve most customization by using the CSS class option that exists for all blocks. But this is not particularly user-friendly.
Writing your own custom blocks is probably the most difficult in customizing your theme or plugin for Gutenberg. But it can also be the most rewarding! Not only will you be able to create blocks that does and look exactly how you want them to – but it’s also a great way of quickly learning about the new Javascript-based technology.
Making sure your theme is Gutenberg-ready
If you are a WordPress theme developer you should be aware that there’s a good deal of setup your theme might need for Gutenberg, especially in the form of add_theme_support(). WordPress’ handbook has a good overview of all theme supports you need to consider to make your theme Gutenberg-ready.
As default WordPress will handle most styling of the default blocks itself, so you shouldn’t need to worry too much about styling these in your theme. But theme developers are usually more picky about their design and styling. So you probably will need to adjust or add to block styling. You can add editor styles to frontend only, editor only, or both. WordPress Gutenberg Handbook provides an overview of editor styles and the default block styles.
There’s also a concept of block templates where you can predefine what blocks should appear in posts. Block templates can be used as a placeholder to help the editor in filling in blocks. But it can also be used to define a fixed set of blocks and positions.
And finally, there are functions available to work with the Gutenberg parser and how to extract blocks from posts. Because all content are saved with full information about the type of content, you can easily extract specific parts of post contents. A good example is extracting the first paragraph of posts to show as excerpt. A very useful PHP function for this concept is parse_blocks(), which uses Gutenberg’s parser onto the provided post content and in return you’ll get a PHP array with all block information and content.
Conclusion
I hope this post has not only taught you something about developing for Gutenberg, but also made you curious and interested in learning more! As a PHP-focused WordPress developer who initially resisted the idea of switching to Javascript-based technology, I can tell you that once you’ve taken the step to learn about the “new way”, you’ll be happy that you did. Gutenberg does open up for new ways to customize, design and show WordPress content without the need of page-builders or themes with heavy libraries to allow flexible and good-looking post content. We just need to learn how to work with it optimally!