In October 2017, Konstantinos Galanakis, a WordPress core contributor and plugin developer, is charged with what seems like an easy task: prepare Toolset plugins for the Gutenberg Editor. His first thoughts? If you think the answer is, “Wow, cool, how exciting is that!” we need to disappoint you.

“Honestly? I was terrified,” is Kostas’ reply when asked about his first reaction. And at first it seemed as if his fears were justified: over the past several months, that “simple” task has turned into a huge project.

Why was Kostas so nervous? And was the project really so complicated?

Rough beginnings

At the end of 2017, the Gutenberg plugin has a 1.5 star rating in the WordPress plugin directory; it is perhaps unsurprising, therefore, that Kostas is more scared than excited when he gets his assignment.

2017 Gutenberg reviews, source:
2017 Gutenberg reviews, source:

Hundreds of WordPress folks are complaining about how Gutenberg will ruin WordPress-based sites and even WordPress itself.

At the same time, there are hundreds of other WordPress plugin developers in exactly the same situation, all with the same basic objective:

Make sure that when Gutenberg gets shipped into WordPress’ core, your plugins are compatible.

Here at WordCamp US we often hear developers expressing their thoughts about Gutenberg. As with Kostas, many are more fearful than excited. However, that attitude seems to be changing.

“I was 90% scared and 10% excited before, and now I’m 90% excited and 10% scared.”

– a UK developer asking a question at the WordCamp US Q&A. He then continued on to explain exactly what scares him about Gutenberg.

WordCamp US 2017 WordCamp US 2017

Perhaps, like this UK developer, fear is making things look twice as bad as they are. Eventually maybe we’ll all switch from 90/10 fear/excitement to 10/90.

Gutenberg documentation

At the same time attendees at WordCamp US were becoming more trusting of Gutenberg, on the other end of the globe, in southern Europe, Kostas was attempting to wet his feet in the Gutenberg sea. He started by experimenting with creating new blocks and reading the Gutenberg documentation.

Gutenberg documentation handbook
Gutenberg documentation handbook, source:

However, Kostas immediately faces obstacles.

Back in 2017, the Gutenberg documentation was very poor. It wasn’t being updated as quickly as the Gutenberg plugin was iterating.

“In the Gutenberg handbook there were a few examples on how to create a block, but none of them were working properly. – Kostas recalls.

There was no single website a WordPress plugin developer could visit to become fully equipped with the essentials to for coding using this new approach.

The dangerous beast

What is the first thing humans do when faced with a big change and feeling anxiety?

Basic human instinct tells us to protect our best and prepare for the worst. For a WordPress developer like Kostas, responsible for plugins that power thousands of live sites, this means ensuring that these sites won’t break.

Kostas installs the Gutenberg plugin in a test site, therefore, to see what happens.

“To my surprise, actually, there wasn’t much that got broken,” Kostas recalls. “All the Views, Content Templates, even CRED forms were in place and seemed to work fine.”

This was due in part to Gutenberg’s preservation of shortcodes. Most of what you build using Toolset plugins is based on shortcodes. Luckily the Gutenberg team decided to leave these shortcodes unchanged. In the future, according to the Gutenberg FAQ section, shortcodes will continue to work as they do now, however, the team recommends eventually changing all shortcodes into blocks.

How will shortcodes work in Gutenberg
How will shortcodes work in Gutenberg, source: Gutenberg FAQ

Kostas was relieved when he realized this:

“That would give us a chance to gradually turn shortcodes into blocks without doing any damage to existing sites.”

Eventually Kostas did find some issues with the inline blocks. But we’ll return to this issue in a bit.

For now, the new year is coming and . . . WordPress developers need to learn how to code again.

Isn’t that ironic?

Learning how to code for Gutenberg

Imagine this: you’ve been an experienced WordPress developer for years, with solid a background in WordPress API, hooks, filters, PHP, and JavaScript. You have numerous tech tools at your fingertips, yet when it comes to creating your first block in Gutenberg you get stuck.


You Google how to create Gutenberg blocks and are flooded with a wave of new terms: ES5, ES 6/7/8/Next, the Modern JavaScript approach, webpack, React, ESLint, Babel, etc.

Steps to writing JS in 2017
Steps to writing JS in 2017, source:

