WordPress: Project Gutenberg, Blocks and Custom Block Types

Minimal Block Example

The bare minimum required to add a block to the editor is to make a call to wp.blocks.registerBlockType() in some JavaScript run on the editor page:

wp.blocks.registerBlockType( 'bwawwp/minimal', {
  title: 'Minimal Block Example',
  category: 'common',
  edit() {
    return 'Minimal block editor content.';
  },
  save() {
    return 'Minimal block frontend content.';
  },
} );

The full docs and list of options can be found in the Block Registration section of the Block Editor Handbook.

Our minimal block passes in the name of the block and an array of arguments. Names must be unique and should be prefixed with the namespace or slug of the plugin loading the block. Names must start with a letter and can contain only lowercase letters, numbers, and dashes.

Our minimal block also passes in a title and category. The title can be any descriptive string, to help users find it in the block list. Later, we will cover how to add a new category to group related blocks. The categories included in core WordPress are common, formatting, layout, widgets, and embed.

The workhorses of the registerBlockType attributes are the edit and save attributes, for which we pass in functions to compute and return the structure of your block. You’ll use the edit function when the block is rendered in the editor (see Figure 11-2). The save function is used when the post is saved, before blocks are serialized into the post_content.

In the minimal block example, we just return a simple string. Note that any HTML included in these strings is going to be sanitized and converted into HTML entities. To generate markup with your blocks, you are going to have to use the wp.element.createElement() function.

Figure 11-2. Minimal block in the editor

We can build a plugin with just one folder, and two files to load our block:

• block.js

• minimal-block-example.php

Here is code for minimal-block-example.php that will enqueue this block.js file:

/**
 * Plugin Name: Minimal Block Example
 */
function enqueue_min_block() {
	wp_enqueue_script(
		'minimal-block',
		plugins_url( 'block.js', __FILE__ ),
		array( 'wp-blocks' )
	);
}
add_action( 'enqueue_block_editor_assets', 'enqueue_min_block' );

This is similar to how we enqueued other JavaScript in This Post. In this case, we are hooking into the enqueue_block_editor_assets action instead of the regular wp_enqueue_scripts action. Note also that our block JavaScript has wp-blocks as a dependency. As we add functionality to our blocks, we will need to include other Gutenberg-related packages here.

From here, return to the docs at WordPress.org and go through the “Writing Your First Block Type” tutorial. This covers adding styles, using editable fields, adding toolbars and settings, and creating dynamic blocks that update on the fly.

Enabling the Block Editor in Your CPTs

As of WordPress 5.3, CPTs will default to using the Classic Editor. At some point, all CPTs may be forced into using the new block editor. For now, to enable the block editor in your CPTs, say so explicitly when registering your CPT.

Here is the homework CPT example again, this time with the settings to use the block editor:

register_post_type(
	'homework',
	array(
		'labels' => array(
			'name' => __( 'Homework' ),
			'singular_name' => __( 'Homework' )
		),
		'public' => true,
		'has_archive' => true,
        'supports' => array( 'title', 'editor' ), // New
        'show_in_rest' => true,          // New
	)
);

The property 'supports' => array( 'title', 'editor' ) adds support for the title field and the block editor. Since the block editor uses the REST API to update posts, we need to also add REST API support by adding 'show_in_rest' => true.

Block Categories

When you’re adding multiple related blocks, it is helpful to put them into the same category so they will appear together in the block list. Setting the category of a block is as simple as changing the category attribute in the registerBlockType() arguments in your block JavaScript. WordPress needs to know about the new block category, though. To do that, use the block_categories filter:

// Add a Homework block category.
function my_block_categories( $categories, $post ) {
	return array_merge(
		$categories,
		array(
			array(
				'slug'  => 'homework',
				'title' => 'Homework',
			),
		)
	);
}
add_filter( 'block_categories', 'my_block_categories' ), 10, 2 );

Each category in the array of $categories is an array with two keys: slug and title (see Figure 11-3).

Figure 11-3. The Homework Block Category with the Homework and Instructions blocks

The Homework Blocks

To support our homework app, we add a couple of blocks. The homework/instructions block will go at the top of our homework and include a due date set via block settings. Multiple homework/question blocks will go below. Each question block has a RichText field to enter the question and a question type set via the block settings. The question types could be true/false, multiple choice, or essay.

The full code for these blocks can be found in the Chapter 11 folder of this blog GitHub repository.

Limiting Blocks to Specific CPTs

