As I announced last week, I decided to start with the Gutenberg (Block Editor) blocks development, exploring the process from the very beginning and trying to do it all with the help of the official WordPress Blocks Documentation.
My goal, for now, is to learn how to convert existing shortcodes (and maybe widgets) into blocks. Most of my plugins have both shortcodes and widgets, and making them into blocks will be very important from now on. This process should be a simpler way of block migration because it will rely on the server-side rendering that already exists for the shortcodes (and widgets), but it will require creating a settings interface for each new block.
I am starting all this as someone who has 12+ years of experience in developing for WordPress, 15+ years of experience with PHP, with 250+ plugins and themes I created over the years. I do use a lot of JavaScript in my plugins (mostly based on jQuery, but recently trying to working more without jQuery). When it comes to React, Webpack, and related technologies, I am almost a complete novice, and I had to start from basics when it comes to setting things up. Last year I did try create-guten-block package, but that package is now mostly abandoned, and it is recommended in few places not to use it due to all the changes Gutenberg has undergone in the past two years.
Last week, I released a free plugin ArchivesPress, and that plugin contains 3 shortcodes. So, the idea for this learning stage is to work with this plugin and add blocks for each of the shortcodes and mirror all shortcodes attributes into settings for blocks to show in the editor sidebar.
The Handbook
I have started by going through the Block Editor Handbook to read more about the requirements for the development environment, structure for the project, and other basic things. Handbook is huge, and it has a lot of information, and it does have a nice structure, starting the basics (that includes the development environment and starting with block development), followed by various how-to guides, references, and more.
But, there are many issues with the Handbook that make it impossible to create anything beyond basic plugins and blocks. I will list the issues a bit later. The first goal was to use the Handbook to create a new plugin and a block.
Create Block Package
The first step is to set up the environment to use for development. I have skipped all that because I already have Node and other of its elements needed, and I use Laragon for a local webserver. So, the next step is creating a new plugin using the @wordpress/create-block package. Using this package will prepare the full plugin project, and you will end up with the functional plugin that adds a single block. But, once everything is prepared, you will end up with about 450MB (yes, 450 MEGA Bytes) of Node libraries with all the dependencies stored inside the plugin. Many of the dependencies I have already installed as Node global modules, but the installer will add everything inside the local node_modules directory, taking a lot of space. If you need to have few plugins with blocks, it will be a huge waste of space. If there is a way to avoid that, I have not found it anywhere.
More Guides and References
Creating plugin and block is easy, but you will end up with an overwhelming source of information that is mostly thrown together without any order when you go through many of the how-to guides. Many of these guides contain vague information that doesn’t really help when you are starting. The first set of guides is about JavaScript. It is really the only thing useful when starting with all this because it has a lot of useful information, including explanations of the block creation package and Node commands.
This is part of the Handbook that I ended up checking out often, and it includes a lot of useful information about various block-related components and packages, settings for components and controls (and that is essential when you need to set up the sidebar settings).
The Internet
Yeah, the plan to rely on the Handbook has failed. There is no way to create anything useful by going with the Handbook only. So, here are few websites I have found that had good information.
- WordPress Gutenberg: wp-gb.com – Why the content of this website is not part of the Handbook is beyond me. It shows all sorts of components and elements for use inside the block for various purposes, with accompanying examples and screenshots for each component.
- Gutenberg Hub: gutenberghub.com – It maintains a long list of excellent tutorials and examples, and some of the resources linked there helped me a lot with the organization of my plugin and elements the blocks needed.
- Reddit and StackOverflow – Yeah, for random Google searches (and I did use Google a lot during this whole process), both websites had plenty of helpful tips and small examples that helped me with some of the issues I had.
The Issues
As I said in the beginning, my goal was to create simple blocks that are mostly mirror components for exiting shortcodes and widgets. I don’t have experience with the React/JS development Gutenberg is based on, and to solve the task I had, my significant experience with WordPress made no difference when it comes to getting started with blocks development. While some elements of the Handbook are great and helpful, I have found it impossible to do what I wanted to do from the start: add blocks to a plugin and base those blocks mostly on the server-side rendering to reuse existing shortcodes code as much as possible.
No way to create a plugin that contains more than one block
The @wordpress/create-block package is made to create a plugin with a single block, and it uses a directory structure that is very impractical for expansion. The Handbook doesn’t contain any information on how to expand the created plugin to include more than one block. The support forum had questions about this very issue, but the ‘solution’ was not helpful and vague.
I have spent hours trying to find more information about the process, running few different tests with multiple generated plugins to get the structure that works for the case of multiple blocks in a single plugin. And, the Handbook has no information at all about that.
If the plugin was created with the @wordpress/create-block package, it is reasonable to expect that this package can either have the option to generate a plugin with two or more blocks or be able to modify once created basic plugin and add additional blocks.
No way to add block(s) into the existing plugin
The @wordpress/create-block can create only a new plugin, I have not found any way to run it inside the existing plugin to expand the plugin with the blocks support. My process was to create a dummy plugin with @wordpress/create-block, with the same name as my plugin (archivespress), and then copy package information files, modules, source and build directories into my plugin folder, and adjust few other things to merge the two.
There are no comprehensive examples of common plugin/block types
If the plan with Gutenberg is to have the Blocks as a replacement for both widgets and shortcodes, then, the official Gutenberg project has to have at least a few fully realized examples and detailed tutorials on how to convert shortcode to block and how to convert widget to block. While there are some examples available, I have found all of them extremely lacking and I was not able to use any of them for what I needed.
The basic plugin doesn’t include every important package
Because the plugin created with the @wordpress/create-block package is so basic, it only has a few core Gutenberg packages included. And, if you need more, you need to know how to include additional packages. A demo plugin like this would be better to include all the dependencies (few extra packages don’t make much difference when the modules directory is close to 500MB in size already) and remove what is not needed the individual blocks. For developers with limited experience when it comes to Node packages, the whole process can be complicated at first. Because of this, having good examples is important, because it can show how to better use packages to do some specific tasks.
The Results
Yes, I did manage to create blocks for my plugin, and, considering this was my first real attempt at doing this, even with spending much more time on this than I planned, it turned out rather well. I have used the @wordpress/create-block created plugin as a starting point, but with few changes to the structure and different block registration methods, I ended up with the new files structure that worked rather well for my case. And, the whole process is not too difficult to do, and the lack of proper examples and tutorials for beginners is the main problem with the whole thing. I spent a total of 4 days that included research, testing, trying things. And, when I finally found the combination that was working, the whole process went surprisingly quickly.
Because of what I had to go through to make this, knowing that a lot of WordPress developers will need to convert shortcodes into blocks, I have decided to write an in-depth tutorial for the process and publish a boilerplate plugin on GitHub. The updated ArchivesPress 2.0 plugin will be released next week with 3 new shiny blocks and few other improvements, and the tutorial about the whole process will be published around the same time.
Let me know about your first experiences with block creation, and what issues you encountered (and how did you managed to solve them).