Develop Custom Gutenberg Block Using ES5 Syntax – Gutenberg Block Development
access_timepersonjunaidte14folderTech, Wordpress

WordPress released a new post/page editor i.e. Gutenberg Editor also known as Block Editor in version 5.0 which improves the post/page development. The editor consists of some built-in blocks which can be used to add different type of content in post/page. In this post, we will discuss how to develop a custom Gutenberg block using ES5 syntax.

ES5 Syntax?

Gutenberg blocks/ WordPress blocks can be developed either using the ESNext (JavaScript code written using the features provided in JavaScript version greater than ES5 i.e ECMAScript5) or ES5 (ECMAScript5) syntax. Most browsers do not understand the code written using ESNext syntax that’s why the code written using ESNext syntax need to be compiled to ES5 thus requiring an extra step. To learn more about ESNext and how to develop WordPress/ Gutenberg blocks using ESNext syntax, please visit our other blog post.

Custom Gutenberg Block Development

Let’s get started with the custom Gutenberg block development. We will create a WordPress plugin which upon activation, will register our custom Gutenberg block. We will create a simple Gutenberg block which will add colored lines with custom width (in %), height (in px), color (hex code using color picker and with default color options).

Step 1: WordPress Plugin For Gutenberg Block

First of all we will create a new WordPress Plugin which will contain the code and logic of our custom Gutenberg block. Upon, activation, the plugin will register our block and will en-queue the styles and scripts required for our custom Gutenberg block.

Create a new folder (for WordPress plugin) in WordPress Files -> wp-content -> plugins and name it anything like custom-wp-block. Create a new file in that folder and name it as custom-wp-block.php and add following code in it. 

<?php
/**
 * Plugin Name: Custom Wp Block
 * Plugin URI: https://codoplex.com/
 * Description: A custom WordPress/Gutenberg block developed by Codoplex.
 * Author: Junaid Hassan
 * Author URI: https://codoplex.com/
 * Version: 1.0.0
 * License: GPL2+
 * License URI: https://www.gnu.org/licenses/gpl-2.0.txt
 *
 * @package customwpblock
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

The above code defines the meta information for the plugin and many other functions related to the WordPress plugin management. Now if you visit the WordPress Dashboard -> plugins, you can view and activate the Custom Wp Block plugin. To learn more about WordPress plugin development, please visit our blog post about how to develop custom WordPress plugin from scratch using OOP and WordPress plugin development cheat sheet.

Step 2: Register and En-Queue Styles and Scripts For Custom Gutenberg Block

In this step we will register and en-queue styles and scripts for our custom Gutenberg block using hooks for WordPress editor (used to display styles and scripts only in WordPress editor) and front-end of the website. WordPress editor hook (enqueue_block_editor_assets) is used to display styles and scripts only in WordPress editor whereas the the front-end hook (enqueue_block_assets) is used to display styles and scripts only on front-end side of the website. At the bottom of the custom-wp-block.php, add following code.

// Hook: Editor assets.
add_action( 'enqueue_block_editor_assets', 'customwpblock_colored_lines_editor_assets' );

/**
 * Enqueue the block's assets for the editor.
 *
 * `wp-blocks`: includes block type registration and related functions.
 * `wp-element`: includes the WordPress Element abstraction for describing the structure of your blocks.
 * `wp-i18n`: To internationalize the block's text.
 *
 * @since 1.0.0
 */
