Gutenberg block set up structure.

[ryanwelcher]

Is your enhancement related to a problem? Please describe.

The theme scaffold provides a very basic if slightly confusion structure for custom blocks. Currently there are two locations for the blocks; assets/js/blocks and includes/blocks. There is not much in the way of direction as to how to work with these directories.

Wordpress 5.5 introduced new API's for working with blocks and I think we should take this opportunity to both update the scaffold to use them and to standardize how we build blocks.

Describe the solution you'd like

The main API change that came with 5.5 was the introduction of block.json for defining a block type metadata and register_block_type_from_metatdata for registering blocks in PHP.

The register_block_type_from_metatdata functions first parameter is the path to the block.json file for this block which contains all of the metadata for the block.

For example:

{
	"name": "my-plugin/notice",
	"title": "Notice",
	"category": "text",
	"parent": [ "core/group" ],
	"icon": "star",
	"description": "Shows warning, error or success notices…",
	"keywords": [ "alert", "message" ],
	"textdomain": "my-plugin",
	"attributes": {
		"message": {
			"type": "string",
			"source": "html",
			"selector": ".message"
		}
	},
	"providesContext": {
		"my-plugin/message": "message"
	},
	"usesContext": [ "groupId" ],
	"supports": {
		"align": true,
		"lightBlockWrapper": true
	},
	"styles": [
		{ "name": "default", "label": "Default", "isDefault": true },
		{ "name": "other", "label": "Other" }
	],
	"example": {
		"attributes": {
			"message": "This is a notice!"
		}
	},
	"editorScript": "file:./build/index.js",
	"script": "file:./build/script.js",
	"editorStyle": "file:./build/index.css",
	"style": "file:./build/style.css"
}

The items in the above example should look familiar as they are many of the same items passed to registerBlockType on the JavaScript side.

The exciting part is this:

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

As it stands now, registering a dynamic block has two un-related steps:

1. Register the custom block in php using register_block_type
2. Register the custom block in JavaScript using registerBlockType and enqueue the related file.

If our blocks are only registered on the PHP using the new register_block_type_from_metatdata function , we can register blocks in a single step as this function automatically registers and enqueues the script/styles.

Build Changes

Instead of generating a single block-editor.js file that holds all of the code to register all of the blocks, we will need to add an entry points for JS and CSS to the config/webpack.settings.js file the represent the JS/CSS that would be loaded into th e block editor.

The register_block_type_from_metatdata also looks for an *.assets.php file to manage dependencies, as such we'll need to leverage either the @wordpress/scripts package or the DependencyExtractionPlugin see #185.

Directory Structure Changes

I propose that we remove the assets/js/blocks directory and place all custom blocks in includes/blocks/{block-name}.

includes/
    ->blocks/
        ->custom-block/
           block.json
           register.php
           register.js
           edit.js
           save.js
           props-shape.js
           inspector-controls.js
           markup.php

block.json
This file holds the meta data for the block.

register.php
This file is pulled into includes/blocks.php and holds the register_block_from_metadata call and the register_callback callback.

register.js
This file handles the JavaScript side of register a block and imports items from block.json as needed. This is the file that is targeted by the entrypoint in weback.

edit.js
Contains the Edit component for the block

save.js
Contains the Save component for the block.

props-shape.js
Contains the prop-types definitions for the block

inspector-controls.js
Contains the InspectorControl items for the block.

markup.php
This file contains the markup for the block that is rendered on the front end. It is used the register_callback in register.php

Additional context
There is an internal project for custom blocks that leverages a similar set up that will also provide a means for registering new blocks.