This is a part of series of tutorials called: Building blocks of the building blocks.
WP-CLI scaffold
WP CLI is one of my favorite tools. This is the tool I use to show off WordPress in front of other PHP kids. The scaffold command is particularly helpful for developers. With one command you can create a plugin, standalone or child theme, tests, post type and taxonomy, and of course, block.
At this moment scaffold command generates code that is a bit out of date but nevertheless, very useful in saving time and following WordPress Coding Standards.
WP-CLI’s documentation for scaffold command suggests that block slug is the only required parameter but it’s not. Running command with only slug defined will return the error. WP-CLI doesn’t care from which folder in project you run commands, as long as you are inside project – I usually do it from WordPress root folder.
wp scaffold block wpcli-block
Error: No plugin or theme selected.I really love this about WP-CLI. It allows me to create blocks in plugin, standalone theme or child theme. Not all tools are this generous.
Theme block
To create block in currently active theme this is all we need:
wp scaffold block wpcli-block --theme
Success: Created block 'Wpcli block'.To build blocks in specific themes, all you have to do is to define theme slug for --theme parameter.
wp scaffold block wpcli-block --theme=twentynineteenOf course, there are other parameters for more customised starting setup. I recommend testing them out.
My currently active theme was Twentytwenty and now it has a new folder blocks. This is found inside:
twentytwenty/
└── blocks/
├── wpcli-block/
│ ├── editor.css
│ ├── index.js
│ └── style.css
└── wpcli-block.phpIn order to get this block working, we need to include blocks/wpcli-block.php file in theme’s functions.php. The block can be found in the Widgets category.
include_once get_template_directory() . '/blocks/wpcli-block.php';Plugin block
Process for building blocks in plugins is almost the same as for themes. Specify plugin’s slug.
wp scaffold block wpcli-plugin-block --plugin=wpcli-block
Error: Can't find 'wpcli-block' plugin.But you need to have a plugin with that name in your plugins directory. Having only an empty folder won’t work because you need that main plugin PHP file for WordPress to know about your plugin existence and you need some place to include your block’s PHP file. The fastest way to do this is with WP-CLI.
wp scaffold plugin wpcli-block
Success: Created plugin files.
Success: Created test files.wp scaffold block wpcli-plugin-block --plugin=wpcli-block
Success: Created block 'Wpcli plugin block'.Now I have a new folder in my plugins directory. The structure is the same as in the theme:
wpcli-block/
└── blocks/
├── wpcli-plugin-block/
│ ├── editor.css
│ ├── index.js
│ └── style.css
└── wpcli-plugin-block.phpAnd now we need to include this PHP file in plugin’s main PHP file.
include_once __DIR__ . '/blocks/wpcli-plugin-block.php';This way you can build as many blocks in theme or plugin as you wish.
wp scaffold block wpcli-second-block --theme
Success: Created block 'Wpcli second block'.wp scaffold block wpcli-plugin-second-block --plugin=wpcli-block
Success: Created block 'Wpcli plugin second block'.Usability
I’m not gonna go into block anatomy now, there will be another tutorial just for that. However, I must say that few things about generated code bother me.
Code generated by WP-CLI uses browser-ready formats: CSS instead of SCSS and ES5 instead of ESNext. It doesn’t consider Webpack and Babel usage and, if you wish to use these, you have to do additional coding and converting. It’s easier to build the block manually from scratch. This really bothers me.
Another issue is that this code doesn’t work in child theme. You can use the scaffold command to generate blocks in child theme but the function used in registering assets in PHP file is for standalone and parent themes, not the child theme.
get_template_directory_uri() . "/blocks/$index_js"To be child theme friendly, instead of get_template_directory_uri() code should use get_stylesheet_directory_uri() or get_theme_file_uri().
get_stylesheet_directory_uri() . "/blocks/$index_js"get_theme_file_uri( "/blocks/$index_js" )PR for fixing this is merged into core WP-CLI and we can expect it in next release: https://github.com/wp-cli/scaffold-command/pull/242
Maintainer of WP-CLI, Alain Schlesser is, of course, aware of these issues and his focus for the future is improving scaffold command.
Useful links:
- This code on GitHub: https://github.com/zzap/Building-blocks-of-the-building-blocks/tree/01-building-block/wp-cli
- WP-CLI scaffold command: https://developer.wordpress.org/cli/commands/scaffold/block/
- Install WP-CLI: https://make.wordpress.org/cli/handbook/installing/