Kau-Boys

I’m currently on vacation and had some tech free days, so my blog post comes a bit later this week. In the previous post, I’ve shown you, how you can write a block without any ES6/React code. This week I want to show you the minimum you have to know to get the full potential of modern JavaScript while still keeping it simple.

Create a block with the “create-block” script

As I’ve also mentioned, that I would highly recommend using the create-block package to create your first little plugin. This will create a lot of files for you, and you are ready to go. We create the example from the last post by running this command in the wp-content/plugins folder:

npx @wordpress/create-block random-posts-server-side-render-block-es6

This will give you the following files in the newly created plugin directory:

$ tree
.
├── node_modules
├── package.json
├── random-posts-server-side-render-block-es6.php
├── readme.txt
└── src
    ├── block.json
    ├── edit.js
    ├── editor.scss
    ├── index.js
    ├── save.js
    └── style.scss

In the node_modules folder we will have all the files we would need for compiling the ES6 code so browsers can use them. The package.json defines all the dependecies that are installed as well the scripts that would run.

The block definition

The most important file in a “block plugin” is the src/block.json file. It defines the name, title, icon and other details:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 2,
    "name": "rpssrb/random-posts",
    "version": "0.1.0",
    "title": "Random Posts",
    "category": "widgets",
    "icon": "smiley",
    "description": "An example for a ServerSideRender block using minimal ES6 code.",
    "supports": {
        "html": false
    },
    "textdomain": "random-posts-server-side-render-block-es6",
    "editorScript": "file:./index.js",
    "editorStyle": "file:./index.css",
    "style": "file:./style-index.css"
}

At the end of the file you will find three really useful lines. They define where the asset files are located. So while we had to use wp_enqueue_scripts in the last blog post, we get this all for free. No need to do that in PHP and handling the check for this file, it’s dependecies and the timestamp for caching ourselves. Just this one feature make it worth using a bit more of modern block development.

Now you could still write only ES5 code into the JavaScript files, but let’s take a look on how our simple example look like with modern JavaScript.

Registering a server side rendered block with ES6

As you have seen in the file system output above, you usually get three JS files. The index.js file will register the block. The edit.js file is used for rendering the block in the editor including controls for it’s options. The save.js will finally hold the functions to save the block content into the post content. Those two extra files can be used, but for a simple block you can also just use the index.js file. And for really complex blocks you would even split up the edit.js into smaller (reusable) parts. To keep it simple again, we will just use the index.js file:

import ServerSideRender from '@wordpress/server-side-render';
import { registerBlockType } from '@wordpress/blocks';
import './editor.scss';
import './style.scss';
import metadata from './block.json';

registerBlockType(
    metadata.name,
    {
        edit() {
            return (
                <ServerSideRender
                    block="rpssrb/random-posts"
                />
            );
        }
    }
);

In order to use components and functions in ES6, we have to import them. We are going to use the ServerSideRender component as well as the registerBlockType function. When you compare this code snippet with the ES5 one from the last blog post, you will recognize that it does not look all that different. This “weirdly looking HTML tag” is JSX, an extension to HTML that React is using to build its components. When passing parameters to those components, you are using attributes similar to HTML (instead of using a JSON object, as in the ES5 variant) and in those attributes you can even use JavaScript. For our ServerSideRender component, we only need to pass the static block name.

As you might have recognized, we are getting the name for the block in the registerBlockType function from our metadata we also import. This will give us the opportunity to get any of the declared values from this file. In this very simple example, we only need the name. We could also use this in the block attribute of the ServerSideRender component, but here we just use a static string.

The two lines I have not yet covered are the imports for the SCSS files. When you use the @wordpress/scripts package that being installed with the npx command above, you will get Sass compilation for free. You just name the two files editor.scss and style.scss and they will be compiled for either just the block editor or for the front end as well.

Now, after you have written this beautiful code, you finally have to compile it. If you only want to do it once (in a minified way, suitable for production use), you run npm run build or while actively developing you use npm run start so you always have a (verbose version, which is better for debugging) of the code you just write.

Registering the PHP callback function for the server side rendered block

As we are still writing a block that would get its content from the PHP backend, we also still have to register the callback function. It looks quite similar to our previous code. But instead of using static string, we can also use the index.js file to register the block in PHP and adding the callback function parameter:

function create_block_rpssrb_block_init() {
	register_block_type(
		__DIR__ . '/build',
		[
			'render_callback' => 'rpssrb_render_callback',
		]
	);
}
add_action( 'init', 'create_block_rpssrb_block_init' );

Instead of using the blocks name, we use the path to our build directory that is being created using the build scripts. In this folder, the PHP function will look for an index.js file and use the block name from this file.

We also use the same implementation for our callback function you can find in the previous blog post. And again you can also use the “bonus” of having a shortcode for the callback as well.

Conclusion

It’s really not that hard to create a block using ES6 syntax, and using the create-block package (or using the @wordpress/script package) make the hard part of getting the compilation running a lot easier. The only thing you have to do – and what might be a bit though – is installing node and then installing npm on your machine. Even then, you have to keep these two up to date and working with the packages you are using. This can really be annoying from time to time.