We want our instructions and question blocks to be used only on posts with the homework post type. To accomplish this, we can add some code to check the post type of the current post being edited and unregister our post types if it’s not a homework post.

At the bottom of your block.js file, add the following code:

// Deregister instructions on non-homework posts.
wp.domReady( function() {
    if( wp.data.select('core/editor').getCurrentPostType() != 'homework' ) {
        wp.blocks.unregisterBlockType( 'homework/instructions' );
    }
});

The wp.domReady() function is similar to jQuery’s document.ready() function, waiting until the full page has loaded before running the code within it. We need to do this because the post type of the current post being edited won’t be available until then. This is why you need to unregister the block instead of checking the post type before registered. To use the wp.domReady() function, make sure your block JavaScript is enqueued with wp-dom-ready as a dependency.

The current post type is pulled out of the WordPress data module using the command wp.data.select('core/editor').getCurrentPostType(). To do this, make sure your block JavaScript is enqueued with wp-edit-post as a dependency.

Tons of useful information is available using similar methods listed in the Data Module Reference. For more on how the data module is built and how to set up your own data stores, check out the data package documentation.

Limiting CPTs to Specific Blocks

Earlier, we showed how to keep our blocks from being used in other post types. WordPress also provides a allowed_block_types filter. This can be used to allow only select block types across your whole site or network. Or you can check the post_type on the $post parameter passed in and allow only select block types when editing posts of that type.

The following code limits homework posts to using a select few core blocks along with our instructions and question blocks:

// Only allow certain blocks on homework posts.
function my_allowed_block_types( $allowed_blocks, $post ) {
    if ( $post->post_type == 'homework' ) {
        $allowed_blocks = array(
            'core/block',
            'core/image',
            'core/paragraph',
            'core/heading',
            'core/list',
            'homework/instructions',
            'homework/question',
        );
    }
    return $allowed_blocks;
}
add_filter( 'allowed_block_types', 'my_allowed_block_types', 10, 2);

By default $allowed_blocks is null, telling WordPress to allow all blocks. Since blocks are added in JavaScript, after all PHP has loaded, the filter can’t know what custom blocks will be added. But if you set a list of allowable blocks using code like that shown in the previous example, it will make sure only blocks in those list get loaded.

Block Templates

When you register a CPT, you can pass a template attribute that will specify a group of blocks to be added to new posts of that type by default. Here is a version of our callback to register the homework post type that defaults to an instructions block up top, followed by one true/false question and one essay question:

// Register the homework CPT.
register_homework_post_type(
	'homework',
	array(
		'labels' => array(
			'name' => __( 'Homework' ),
			'singular_name' => __( 'Homework' )
		),
		'public' => true,
		'has_archive' => true,
        'supports' => array( 'title', 'editor' ),
        'show_in_rest' => true,
        'template' => array(
            array( 'homework/instructions' ),
            array( 'homework/question',
				array( 'content' => 'True/false 1.',
					   'question_type' => 'true_false'
				)
			),
            array( 'homework/question',
				array( 'content' => 'Essay question.',
					   'question_type' => 'essay'
				)
			),
        )
	)
);

With the above code in place, new homework posts will use our template and start with the instructions block and a few question blocks already in place. You can click on each block to edit their content (Figure 11-4).

Figure 11-4. Default template for new homework posts

You can also add templates to core post types or other CPTs after they are registered, add templates in your block JavaScript, lock templates so they cannot be rearranged or deleted, and next templates. Read about this and more in the Block Templates section of the Block Editor Handbook.

Saving Block Data to Post Meta

By default, attributes on blocks are stored inside of specially formatted HTML comments in the post_content body. The instructions block looks something like this before being converted for the frontend:

<!-- wp:homework/instructions -->
<p class="wp-block-homework-instructions-content">Email me your answers.</p>
<p class="wp-block-homework-instructions-due_date">Due Date: 2020-11-01</p>
<!-- /wp:homework/instructions -->

If our block is configured correctly, the content and due date are editable from the block editor and settings panel for those blocks. And things will then show up on the frontend of the website.

However, we might want to be able to sort homework assignments by due date or develop other reports around data set in our blocks. This is the kind of thing that would be possible if that data were stored in post meta.

To link block attributes to post meta, we need to register our post meta fields. We don’t always register post meta. You can just call the update_post_meta() function directly and add any data you want. However, when manipulating post meta through the REST API, we need to register it:

