Creating a server side rendered Gutenberg block

Register a small dynamic block correctly on the server and in the editor, then render its output with PHP.

Creating your first server side rendered WordPress Gutenberg block can seem like a daunting task, but with a little bit of guidance, it can be a straightforward process.


Setting up the plugin

Once you have the WordPress environment set up, the next step is to create a new plugin. This can be done by creating a new directory in the “wp-content/plugins” directory and giving it a unique name. In this directory, create a new file named “index.php” and add the plugin header information at the top of the file:

<?php
/*
 Plugin Name: My First Server Side Rendered Block
 Plugin URI: https://example.com/my-first-block
 Description: This is my first server side rendered block for WordPress.
 Version: 1.0
 Author: Your Name
 Author URI: https://example.com
 License: GPL2
*/

Define your block with a block.json file

Next, create a new file named “block.json” in the same directory and define the metadata for the block:

{
  "apiVersion": 3,
  "name": "my-plugin/my-first-block",
  "title": "My First Block",
  "category": "widgets",
  "icon": "admin-site",
  "supports": {
    "html": false
  },
  "editorScript": "file:./my-first-block.js"
}

Creating the block

With the block.json file in place, you can now create the actual block using the WordPress block API. To do this, add the following code to your plugin file:

add_action('init', function () {
    wp_register_script('my-first-block-editor',
        plugins_url('my-first-block.js', __FILE__),
        ['wp-blocks', 'wp-element', 'wp-block-editor'], '1.0', true);
    register_block_type(__DIR__, [
        'editor_script' => 'my-first-block-editor',
        'render_callback' => function () { return '<p>Hello World</p>'; },
    ]);
});

Create my-first-block.js beside block.json. An empty script will not register the block in the editor. Use this minimal JavaScript (no build step required):

The heart of the server side rendering lies in the my_first_block_render function. This function is responsible for rendering the block’s content on the front end of the website. In this example, it simply returns the string “Hello World”. However, in a real-world scenario, you would typically use this function to retrieve data from the database, manipulate the data, and return the result to be displayed on the front end.

The my_first_block_render function takes in an $attributes parameter, which is an array that contains any attributes that have been set for the block in the editor. You can use this information to retrieve and manipulate the data that is specific to this particular instance of the block.

The my_first_block_render function is passed to the register_block_type function as the render_callback parameter, so that it is called every time the block is rendered on the front end.

In conclusion, server side rendering is a crucial part of creating blocks in WordPress, and the my_first_block_render function is at the center of this process. Whether you’re simply returning a string or retrieving and manipulating data from the database, this function is the key to creating dynamic, data-driven blocks that can enhance the user experience on your WordPress site.

Register the editor block

The following file must be saved as my-first-block.js. It registers the same name as the PHP metadata and uses dynamic output. For field-driven rendering, continue with our ACF field block tutorial.

wp.blocks.registerBlockType('my-plugin/my-first-block', {
  apiVersion: 3, title: 'My First Block', category: 'widgets',
  edit: function () {
    return wp.element.createElement('p', wp.blockEditor.useBlockProps(), 'Hello World');
  },
  save: function () { return null; }
});

Good things, occasionally.

Fresh ideas, useful tools and better ways to build. Delivered when we have something worth sharing.