Creating a Custom Block. Part 1: The Basics

Understanding Custom Blocks

Custom blocks are reusable content elements you can add to your WordPress site using the block editor. They extend the functionality of the editor, allowing you to create specific layouts or functionalities without writing custom code for each page.

Prerequisites

Before diving in, ensure you have:

• A text editor or IDE (Integrated Development Environment) like Visual Studio Code.
• A local WordPress development environment. You can use tools like DesktopServer or Local by Flywheel.
• Basic understanding of PHP, HTML, and CSS.

Setting Up the Development Environment

1. Create a directory for your custom block plugin.
2. Inside the directory, initialize a Node.js project using npm init -y.
3. Install the @wordpress/create-block package: npm install @wordpress/create-block.

Scaffolding the Block Plugin

1. Run npx create-block my-custom-block, replacing my-custom-block with your desired block name.
2. This creates the basic structure for your plugin, including a block.json file and essential JavaScript files.

Defining Block Metadata (block.json)

The block.json file defines your block’s properties like name, title, category, and attributes. Here’s an example:

JSON

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "my-custom-block/example-block",
  "title": "Example Block",
  "category": "common",
  "attributes": {
    "content": {
      "type": "string",
      "source": "html"
    }
  },
  "editorScript": "script.js",
  "style": "style.css",
  "editorStyle": "editor-style.css"
}

Building the Block Functionality (script.js)

This file controls the block’s behavior in the editor. Here’s a basic structure:

JavaScript

import { registerBlockType } from '@wordpress/blocks';

registerBlockType( 'my-custom-block/example-block', {
  edit: ( { attributes, setAttributes } ) => {
    // Edit UI for the block
    return (
      <div>
        <p> Your Content Here: </p>
        <textarea
          value={ attributes.content }
          onChange={ ( event ) => setAttributes( { content: event.target.value } ) }
        />
      </div>
    );
  },
  save: ( { attributes } ) => {
    // Rendered output of the block
    return <p>{ attributes.content }</p>;
  },
});

Styling the Block (style.css)

This file defines the block’s visual appearance on the frontend review. You can use CSS selectors to target the block element and its inner content.

Adding Editor Styles (editor-style.css)

This file styles the block specifically within the editor for better visualization while editing content.

Developing the Block Further

With this foundation, you can enhance your block by:

• Adding more attributes for customization.
• Creating custom edit components using React.
• Implementing dynamic data fetching using WordPress APIs.

Testing and Deployment

1. Activate the plugin in your development environment.
2. Add the block to a page or post and test its functionality.
3. Once satisfied, deactivate and zip the plugin directory.
4. Upload the zip file to your live WordPress site’s plugin section and activate it.

Resources

• WordPress Block Editor Handbook: https://developer.wordpress.org/block-editor/getting-started/tutorial/
• @wordpress/create-block package: https://www.npmjs.com/package/@wordpress/create-block
• WordPress Codex: https://codex.wordpress.org/Main_Page

Remember, this is a simplified overview. As you progress, refer to the mentioned resources for in-depth explanations and advanced techniques.

As part of a series, in Part 2 we’ll continue building more functionality with React.js.