The reason why it’s worth to do all that, I will cover in my next blog post, when we add some simple controls to our block to make it more usable.

Earlier this week, Topher asked an interesting question on Twitter regarding the current state of block development:

This made me think about I would answer this question. When I first started with block development, I primarily wrote “server side rendered blocks”. These blocks will not generate the content directly in the editor, but use some PHP code and a callback function to render the content, just as a shortcode would do.

The other difficulty with block development is the need to learn many new things: React, JSX, modern JavaScript compilation with webpack and much more. This all combined does not make it “as easy” as it was with shortcodes. But still I wanted to show, how little code you need to create a block that could possibly replace a shortcode without the need to learn all these new things.

Writing a server side rendered block – the PHP part

The easy part is registering the block and the render callback in PHP. While you would use the function add_shortcode() for a shortcode callback, you use a parameter when registering the block in PHP:

function rpssrb_init() {
	register_block_type(
		'rpssrb/random-posts',
		[
			'render_callback' => 'rpssrb_render_callback',
		]
	);
}
add_action( 'init', 'rpssrb_init' );

For this blog post, we will write a block that will render some random posts. The content of the callback would look just like with a shortcode. You can also use the same helper functions you would use for a shortcode. The callback might look like this:

function rpssrb_render_callback( $atts ) {
	$atts = shortcode_atts(
		[
			'post_type'      => 'post',
			'orderby'        => 'rand',
			'posts_per_page' => 5,
		],
		$atts
	);

	$query = new WP_Query( $atts );

	$output = '';
	if ( $query->have_posts() ) {
		$output .= '<ul>';
		while ( $query->have_posts() ) {
			$query->the_post();
			$output .= sprintf(
				'<li><a href=%s>%s</a></li>',
				get_permalink(),
				get_the_title()
			);
		}
		$output .= '</ul>';
	}

	return $output;
}

We set some default attributes and then run a WP_Query to get 5 random posts. We render them in a simple unordered list with only the title linked to the blog post.

Implementing the block in JavaScript – using ES5 code only

As mentioned before, one of the hardest parts of writing a block is need to learn React, JSX, etc. and compile this code. If you are not familiar with these technologies, it can be really hard to get started. This is why I want to show you how you can use some ES5 (“old JavaScript”) to write a block. All you really need is this:

wp.blocks.registerBlockType(
	'rpssrb/random-posts',
	{
		title: 'Random Posts',
		edit: function () {
			return wp.element.createElement(
				wp.serverSideRender,
				{
					block: 'rpssrb/random-posts'
				}
			);
		}
	}
);

We use the wp.blocks.registerBlockType function in ES5 style and only provide a title and the edit function. In this function, we create a React element with the wp.serverSideRender component that will render our block.

The edit function is used to show the content of the block (in our case the result of the callback function written in PHP). You don’t even need this, but then you would not see anything in the block editor (the block also does not take up any space as it’s empty), but it would render in the frontend.

Loading the JavaScript file

This JavaScript code has to be loaded when the block editor is used. If you already have some files being loaded for the block editor, just place it in this file. If not, you would enqueue it in the same way as usual, but with a different hook:

function rpssrb_register_scripts() {
	wp_enqueue_script(
		'random-posts-server-side-render-block',
		plugin_dir_url( __FILE__ ) . 'index.js',
		[ 'wp-blocks', 'wp-server-side-render' ],
		filemtime( plugin_dir_path( __FILE__ ) . 'index.js' ),
		true
	);
}
add_action( 'enqueue_block_editor_assets', 'rpssrb_register_scripts' );

In the dependencies, we add wp-blocks and wp-server-side-render, but they are usually loaded anyway when the block editor is used.

Bonus: use a shortcode as well

As we have written a callback function that we already know from shortcodes, we can simply add another line to make it usable as a shortcode as well (e.g. using the shortcode block):

add_shortcode( 'rpssrb_random_posts', 'rpssrb_render_callback' );

Caveat: using attributes is complicated!

The block we have built here cannot use any attributes. Adding them to the block would be easy, but implementing the controls to make them usable is not that easy. And while it’s doable using only ES5, I would not suggest doing this.

Consequence: Learn JavaScript, deeply.

As Matt has given us all as homework at WCUS 2015 I would highly suggest to start learning some modern JavaScript. The hardest part is getting started is the compilation using webpack. If you have no idea where to start, I would agree with the answer from Birgit to the tweet: use the create-block package.

The create-block package will not only help you to create a running block inside a WordPress plugin. It will also install all the JavaScript packages needed to compile the modern JavaScript. For this it’s using the @wordpress/scripts package and the main script you would use is the start script. Give it a try, read some documentation on how to add attributes and make your block even easier to use.

Conclusion: creating a block can be easy, but it might not be enough

While you can write a block as a simple replacement for a shortcode using only one PHP and one JavaScript file using ES5 syntax, I would not recommend it. Once you made yourself familiar with some basics, you can create blocks that improve usability dramatically. I know it sounds a bit intimidating, and you will run into all kinds of problems, but it’s worth it.

If you want to see the complete code of this blog post, you can find it on GitHub as a plugin.