Theme Gutenberg Blocks

This is a boilerplate for adding multiple blocks within a theme. If you wish to add blocks to a plugin rather than via the theme please use Plugin Gutenberg Blocks.

Table of Contents

1. Directory Structure
2. Getting started
3. Customisation
   1. Webpack
   2. New Blocks
   3. Multiple vs Combined Block Asset Files
4. Build
5. TODO

Directory Structure

The following is the basic directory structure.

├── /blocks - All the custom blocks that will be automatically registered.
├── /build - Default directory that the block bundles get added to from the wp-script commands within the package.json.
├── /node_modules - Bundles.
├── /src - Contains the index.js file that is the source for the bundling commands, this automatically imports all the custom blocks from the /blocks directory, assuming they contain a index.js file.
├── /blocks-bootstrap.php - The PHP code that runs the WP functions to automatically register blocks from the /blocks directory. This uses glob patterns to autoload blocks, see New Blocks
├── /package.json - The package json.
├── /package-lock.json - The package json lock file.
├── /README.md - This file.
└── /webpack.config.js - The webpack configuration that extends on the node_modules/@wordpress/scripts/config/webpack.config.js Config.

Getting Started

This section details the beginning of the setup within your theme.

1. Place a copy of this directory within your theme, this example assumes that this directory will be placed at themes/xxx/source/gutenberg. If your case differs, please place it wherever is convenient and update the following bootstrap loader.
2. Update the functions.php file of your theme to include;

$theme_gutenberg_blocks_bootstrap_file = dirname( __FILE__ ) . '/source/gutenberg/blocks-bootstrap.php';

if ( file_exists( $theme_gutenberg_blocks_bootstrap_file ) ) {
    require_once $theme_gutenberg_blocks_bootstrap_file;
}

1. Navigate to the directory and run the commands.

cd wp-content/themes/xxx/source/gutenberg
npm install
npm run build

Customisation

From this point on we will refer to the directory themes/xxx/source/gutenberg as gutenberg. Within the gutenberg directory there are several customisations that can be done.

Webpack

The gutenberg/webpack.config.js file in this directory extends the default located here node_modules/@wordpress/scripts/config/webpack.config.js. Any additional webpack customisations that extend or overwrites the WordPress scripts default should go in this file.

New Blocks

within gutenberg/blocks directory lays all the custom blocks that will be bundled. The directory has, first-block, second-block and third-block. They can be renamed or removed, they are simply there to provide an example.

Every custom block will reside within their own directory within gutenberg/blocks directory. The format is as per WordPress current information(WP 5.9.3) see How-to Guides / Blocks. In this instance each block does not need any package bundler files as this is handled in the gutenberg root directory.

Required

Each block requires a directory of its own, named after its block, i.e. first-block. Within this directory the following files can be used;
└── /blocks
  └── /block-name
    ├── /args.php - Optional. Not a WordPress default. This is used within the bootstrap file when auto registering all the blocks. This is optional and can be removed. See register_block_type() @param $args.
    ├── /block.json - The settings and other metadata should be defined in a block.json file.
    ├── /edit.js - The edit functionality, which is a component that is shown in the editor when the block gets inserted.
    ├── /editor.scss - Contains any CSS code that gets applied to the editor.
    ├── /index.js - Registers a new block, combining asset files within said block directory.
    ├── /save.js - The save function defines the way in which the different attributes should be combined into the final markup, which is then serialized by the block editor into post_content.
    └── /style.scss - Applied both on the front of your site and in the editor.

Register the new block

That's it, the block will be auto registered based on the above files, and the block will be auto bundled next time the script is run from the this gutenberg root directory.

Multiple vs Combined Block Asset Files

Currently, the webpack file has a variable to change the way that the build is done. This variable is defined as multipleEntryPoint, which is a boolean and if its true the webpack builder will create asset files for each block and not combine them. One caveat with this is that the block.json file for each block needs to point at the correct asset files that are built.

The examples in this directory are using the multiple entry points, so each block has individual asset files, this can be seen within these lines;

{
  "editorScript": "file:../../build/first-block.js",
  "editorStyle": "file:../../build/first-block.css",
  "style": "file:../../build/style-first-block.css"
}

The opposite would be that multipleEntryPoint is set to false within the webpack.config.js file, then the block.json would have lines like this;

{
  "editorScript": "file:../../build/index.js",
  "editorStyle": "file:../../build/index.css",
  "style": "file:../../build/style-index.css"
}

Build

If your site runs a build on deploy, its advisable that you gitignore the ./build dir and add the script to your pipelines or similar build process.

TODO

The following would be nice to address at some point, and advice would be welcome.

• Find a way for the variable used within the webpack file could be globally set multipleEntryPoint, so that it's passed to the webpack.config.js for the entry points. In addition it would be used to automatically update the block.json files for each of the custom blocks, dictating the "editorScript", "editorStyle", and "style" keys.