register_post_meta( 'homework', '_homework_due_date', array(
    'show_in_rest' => true,
    'single' => true,
    'type' => 'string',
    'auth_callback' => function() {
        return current_user_can( 'edit_posts' );
    }
) );

Now we can simply set the source in the block attribute to link to our post meta:

wp.blocks.registerBlockType( 'homework/instructions', {
	// ...

	attributes: {
	    content: {
	        type: 'array',
	        source: 'children',
	        selector: 'p',
	    },
	    due_date: {
	        type: 'string',
	        meta: '_homework_due_date',
	        source: 'meta',
	        default: '',
	    }
	},

	// ...
}

You can find more details on how to edit post meta through blocks in the “Store Post Meta with a Block” tutorial in the Block Editor Handbook.

Enable WP_SCRIPT_DEBUG

By default, WordPress will use minimized JavaScript and bundle all of its JavaScript into one file. This makes JavaScript errors in the console largely unusable. While doing any kind of JavaScript development, but especially when working with Gutenberg, you will want to enable WP_SCRIPT_DEBUG.

Adding define( 'WP_SCRIPT_DEBUG', true ); to your wp-config.php file tells WordPress to use unminimized versions of scripts and load all JavaScript files individually. This way, errors in the debug bar console will point to useful filenames and line numbers that you can cross-reference in your codebase.

Use filemtime() for the Script Version

When you enqueue JavaScript, you can set a version. Because browsers will aggressively cache JavaScript files, you can update the version of the script to break that cache. When working on your JavaScript files, you are going to be editing and updating them a lot. Setting the version to the last modified date of the underlying file is one way to keep your browser from caching that JavaScript file while working on it.

Here is a version of the code to enqueue the question blocks that uses the filemtime() function for the script version:

wp_register_script(
    'homework-question',
    BWAWWP_URL . 'homework-cpt/blocks/question/blocks.js',
    array( 'wp-blocks',
		   'wp-element',
		   'wp-editor',
		   'wp-components',
		   'wp-dom-ready',
		   'wp-edit-post',
	),
    filemtime( BWAWWP_DIR . 'homework-cpt/blocks/question/blocks.js' )
);

Before you deploy this code in the form of a plugin, you’ll want to update the version of the script to be the version number of the plugin or a specific version number for the script.

More Tips

Zac Gordon’s “31 Tips for Gutenberg Development” includes some great tips and also direction into advanced topics in block development.

Learn JavaScript, Node.js, and React More Deeply

Learning vanilla JavaScript, Node.js, and React more deeply will help you with your WordPress block development. At the very least, take some time to read up on, experiment with, and gain a general understanding of how each of these technologies works. You’ll find that debugging issues with Gutenberg development is much easier if you can better tell which layer of your stack the issue is coming from:

JavaScript

We cover JavaScript and its history with WordPress in This Blog. The stronger your JavaScript skills, the easier you will find it to develop blocks. JavaScript: The Definitive Guide, by David Flanagan, and JavaScript: The Good Parts, by Douglas Crockford, are two great books for learning JavaScript. You can browse them to pick up the basics and use them for reference or dive into them to “learn JavaScript deeply.”

Node.js*

Node.js is a JavaScript runtime that will run in your server environment. Several Node.js-based tools are used in the typical Gutenberg build setup, including webpack, Babel, and the Node Package Manager (npm). Webpack is used to compile all your JavaScript into a single bundle to be deployed to the browser. Babel is used to convert ESNext and JSX code into JavaScript that will run across the widest range of browsers. The npm is used to install JavaScript packages and manage the dependencies between them. Both webpack and Babel are typically installed as node modules. You may also want to use additional node libraries in the JavaScript code for your blocks. You can install and manage those via npm. The “JavaScript Build Setup” section of the Block Editor Handbook will walk you through installing node and npm, then installing the @wordpress/scripts package, which includes the recommended default configurations for webpack and Babel.

React

We give a full description of React in This Blog. In summary, React is a JavaScript library for building interactive UIs that is used extensively in the block editor screens. A WordPress block can be viewed as a collection of React UI components designed to serve a common editor or content style use case. WordPress has its own library of React components specific for building blocks. These can be combined with other React components or custom developed components. Experimenting with React outside the context of building a Gutenberg block will help you to get familiar with React in general. When you run into issues building WordPress blocks, you will be better equipped to know if those issues are React issues or WordPress issues, which will help you to know where to go for help. If you’d like to dive deep into React, check out the book Learning React, by Alex Banks and Eve Porcello. Just going through the official tutorial on the React website or one of the other examples there will be very useful as well.