Picture of an angry face drawn on a cardboard

During the past few months we’ve been working at Nelio on Nelio A/B Testing 5.0, the new version of our conversion optimization plugin. This new version is just around the corner and it comes with many new features and tons of improvements in its UI, UX, and under the hood. It’s a faster, more robust, more usable and, in short, much better plugin.

For the development of this new version we have adopted the new WordPress development stack. That is, it’s now using React, JavaScript, Redux, and all those fancy things Gutenberg is based on. But using the latest technologies available is not always a good idea, as one might face unexpected problems down the road…

Woman saying 'oopsie'

So in today’s post I would like to comment on some of the things in Gutenbereg’s dev stack that drove me crazy.

Dizzying Development Rate

The first and big problem that Gutenberg development has is the pace at which Gutenberg evolves. Keep in mind this is a project that’s under heavy development, and this means new things pop up, change, and evolve every other day.

Cat in a car

For instance, imagine you are developing a plugin for the block editor and, as part of your plugin, you need to access the blocks in a post. When Gutenberg was first released, you accessed said blocks using the editor module…

…but this only worked for a few months, as things suddenly changed. In April 2019, Gutenberg‘s development team published a new version of Gutenberg in which they decided to extract block-related functions into their own module, block-editor, moving it away from the “post editor module.” This change (which, don’t get me wrong, makes total sense) meant that all developers who spent some time adapting their plugin to Gutenberg had to do yet another adaptation just 6 months later.

This is an issue we’ll be facing for a while. Until Gutenberg and its entire stack doesn’t freeze completely, we’ll have to accept the fact that there will be constant changes in their APIs, the module it offers, etc.

Misleading Documentation

Another thing I find quite annoying about Gutenberg is its documentation, which, at best, is somewhat tricky. Often the documentation describes scenarios that can’t be implemented or misses to explain other scenarios that are indeed possible. Again, don’t get me wrong: I love the fact that we have so many docs available, and creating and keeping up-to-date such a useful documentation is a gigantic task… but, still, this can get frustrating!

Baby that doesn't want to eat regular food

Let’s see it with another example. Suppose you want to add a checkbox in your UI. With Gutenberg, this is as easy as loading the CheckboxControl component from @wordpress/components. Now, if you look at the documentation you’ll see the following fragment:

Parent and child checkboxes

Checkboxes can have a parent-child relationship, with secondary options nested under primary options.

When the parent checkbox is checked, all the child checkboxes are checked. When a parent checkbox is unchecked, all the child checkboxes are unchecked.

If only a few child checkboxes are checked, the parent checkbox becomes a mixed checkbox.

where they explain how a parent checkbox works:

Global selection box in Gutenberg
Global selection box in Gutenberg.

The first question that comes to my mind is: how does one specify a parent-child relationship with this component? The documentation doesn’t explain anything about this… so I assume they’re simply describing the expected behavior and it’s my responsibility to make sure that my UI behaves like this. OK, cool, I can live with that.

But what about the “mixed checkbox” the docs mention?

Mixed checkbox.
Mixed checkbox.

As you can see in the previous screenshot, Title‘s checkbox doesn’t have a tick nor it’s empty, but it has a minus sign. This symbol is used to signal that some (but not all) of its child checkboxes are checked. And now the question is: how the heck do I set a checkbox into this “mixed state?”

If you take a look at the source code of this component, you will see that Gutenberg‘s checkbox doesn’t include the minus sign. The only dashicon it uses is a “check” icon so… does this mean I need to implement the “mixed checkbox” myself? I don’t know ?

Limited Examples

Finally, there’s the issue of limited examples. WordPress has been with us for so long that, for any problem you can think of, there’s probably tons of examples explaining how to solve it. Plugins, snippets, posts, questions (and answers!) on Stack Exchange… the amount of information we can access is endless.

But not with Gutenberg.

Gutenberg is different.

Gutenberg is too new.

Confused little girl

If you develop in Gutenberg you must accept that there are many things for which there aren’t any clear examples available. You will have to browse Gutenberg‘s source code and learn by yourself. You’ll have to fly solo and rely on your own knowledge and understanding of the platform to find the solution.

In Summary

Gutenberg‘s development stack is awesome, but it is so new you’ll have to accept that (a) you won’t be able to find examples on how to solve a particular problem, (b) documentation is not completely accurate yet, and (c) the stack itself is changing every other day. Nonetheless, I’d strongly suggest not to be afraid about it and learn and use these technologies as soon as you can—they’re the future of WordPress, and the sooner you get used to them, the better.

And now, tell me, what’s driving you nuts about Gutenberg? Tell us in the comment section below!

Featured Image by Andre Hunter on Unsplash.

Leave a Reply

Your email address will not be published. Required fields are marked *

I have read and agree to the Nelio Software Privacy Policy

Your personal data will be located on SiteGround and will be treated by Nelio Software with the sole purpose of publishing this comment here. The legitimation is carried out through your express consent. Contact us to access, rectify, limit, or delete your data.