function customwpblock_colored_lines_editor_assets() {
	// Scripts.
	wp_enqueue_script(
		'customwpblock-colored-lines', // Handle.
		plugins_url( 'block.js', __FILE__ ), // Block.js: We register the block here.
		array( 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-editor' ), // Dependencies, defined above.
		filemtime( plugin_dir_path( __FILE__ ) . 'block.js' ) // filemtime — Gets file modification time.
	);

	// Styles.
	wp_enqueue_style(
		'customwpblock-colored-lines-editor', // Handle.
		plugins_url( 'editor.css', __FILE__ ), // Block editor CSS.
		array( 'wp-edit-blocks' ), // Dependency to include the CSS after it.
		filemtime( plugin_dir_path( __FILE__ ) . 'editor.css' ) // filemtime — Gets file modification time.
	);
} // End function customwpblock_colored_lines_editor_assets().


// Hook: Frontend assets.
add_action( 'enqueue_block_assets', 'customwpblock_colored_lines_assets' );

/**
 * Enqueue the block's assets for the frontend.
 *
 * @since 1.0.0
 */
function customwpblock_colored_lines_assets() {
	// Styles.
	wp_enqueue_style(
		'customwpblock-colored-lines-frontend', // Handle.
		plugins_url( 'style.css', __FILE__ ), // Block frontend CSS.
		array( 'wp-blocks' ), // Dependency to include the CSS after it.
		filemtime( plugin_dir_path( __FILE__ ) . 'style.css' ) // filemtime — Gets file modification time.
	);
} // End function customwpblock_colored_lines_assets().

The above code registers/en-queue script file (block.js) which will contain the code and logic to register our custom Gutenberg block, style file (editor.css) which will contain CSS styles for the editor side of the custom Gutenberg block and another style file (style.css) which will contain CSS styles for the front-end display of the custom Gutenberg block. For now inside the plugin folder, create these 3 files i.e block.js, editor.css and style.css.

Step 3: Registering Custom Gutenberg Block

In this step, we will register our custom Gutenberg block with Gutenberg editor using the registerBlockType() function inside the block.js file. Inside the block.js file, add the following code.

( function(blocks, editor, element) {
	const __ = wp.i18n.__; // The __() for internationalization.
	const el = element.createElement; // The wp.element.createElement() function to create elements.
	const registerBlockType = blocks.registerBlockType; // The registerBlockType() to register blocks.

	registerBlockType( 'customwpblock/colored-lines', { // Block name. Block names must be string that contains a namespace prefix. Example: my-plugin/my-custom-block.
		title: __( 'Colored Lines', 'customwpblock' ), // Block title.
		icon: 'text', // Block icon from Dashicons → https://developer.wordpress.org/resource/dashicons/.
		category: 'common', // Block category — Group blocks together based on common traits E.g. common, formatting, layout widgets, embed.
		keywords: [ 'customwpblock', 'colored', 'lines' ], // keywords for custom block
		attributes: {}, //placeholders to store customized settings information about the block
		example: { // used to define default values for the attributes
			attributes: {},
		},
		// The "edit" property must be a valid function.
		edit: (function( props ) {
			const blockParentStyle = {
				width: '100%',
				padding: '0',
				marginTop: '0px',
				marginBottom: '0px',
			};
			const blockInnerStyle = {
				backgroundColor: "#FF7F50",
				width: '100%',
				height: '2px',
				display: 'inline-block',
			};

			return [
				el( 'div', { className: props.className },
					el( 'div', { className: 'customwpblock-colored-lines', style : blockParentStyle },
						el( 'span', {style : blockInnerStyle},
						)
					)
				)
			];
		}),

		// The "save" property must be specified and must be a valid function.
		save: function( props ) {

			const blockParentStyle = {
				width: '100%',
				padding: '0',
				marginTop: '0px',
				marginBottom: '0px',
			};
			const blockInnerStyle = {
				backgroundColor: "#FF7F50",
				width: '100%',
				height: '2px',
				display: 'inline-block',
			};
			return (
				el( 'div', { className: props.className }, // className property is automatically enabled for each block
					el( 'div', { className: 'customwpblock-colored-lines', style : blockParentStyle },
						el( 'span', {style : blockInnerStyle},
						)
					)
				)
			);
		},
	} );
})(window.wp.blocks,
    window.wp.editor,
	window.wp.element
);

The code is very well-documented and explained using the inline comments. The main parent function takes 3 packages (blocks, editor and element) as input arguments each exposing the relevant functions from the packages. the registerBlockType function registers the custom Gutenberg block (colored-lines) with the Gutenberg editor. The edit() function handles how the block will display inside the Gutenberg editor whereas the save() function describes how the block will be displayed on the front-end side of the website. The other code is explained using the inline comments, if you have any question then write in the comments and we will explain it.

Step 4: Styles of Custom Gutenberg Block

The style files i.e style.css and editor.css are used to change the appearance of the custom Gutenberg block on front-end and inside the Gutenberg editor respectively. For simplicity, we have left the files empty but you can experiment by defining different styles in these files.

Conclusion and Further Readings

In this blog post we have described the steps required to develop custom Gutenberg block using the ES5 syntax. At the moment, the block is static and we are not able to change the behavior of the block. Please visit following blog posts, to make the block dynamic by adding the functionality to change the alignment, width, height and color of the colored lines block.

Leave a Comment