Gutenberg Boilerplate Demonstrates How to Build Custom Blocks

Gutenberg is still in beta but developers are already getting ready for creating their own custom blocks. Over the weekend Ahmad Awais released a new project called Gutenberg Boilerplate For Third-Party Custom Blocks. Awais’ introductory post includes a rundown of his thoughts on the current pros and cons of developing for the Gutenberg project. Although he appreciates the technology behind Gutenberg and the improvements over shortcodes, he is not fully sold on the concept of putting everything into blocks. To learn more, he decided to jump into the code.

“I am still making up my mind with how Gutenberg will fit in the WordPress core,” Awais said. “There are so many things which are both good and bad about it. So, instead of ranting about it, I wanted to do something more productive. I went ahead, studied the source code and received a lot of help from Gutenberg contributors (Matias Ventura, James Nylen, Riad Benguella, Andrew Duthie, Joen, etc.) to finally build a Gutenberg Boilerplate project.”

Awais’ Gutenberg Boilerplate is a good starting place for learning more of the basics about developing for the editor. It comes in the form of a plugin that offers four examples of how to build different kinds of custom Gutenberg blocks, with and without a build process:

  • A block with custom CSS for editor and front end
  • A block with ES6 or ESNext and a Webpack build process
  • A block with editable content
  • A block to click Tweet the contents of that block

For example, the tweet block, which is something that might previously been handled with a shortcode, is an example that includes four files: block.js to register the custom Gutenberg block, editor.css, style.css, and index.php.

Awais noticed that many developers were wanting to try building third-party blocks, but Gutenberg’s documentation for this was outdated and/or non-existent. He got involved in contributing to the project’s documentation after discovering the docs describing how to enqueue block and block editor assets were not available. This gave him the inspiration to create a boilerplate.

“Both as a theme/plugin developer, I think there’s going to be a steep learning curve here for just about everyone – users as well as developers,” Awais said. “WordPress development just became very complicated with the Gutenberg project. I’m also not sure how devs will start writing extensions. Some users might expect them to keep the shortcodes for the old editor. Some might ask for blocks in the new one. Is there an API or back-compat? In short everything is changing and this change has both pros and cons.”

These concerns also tie into the larger discussion around how Gutenberg can support legacy metaboxes that use the old PHP framework, instead of updating to the new JS.

“New metaboxes should be written in JS, and will appear in the Post Settings sidebar alongside the stock ones,” Gutenberg contributor Joen Asmussen said. “Metaboxes written in PHP should ideally be upgraded to be JS, but should continue to work in their PHP form also.” Asmussen has proposed an “Extended Settings” panel to house legacy metaboxes in a section below the editor. It would appear only when legacy plugins and metaboxes are enabled, as shown in the mockup below.

Discussion regarding how to support metaboxes is still ongoing. With so many important issues like this up in the air, it’s too early to know what the future of extending Gutenberg will look like. At the moment, the project is undergoing rapid development and changes, so extending Gutenberg may evolve drastically over a short period of time. If the editor is to preserve the same flexibility and customization opportunities of its predecessor, the project will need to ensure that it is easy to create custom blocks and extensions while continuing to support older PHP metabox infrastructure that is currently widely used.

