Oh, Gutenberg: the topic of so many developer and WordPress conversations in the past year.

Since Gutenberg itself is still in a constant state of flux, learning more about its inner workings definitely proves to be challenging as certain elements are deprecated or move around within the core library. However, here are some of the things I’ve gleaned from beginning to poke around that I thought others might find useful.

What is Gutenberg?

Blocks block blocks. Gutenberg is blocks. Gutenberg is a React couch with a WordPress slipcover over it. It’s the new iteration of the WYSIWYG editor for WordPress, which will lend itself to further customization and a different page-builder-except-totally-not experience within WordPress.

Right now, there are posts, pages, menus, widgets, the Customizer…our cup runneth over with options! Part of what it seems Gutenberg aims to do in the long game is to consolidate everything into block components while replacing the TinyMCE editor.

Getting Up & Running

Note: this post assumes you have a local WordPress install in place with a theme (I used Twenty Seventeen) with the Gutenberg plugin both installed and activated.

I used Ahmad Awais’ boilerplate to get up and running in order to create my own custom block. It assists in creating a foundational file structure and enqueuing the necessary JavaScript and stylesheets to be used so we’re already a few steps ahead of the game.

Two things to note before moving forward are:

• Prior to tweaking any code, I installed the “React Templates” as well as Babel packages in Sublime to assist in my syntax highlighting.
• How to use comments in JSX.

Creating Blocks

The JavaScript function that is used to create blocks is registerBlockType, is made available in the global scope and does all the work. Remember that blocks live within plugins. As they affect content, you will need it to remain active even if the theme changes.

// Imports and Variable assignments.
import './style.scss';
import './editor.scss';

const { __ } = wp.i18n; // Import __() from wp.i18n for translations
const { registerBlockType } = wp.blocks; // Import registerBlockType() from wp.blocks

registerBlockType( 'namespace/the-coolest-block', {
// ... All the stuff inside your block which is a big ol' JavaScript object
}

Within this function, the object that creates your block has three main sections:

1. An Attributes List
2. An “Edit” function
3. A “Save” function

Gutenberg Block Skeleton

registerBlockType( 'namespace/the-coolest-block', {
	// General Block Settings.
	title: 'The Coolest Block',
	icon: 'smiley',
	category: 'common',

	// List of Attributes
	attributes: {
		// What we can interact with.
	},

	// Edit Function.
	edit( { props } ) {
		return (
		     // What you want sent back to you.
		);
	},

	// Save Function.
	save( { props } ) {
		// ...
	},
}

List of Attributes

If you want your block to …well, do anything (like edit text), you have to use the attributes object, which is Gutenberg’s state management system. It’s a top level object that keeps track of properties and what has changed.

For each thing that you want to be editable, you’ll need a corresponding attribute. The block’s output is a function of its attributes. Attributes in Gutenberg track the present condition of data (state) in a block.

The ‘edit’ function

This is how the block looks behind-the-scenes in the Dashboard’s editor. The edit() function let’s you customize the interface. For those familiar with React, this is similar to the render() function.

Ideally, this is where you specify a return statement that has your JSX (JavaScript XML) within it.

The ‘save’ function

This is what your block looks like on the front-end. It defines the way the different attributes should be combined into the final markup. This is then serialized into post_content. This is apparently how backwards compatibility is maintained so your content will remain intact if Gutenberg is disabled.

Now what?

I’m going to continue my explorations by, fingers crossed, creating my own custom block with editable fields. Wish me luck!

Resources:

• WP Docs: Gutenberg Handbook
• Anatomy of a Custom Block: How Gutenberg Blocks Work
• WordPress.tv: Gutenberg-related talks