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.
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.
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
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).
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.
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.
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).