Developing Gutenblocks is not for the faint of heart

What’s it like building blocks for the new block editor for WordPress? Turns out it’s pretty hard. Our front-end developer Sjardo Janssen spent a considerable amount of time learning how to do this. The new editor is built on technologies unfamiliar for many front-ender, Sjardo found. He also found it incredibly hard obtaining what he needed to get going. Frustrations built, which he wanted to vent in this interview. Let’s dive right in.

Do you have an example that shows just how frustrating working with Gutenblocks is?

Yeah, let’s talk about InnerBlocks. InnerBlocks are core components that tie all types of blocks together. It’s a key component that helps you reuse your blocks to make the most from their functionalities. By using InnerBlocks, you don’t have to build your own text components or image importer, for instance, as there’s probably an existing core Gutenberg block that will do everything you want.

There is one drawback, though — you can’t use an existing block on its own. You have to wrap blocks in <InnerBlocks> to make it available on a page. You can’t simply write HTML, create a <div> where you want and insert an image block, for example.

Let’s dissect that:

On the left, I want people to insert a heading and a paragraph. On the right, I want them to insert an image. Pretty straightforward, right? Actually, this is not simply one block. It’s a block that includes a child block because both parts of this block have to be wrapped in a div.

The code looks like this:

Build left-hand side and include surrounding div:

<div className="default\_content">
	<InnerBlocks
        allowedBlocks=\['core/heading', 'core/paragraph' ]
        template=\[ \['core/heading', {level: 2}] ];
        templateLock={ false }
    />
</div>

Build final block:

<div className="text-image">
	<InnerBlocks
        allowedBlocks=\['custom/default\_content', 'core/image']
        template=\[ \['custom/title-content', {}], \['core/image', {}] ];
        templateLock="all"
    />
</div>

It works, but it’s far from perfect. Why do I have to create a separate block to make sure it’s wrapped in a div? I expected to use two <InnerBlocks> like this:

<div>
	<div class=”left”>
		<InnerBlocks
			allowedBlocks=\['core/heading', 'core/paragraph' ]
	        template=\[ \['core/heading', {level: 2}] ];
		/>
	</div>
	<div class=”right”>
		<InnerBlocks
			allowedBlocks=\['core/image', 'core/paragraph' ]
	        template=\[ \['core/image', {}] ];
	        templateLock="all"
		/>
	</div>
</div>

That doesn’t work, as you can only use one <InnerBlocks> per block. Now I have to make a separate Gutenblock for each combination that I want to use within a separate <div>. I can’t give an innerBlock a class, so I have to write HTML around it to make sure I can target the group. It would be awesome if you could use blocks from the Core Gutenberg editor separately. While thinking about this, I came up with a new element, InsertBlock. An example:

<div class=”Blockname”>
	<InsertBlock
		allowedBlocks={\['core/heading', \[core/paragraph]}
template={\[core/heading]}
tagName=”div”
		className="customClassName"
	/>
	<InsertBlock
		block={\[‘core/image’]}
className=”customClassName”
tagName=”div”
		/>
	</div>
</div>

In the above example, I can use every single block in the position I need by using that proposed element <InsertBlock>. Each block has the following variables:

• AllowedBlocks
  Which blocks can be inserted in this exact position.
• Template (optional).
  The default template of blocks before starting. Works like template within <InnerBlocks>
• TemplateLock (optional)
  If you want to lock the template down, just like it works for <InnerBlocks>.
• ClassName (optional)
  If you want to give the block a custom class. If filled, it wraps the block in a <div>
• TagName (optional)
  If you want something else than a <div> wrapping the block. Works like TagName as the RichText component.

Thanks to this setup it’s possible to use everything, everywhere. Total freedom! No need for custom Gutenblocks made especially for nesting purposes, but only blocks we actually need.

I see what you mean. So, what’s your background, Sjardo? How did you come so invested in building blocks?

For years, I worked as a front-end developer and UX designer building WordPress sites. I use a combination of tools and languages to build sites and I get things done, even with my limited knowledge of PHP and JavaScript.

Gutenberg had me excited from the start. I love the core idea — creating a visual representation of the output while editing content. This way, users get a good idea of what the page looks like. The user interface is spot on. I see why plugins like Elementor, Beaver Builder and Visual Composer are so popular. For the most part, Gutenberg is easy to use — you see what’s happening and it gives you a sense of control. I love it and for Yoast.com, I want it.

Yoast invested a lot of time helping develop the new editor but did not yet put any effort into making custom blocks for our website. Now, we want to use what Gutenberg has to offer and use it as intended.

Early 2019, I was asked to create Gutenberg Block’s (Gutenblocks) for Yoast.com — a challenge I loved to accept.

What’s your regular process diving into new technology?

My process involves a lot of experimenting. I always use code snippets found in the documentation and play with those. That is how I taught myself HTML and CSS. For Gutenberg, this didn’t work.

None of the snippets I tried worked. Why? In contrary to WordPress, Gutenblocks aren’t written in PHP but JavaScript (JS). What’s more, you have two types of snippets, ES5 (or Classic JavaScript) and ESNext. The latter is a new type of JS that you need to convert to old JS before sites can use it.

It took some time for me to find out what type of JS it was. It was stated in the documentation, but only in an obscure corner of the tutorial section. If you want me to learn this, please tell me everything I need to know up front! Now, I know I need JavaScript to create elements on a website, not PHP.

You’re lucky because you could take your time experimenting to learn this technology, right? At most companies, time like this is not a given?

My boss gave me time to absorb the language and to learn it by trial and error. I’m grateful for that, but I understand that is not a given. Not many people have time to learn new technologies as loads of companies can’t or won’t invest that much.

Developers have a hard time keeping their knowledge of HTML, CSS and PHP up to date, so learning a new language is easier said than done. Especially ESNext — as you need a build process before you can even get started! I had to ask some of our JavaScript fanatics to help me set up a staging environment.

While learning a language you grow to love or hate the documentation. How was that for you?

I’m not a native English speaker, so sometimes I have a hard time understanding what something does even if the documentation is really good. Learning a new language is not easy when you struggle with both the programming language and the written language.

We can overcome that by visualizing what code should do by using screenshots of end results in the documentation. I use the output to validate my work. If I don’t get errors and the output looks good, then, for me, I did it correctly.

So you felt lost?

The standard Gutenblocks provide loads of options. If you combine all the blocks, you can do incredible stuff. Yet, when you build a theme, most of the default behavior of blocks no longer suits the design you’re after. You get new breakpoints and, sometimes, you’re looking for interactions that don’t exist yet.

For me, it’s important to see what code does. It’s even better if that code somehow fits a project I’m working on. Adding use cases to the docs might help visualize code. Pick some popular cases, like how to create a block with text and a neatly aligned image. Include a video of that use case, with a working code snippet and a screenshot of the end result. Great starting points to base your work on.

Once you got going, how was the experience building Gutenblocks?

Remember I learn to code by using snippets? That works if you get output, but I often didn’t get any. Building the ESNext file didn’t work and poorly written error messages don’t help you figure out what’s wrong. Sometimes, the page didn’t load and I got a bunch of console errors. And sometimes there were no errors, but the screen wouldn’t render anything just the same.

I know, it’s OK to get error messages. You need them to figure out why something fails, but there should be a way to find common errors in Gutenberg. Now, if I paste an exact error message into Google there are no decent answers. Checking the documentation didn’t help, as there is no FAQ. Of course, it’s a new language, but I doubt I’m the first one with these kinds of problems? A FAQ could fill the void. List common errors and warnings and show information on how to debug them.

Here’s an example. While working on settings for a block, I wanted to create a panel in the right sidebar. Apparently, the sidebar is called the InspectorControls, but you don’t find that searching for “sidebar” in the docs.

When I found the snippet and used it in my block, it didn’t look great. Borders crossed text and the layout was messed up, but I had no idea what went wrong. No errors, nothing. I doubled checked the code, removed all the changes and carefully copied and pasted the snippet from the example. Still, the same problem.

To fix this, I checked the HTML source for what was going on. I found out that the InspectorControls is a panel on its own. You don’t need <Panel> if you use it in the InspectorControls, just <PanelBody> and if you want, <PanelRow>. I now know this and will probably never do it again, but why not put stuff like this in the documentation? If possible, with an example where you can use this component.

You love working with CSS, but I heard you say styling blocks in the new editor is frustrating. Why is that?

That’s true, I love CSS. Some people think it’s black magic, but for me, everything is as clear as crystal. But the new block editor seems to hate CSS. After learning how to work with components, I spent a lot of time fighting with CSS to style blocks in the editor.

This fight starts with the number of <div> that appear when you use <InnerBlocks>. It adds two divs to an <InnerBlock> and you can’t give these a class name. Also, see the amount of HTML that has to be rendered for a heading in an <InnerBlock>. What are all those divs doing there?

Good CSS is targeting elements with as few as possible nesting. Sadly, in the current state, working with CSS is too hard. If you start a new theme, you can build your blocks and form your CSS around it. If you have an existing theme, you are up for a challenge.

So developing for Gutenberg is not for the faint of heart?

Learning a new tool has to start with liking working with it. I need to be enthusiastic about new solutions. Otherwise, I won’t use it and look for easier and faster ways of working. I don’t need slow and difficult to use tools and solutions, especially if they’re not fun to use and don’t offer much of an improvement. At this point in time, the new block editor is an improvement for the end user that works with the blocks, but not an improvement for developers that have to build those blocks. If possible, I’ll look for easier solutions that offer a more pleasant experience.

I know I sound like a down and out front-end developer who has to say goodbye to his old tricks. But I’m not and I love the Gutenberg editor. You wouldn’t think it, but I even like building blocks. I love learning new techniques and I think this is a huge step in the right direction.

Some things worry me, though. We need simple things that could make a major difference for new developers to get into WordPress and for existing developers to adapt to Gutenberg. By focussing on keeping users happy, Team Gutenberg is forgetting to keep developers happy. For all intents and purposes, they’re the ones who have to make new Gutenblocks. They will help grow WordPress, even if you don’t hear much from them.