You are confused whether to learn React or not. You can build Gutenberg blocks using the React library, but the Gutenberg team also provides the so-called “abstraction layer,” so maybe you shouldn’t bother with React at all.

To React or not to React - Gutenberg
To React or not to React

You read and read, do more digging and Googling, but your first block is still not ready.

“The turning point for me was buying and watching Zac Gordon’s Gutenberg Development course.” – Kostas

On January 5, 2018, announces the release of a Gutenberg video training for web developers.

Zac Gordon, previously known as the JavaScript Educator, prepared a Gutenberg course for WordPress developers at breakneck speed while Gutenberg was still under development.

In his interview for the WordPress weekly, Gordon explains this decision to create a course so quickly:

“I have to drop everything I’m doing and do a Gutenberg course because otherwise how are people gonna learn this? It has not been something easy to learn. . . . I try to stay away from things like too much coffee and Red Bull, but my house was filled with these things.”

eff Chandler and John James Jacoby interviewing Zac Gordon, the author of the Gutenberg Development Course
Jeff Chandler and John James Jacoby interviewing Zac Gordon, the author of the Gutenberg Development Course, source:

Gordon’s trouble was well-appreciated. Kostas describes how helpful the course was:

“The course was a game changer for me. It comes with block examples and a plugin that allows you to quickly set up the development environment for coding blocks. The dirty work is already handled, and you can test your changes in blocks immediately.”

The package.json file from Zac’s course boots up the development environment, allowing you to test your first blocks much faster
The package.json file from Zac’s course boots up the development environment, allowing you to test your first blocks much faster

Zac’s course covers the most typical blocks, explaining them step by step and giving viewers some solid fundamentals on coding for Gutenberg.

After taking the course, Kostas feels more confident with creating new blocks. While he doesn’t use React in his code, he admits that knowing React helps a lot. Zac Gordon agrees with the utility of React:

“I’m really glad that I learned React, all the ES 6/7/8 and stuff, because knowing that when you open up Gutenberg, it’s so clean. It’s just a beautiful React. It’s so nice, it’s well architected, all these conventions are followed. You could literally copy and paste chunks of code from core into your blocks and it works.”

Zac Gordon about React

After taking this online course, Kostas’ skepticism recedes and is gradually replaced with excitement. It is high time for him to turn the first Toolset shortcodes into Gutenberg blocks!

First Toolset blocks appear on the horizon

In February 2018 the first two Toolset shortcodes are turned into blocks. The figure below shows how the Views shortcode has evolved into a dynamic block.

If you are new to Toolset, think about a View as a custom WordPress query you create using the user interface. The View will output a set of posts meeting certain criteria, for example, “3 random books from the Education category.” You can then insert this View anywhere in your WordPress site.

The screenshots below show how this View is inserted into a page as shortcode in the classic editor (left) and as a block in the Gutenberg editor (right).

Inserting View as a shortcode
Inserting View as a shortcode

Inserting View as a dynamic block
Inserting View as a dynamic block

Testing with users

At the same time as blocks are beginning to be used, Matt Cromwell, the lead admin of the WordPress Advanced Facebook Group, launches a series of Gutenberg interviews. In one of them Tammie Lister, a WordPress core contributor and UX Designer at Automattic, explains how developing a plugin in the open source environment helps create a product users actually need instead of developing a product a designer thinks they need.

“It’s important to me not to design in our bubble. I could detach myself from Slack if I need a couple of hours to design but if I design in isolation and put myself in a tower and I don’t have any interactions and I’m not giving myself fuel to be able to come up with the design that’s going to work for users.”

– Tammie Lister

Tammie Lister explains how developing a plugin in the open source environment helps create a product users actually need
Tammie Lister explains how developing a plugin in the open source environment helps create a product users actually need, source:

The Toolset team shares Tammie’s opinion, and they release the first beta plugins with Gutenberg support even though the blocks are not ideal. The feedback received from Toolset customers seems to be positive and helps detect some further compatibility issues.

But what does it actually mean for a plugin to be “Gutenberg compatible”?

What it means to adapt a plugin for Gutenberg

Over the past several months Gutenberg’s situation has changed dramatically. Today, more and more developers are exchanging knowledge and sharing their experiences.

