Develop your own WordPress block - Part 1: Getting started with programming with Gutenberg

In this series of articles, I'll show you how you can develop your own WordPress block from scratch. The first part is about the structure and architecture of a Gutenberg Block Plugin and the presentation of all tools required for development in modern JavaScript.

Image card block

The aim of the entire series is to develop an image card block for the new WordPress Gutenberg editor. It should be possible to determine the image, title and text and to adjust the layout, the colors and the design of the block with some options.

Image Card WordPress Block

To get started, let's first define some theoretical basics:

  • What is a block plugin made of?
  • What is React and JSX?
  • Why do I need tools?
  • What is Webpack, Babel and Sass for?

Building a Gutenberg block

First, I would like to take a look at the architecture of a Gutenberg block.

Basically, only one JavaScript file is integrated into the editor for a WordPress block. The block JS is integrated as usual in WordPress with wp_enqueue_script() and should be done in a WordPress plugin (not theme).

A very simple WordPress block plugin could consist of just four files:

  • Block JavaScript - block.js

    Here the block is created and programmed with the registerBlockType() function. From the block interface in the editor, HTML markup in the front end to the block options, everything takes place here in JavaScript and React. In the rest of the tutorials in this series of articles, we will focus on this part of the block development in detail.

  • Block stylesheet - block.css

    The styling of the block is integrated with its own CSS file both in the editor and in the frontend (theme).

  • Editor stylesheet - block-editor.css

    In contrast to the block.css , this stylesheet is only loaded in the editor. It includes extra styling for block options and the block interface, which is not needed in the front end.

  • Plugin File - plugin.php

    The main plugin file with the normal WordPress plugin header . Here our block JavaScript and block stylesheets are integrated enqueue_block_editor_assets the theme and editor with the new action hooks enqueue_block_assets and enqueue_block_editor_assets .

This basic block architecture also works for the currently very popular block collections. Instead of one block, several blocks are simply registered in the JavaScript file.

React and JSX

When you hear Gutenberg, you inevitably think of React as a developer.

React is a JavaScript library from Facebook for creating user interfaces. The Gutenberg Editor is completely written in React, as are all core blocks. Theoretically, you can also create your own blocks without React, but as of today almost everyone uses the framework.

React relies on components that are nested within one another. A component is a function or class that returns and renders a React element.

 class Welcome extends React.Component { render() { return <h1>Hello, {}</h1>; } }

The return value of the render function looks strange at first and is neither a string nor HTML, but JSX. It is the preferred form of creating a React Element.

JSX is a syntax extension for JavaScript and recommended for development with React. It brings JavaScript and HTML together and in principle allows us to mix HTML tags, JavaScript code and React components, similar to a template language.

Modern JavaScript tooling

The development of WordPress themes and plugins involves few hurdles and is very easy, because nothing more than a text editor and a local development environment is required. Even WordPress beginners can adapt the code relatively easily.

In theory, WordPress blocks don't need more than that either. The Gutenberg Handbook shows code examples in ES5 that can do without any tooling. In my opinion, the development for Gutenberg only makes sense in ESNext and with JSX, which requires a number of tools:

  • Webpack

    It would be very tedious to create an entire block or even several blocks in a JavaScript file. Webpack is a so-called bundler and is used to merge several JS files back into one file. We can use it to split our JavaScript code into any number of files and import and export them as modules.

  • Babel

    Modern JavaScript usually means the use of the latest ES6 features . ES6 is the latest standard for JavaScript and has lots of great features, but it won't work in older browsers. This is where Babel comes in. The tool compiles your modern ES6 and JSX code and turns it into compatible JavaScript for all browsers.

  • Sass

    Sass is super-powered CSS and makes it easy for you to write style sheets with useful features like variables, nesting and mixins.

Webpack is the core of the build process, ie in addition to bundling files, the code is transformed with so-called Webpack loaders - for Babel and Sass, among others. You can think of it as a funnel. At the top you pour in a lot of source files and code (ES6, JSX, SCSS), at the bottom our block.js and block.css come out.

Developing a WordPress Block: Outlook on Part 2

Phew, I hope the multitude of terms and buzzwords didn't put you off immediately.

In the next tutorial we leave theory behind and create our own block plugin. The structure of the plugin and the functionality of the tooling should become a little more understandable and clearer as soon as we start with the practical part. React and JSX are not rocket science either, as we will see with the first code examples.

Overview of all articles in this series