Welcome to Code Gutenberg. This is an introduction post for the new WordPress 5.0, Gutenberg update.
To begin in a simple manner, let’s make a gutenberg block type that will display a message in the wordpress post. This is just the bare basics to register a block and show a styled block on the front-end without the functionality of editing the block itself dynamically, so we won’t be able to edit the message from the back-end. We’ll get deeper in the editable fields on a later section.
Let’s get started
“Learning to build block types”
On the first learning step we will keep things simple.
Block types in WordPress Gutenberg that have static content are implemented in JavaScript using the registerBlockType
function. The function will specify the frame of a block, we describe how the block will behave so the editor will understand how it displays, how it will change when we edit it, and how the content is saved in the wordpress post.
Enqueuing Block Scripts
The way a block will behave is as we said implemented with javascript, you need to register the block server-side so that the code will run, so we need to enqueue your scripts. Register scripts and styles using wp_register_script
and wp_register_style
, then assign these as handles associated with your block using the script
, style
, editor_script
, and editor_style
block type registration settings. The editor_
-prefixed handles will only be enqueued in the context of the editor, while script
and style
will be enqueued both in the editor and when viewing a post on the front of your site.
<?php function gutenberg_boilerplate_block() { wp_register_script( 'gutenberg-boilerplate-es5-step01', plugins_url( 'step-01/block.js', __FILE__ ), array( 'wp-blocks', 'wp-element' ) ); register_block_type( 'gutenberg-boilerplate-es5/hello-world-step-01', array( 'editor_script' => 'gutenberg-boilerplate-es5-step01', ) ); } add_action( 'init', 'gutenberg_boilerplate_block' );
Note the two script dependencies:
wp-blocks
includes block type registration and related functionswp-element
includes the WordPress Element abstraction for describing the structure of your blocks
If you were to use a component from the wp-editor
package, for example the RichText component, you would also need to add wp-editor
to the dependency list.
Registering the Block
With the script enqueued, let’s look at the implementation of the block itself:
var el = wp.element.createElement, registerBlockType = wp.blocks.registerBlockType, blockStyle = { backgroundColor: '#900', color: '#fff', padding: '20px' }; registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-01', { title: 'Hello World (Step 1)', icon: 'universal-access-alt', category: 'layout', edit: function() { return el( 'p', { style: blockStyle }, 'Hello editor.' ); }, save: function() { return el( 'p', { style: blockStyle }, 'Hello saved content.' ); }, } );
const { registerBlockType } = wp.blocks; const blockStyle = { backgroundColor: '#900', color: '#fff', padding: '20px' }; registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-01', { title: 'Hello World (Step 1)', icon: 'universal-access-alt', category: 'layout', edit() { return <p style={ blockStyle }>Hello editor.</p>; }, save() { return <p style={ blockStyle }>Hello saved content.</p>; }, } );
Once a block is registered, you should immediately see that it becomes available as an option in the editor inserter dialog, using values from title
, icon
, and category
to organize its display. You can choose an icon from any included in the built-in Dashicons icon set, or provide a custom svg element.
A block name must be prefixed with a namespace specific to your plugin. This helps prevent conflicts when more than one plugin registers a block with the same name.
The edit
and save
functions describe the structure of your block in the context of the editor and the saved content respectively. While the difference is not obvious in this simple example, in the following sections we’ll explore how these are used to enable customization of the block in the editor preview.