In March 2018 Daniel Bachhuber, a WordPress core contributor, launches a plugin compatibility database, which turns out to be another game changer. Finally, someone from the Gutenberg core team is explaining in a clear and straightforward way what it means for a plugin to be Gutenberg compatible.

The README file, which accompanies the database, reads:

A plugin is compatible with Gutenberg when:

  • A WordPress user can perform the same functional task with Gutenberg active. For instance, if the plugin includes an “Add Media” button, it’s considered Gutenberg-compatible when it has a block registered for the Gutenberg inserter. Feature-parity, essentially.
  • There are no (obvious) errors when the WordPress plugin is active alongside Gutenberg.

Around the same time, also in March 2018, another Gutenberg core developer, Grzegorz Zielinski, gives a Gutenberg-related talk at a local WordPress meetup in Poland.

Grzegorz Zieliński, Gutenberg core developer, speaking about Gutenberg at a WordPress meetup in Poland
Grzegorz Zieliński, Gutenberg core developer, speaking about Gutenberg at a WordPress meetup in Poland

He shares some good practices for creating custom blocks. I (Agnes Bury) attend the meetup and collect some valuable takeaways to share with the Toolset team.

“Grzegorz explained that how your custom block looks in your WordPress backend should reflect what the user will eventually see on the frontend. The idea is to prevent switching forth and back between the editor and the preview of your post. The editor is supposed to be your preview.”

Suddenly, it has become obvious what user interface unification means in practice. Mel Choice, the WordPress core contributor and product designer at Automattic, explains the roles of a block in interface unification in her February 2018 “Customizing the Future” talk at Loop Conf:

“Once you learn how to work with one block, you know how to work with all blocks.”

She also shares a preview of the first block provided by the WooCommerce team along with a link to the github where you can see how the Products block looks under the hood.

The best part of Mel’s presentation is her use of templates and demonstration of the power of placeholders, as shown in the screenshot below.

Mel Choice explains the roles of a block in interface unification
Mel Choice explains the roles of a block in interface unification, source:

Refining our plans

Enriched with new knowledge, the Toolset team meets again to revise the Gutenberg support development plans.

Following Daniel Bachhuber’s suggestion, we identify all the additional buttons in the classic editor and begin turning these into blocks.

Toolset buttons in the classic editor that will disappear when you open a page in Gutenberg.
Toolset buttons in the classic editor that will disappear when you open a page in Gutenberg.

Considering Grzegorz Zielinski’s advice about the importance of the preview inside the backend, we also start thinking about more accurate representation of our block previews.

We also realized the importance of interface unification and that we need to eliminate the old pop-ups completely. Once a user starts editing in the new editor, they should only use Gutenberg’s interface and controls.

Inserting links
Inserting links – now

Inserting links in Gutenberg
Inserting links – plans

Last but not least, we are taking a closer look at the Gutenberg templates. One of Toolset plugins’ greatest features is the ability to build custom templates for post types directly from the WordPress backend, without PHP coding.

Adopting Gutenberg templates that allow end users to setup their content by filling out placeholders would be a great step forward.

Jakub Milczarek, a Toolset UX specialist, sees other benefits to Gutenberg as well:

“Having so many shortcodes in Toolset, it will take us a while to turn every single piece of our current UI into a Gutenberg block. But the good side is that adjusting for Gutenberg gives us the opportunity to review our current interface and unify it.”

Remaining issues

Our main goal is to focus on Gutenberg compatibility and ensure that, when Gutenberg becomes part of the WordPresas core, Toolset-based sites continue working without any major issues.

A few issues remain to work out. For example, inline shortcodes do not work as expected in Gutenberg.

The Gutenberg team is responsive and does not dismiss any feedback, and so we are confident that almost all critical issues will be resolved before Gutenberg migrates to the WordPress core.


When a big change nears, what scares people most is a lack of information. We are happy that the Gutenberg project is evolving not only in terms new iterations but, most importantly, in terms of growing documentation and the increasing sharing of know-how among the WordPress community.

There’s still much work to be done in Toolset plugins to allow our users to fully benefit from a better UX. Given the Gutenberg core team and WordPress community’s great support, we are positive that Gutenberg will have a bright WordPress future.