16 Comments


  1. This is great. However, this kind of worries me:

    “WordPress development just became very complicated with the Gutenberg project. I’m also not sure how devs will start writing extensions. Some users might expect them to keep the shortcodes for the old editor. Some might ask for blocks in the new one. Is there an API or back-compat? In short everything is changing and this change has both pros and cons.”

    This feels like something that should be defined by now by the project leads. Not implemented but things like “is there an API, is there backward compatibility” should be known even if something isn’t targeted as a 1.0 release feature.

    Report


    1. I agree with you on that!

      Get involved raise a few converns and contribute back to make them go away!

      Report


  2. “WordPress development just became very complicated with the Gutenberg project

    This is exactly what so many people were concerned about then a small set of developers were promoting the use of React _(vs. Vue)_ when they said “But what we choose will only affect the core developers.” I am paraphrasing, of course.

    Report


    1. It’s a scary thing to consider that developers might find using React with something like Laravel more easier than with WordPress. Remeber what happned with Drupal 8.0?

      Report


      1. Just read it. I completely agree with you on that. I know for a fact — that’s what happened!

        Report


  3. Thank you, Sarah — for covering the Gutenberg Boilerplate here!

    Everyone, I want to let you know that Gutenberg Boilerplate needs more reviewers and contributors. If you want to get into Gutenberg development, it’s the high time to do that.

    And if you’re just interested in keeping up with this project then Star the repository to show appreciation and watch it to keep up with the updates :)

    Here’s the link: https://github.com/ahmadawais/Gutenberg-Boilerplate/

    Report


    1. Everyone, I want to let you know that Gutenberg Boilerplate needs more reviewers and contributors.

      Instead of trying to get more people to use and test it, perhaps it is an idea to abandon the project altogether?

      If you want to get into Gutenberg development, it’s the high time to do that.

      People quite obviously don’t care about Gutenberg and certainly don’t want anything that complicates future development.

      And now with the issue about React not having the right license (see WP Tavern post https://wptavern.com/?p=73216), I think it is time to abandon ship. In a few months time, people will have forgotten that a few weeks were wasted on something that was unnecessary from the get-go!

      Report


      1. Are you suggesting he abandons the boilerplate documentation, or that gutenberg itself should be abandoned?

        In the case of the latter, I’m sorry to say that wordpress will almost definitely replace the current editor with gutenberg in a future version, the people at wordpress are very keen on that. Barring any great disaster this will happen sooner rather than later, so better that we jump on the bandwagon now and make it as good as it can be. And initiatives like this are very helpful to make it approachable to people that aren’t in the gutenberg inner circle right now. So good job Ahmad!

        Also, a ‘few weeks’? Gutenberg has been in development for 6 months now.

        Report


      2. Thanks for that, Tim!

        @George — IMHO if you’re not there to talk about your concerns (instead of just writing it off on WPT comments) how else do you think they will get addressed?

        Report


      3. @Tim – Honestly, I think it’s a mistake to flat out replace TinyMCE with Gutenberg. Users/Developers need to be given the choice which one they want to use.

        I liken it to Microsoft’s huge mistake with forcing the Metro UI onto people with Windows 8 without offering them the choice to use Aero (Windows 7’s interface). As a result, Windows 8 adoption after 12 months was a hair short of 50% of Windows 7.

        When you force such a fundamental change on people, you risk them re-evaluating their options. They may either opt to not upgrade WordPress or move to a different solution.

        Report


  4. This type of fundamental change should really become a plugin or a fork of WP, not stuffed into core. Sad!

    Report


    1. I’d tend to agree considering there’s little to be done in regards to the additional WP editor experience fragmentation that Gutenberg will create anyhow.

      I see WP development falling into 3 categories (at least)…

      1) Become aware of whether you’re running on a system with the old TinyMCE or new Gutenberg and act accordingly. If it’s a plugin that can dynamically alter this fact, that further complicates things but only slightly.

      2) Offer separate v4.x and v5.0 versions.

      3) Stop development of the older v4.x branch versions and only develop v5.x going forward even at the expense of lost users.

      Report


    2. I’ve been thinking a lot about this and there’s actually some precedent on how to handle this. Personally I always use the text editor in tinyMCE, so much that I often click the “Disable the visual editor when writing” option on the profile page. I think a similar solution could work. By default new installs get Gutenberg, but you have a profile option to use the legacy editor. Maybe even a global setting to set legacy for all new users (or even all users). Something along these lines is probably the closest we’ll get to the best of both worlds.

      Report


  5. So is the normal PHP way to create meta boxes going away? That’s going to be a huge problem for me, having used that in dozens of client websites, for all kinds of extra custom fields. How am I going to fix all those sites breaking when this is released? This can’t be true.

    I’m absolutely no Js developer so rewriting it in Javascript will be a big problem. And I don’t want to think about how clients are going to react to this, obviously they aren’t eager to pay a lot of money to have me fix a problem that wasn’t there before.

    Really scared about the direction WordPress is developing. It has always been the best option but the future looks dark.

    Report


  6. Thank you for putting this together Ahmad! I’ve been curious how easy it will be to create custom blocks.

    I’m glad to see some thought has been given to standard PHP meta boxes with this “Extended Settings” mock up. Not ideal but workable.

    One use case I still haven’t seen addressed however is when you have a custom post type that doesn’t require a WYSIWYG editor at all or at least a much less prominent one. This is not uncommon at all in custom work – take for example a store post type for a store locator. Has anyone see discussion on this topic?

    Report

Comments are closed.