• Home
  • About Mitch
  • Speaking
  • Articles
  • Contact
  • Home
  • About Mitch
  • Speaking
  • Articles
  • Contact

Digital Strategist

WordPress Developer

Content Creator

Unapologetic Punk

Mitch Canter

  • X
  • Bluesky
  • GitHub
  • Twitch
  • YouTube
  • LinkedIn
Tutorial

One Block to Another: A Guide To The Block Transform API

CMDR Mitchcraft

Reading time: 4 minutes

The introduction of Gutenberg in WordPress has revolutionized the way we create and design content. With Gutenberg’s popularity on the rise, content creators are on the hunt for ways to make their content easier and more effective to write. As more and more blocks are added to the repository, it becomes increasingly important to allow a sort of interoperability to them – allowing blocks to transfer content from one to another as users figure out which blocks work best for them. Thankfully, the Block Transform API allows exactly that.

What is the Block Transform API?

A Block Transform is underlying code in a Gutenberg block that allows that block to be converted to another. This happens in one of two ways:

  1. Outgoing, moving data to another block
  2. Incoming, moving data from other blocks or other formats into a Gutenberg Block

It’s good practice to ensure that any blocks created have at least the basic transformations accounted for – your content editors will thank you for the ability to seamlessly move between blocks as they try to figure out the best ways to structure their content.

How to Transform A Block In The WordPress Editor

In the WordPress Editor, taking advantage of a block transform is easy:

Block Transform - Changing to Headline

Click on the block you wish to transform. A contextual menu will pop up over the block. Click on the block time – in the example above, it’s a Paragraph tag.

Block Transform - Changing to Headline

This will bring up the “Transform To…” dropdown. Here, you’ll see the list of defined blocks that you can transfer this block’s content to. In this case, we want to change this block to a Headline block.

Block Transform - Changing to Headline

The content is immediately transformed into a headline block. We can transform it back to a paragraph block, or we can use it as a headline with the previous text imported and ready to manipulate.

Setting Up A Block Transform

Most of the core WordPress blocks have transforms defined already, but what if we’re writing our own blocks a part of a theme or plugin? Let’s look at a very simple custom WordPress block:

export const settings = {
    title: 'My Block Title',
    description: 'My block description',
    /* ... */
    transforms: {
        from: [
            /* supported from transforms */
        ],
        to: [
            /* supported to transforms */
        ],
    },
};

Here we have a defined block with its title and description, and not much else. If we want to add a transform to this, we need to define a few parameters, as described in the Block Transform handbook on WordPress.org.

First, we need to define which type of transformation it is:

  • block – conversion of one block to another
  • enter – conversion of specific content entered by the user (example: a separator block created when the user types “—“. Markdown conversion is a great example of this (## turns into a Headline 2 when you add it to the editor)
  • files – recognition of a specific file time, and a conversion of that file into a block
  • prefix – conversion of a specific command prefix (ex. !block) to a block.
  • raw – conversion of raw HTML to a pre-formatted block design.
  • shortcode – conversion of a shortcode and its attributes into an appropriate Gutenberg block

For this guide, we’ll stay simple and go with a block to block conversion. Let’s look at our example above: transforming a paragraph tag into a headline tag (this is defined in the Headline block, since it’s a ‘from’ transform):

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

transforms: {
    from: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            transform: ( attributes ) => {
                return createBlock( 'core/heading', {
                    content: attributes.content,
                } );
            },
        },
    ]
}

We are defining our ‘from’ transform, telling WordPress that we are defining the transform from paragraph to heading, and using createBlock to have WordPress set up and create the new Headline block with our current content.

A ‘to’ transition is similar, defining what content we can push to other blocks during the conversion:

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

transforms: {
    to: [
        {
            type: 'block',
            blocks: [ 'core/heading' ],
            transform: ( attributes ) => {
                return createBlock( 'core/paragraph', {
                    content: attributes.content,
                } );
            },
        },
    ]
}

Why Bother With A Block Transform?

WordPress is a system that’s been well known for its ease-of-use for non-technical users. Without a clear standard to migrate content between blocks, any new blocks created will only created walled gardens that frustrate and confuse users. The Block Transform API is one of the most powerful things to come out of Gutenberg. It also is one of the most underutilized features.

As developers, we owe it to our users to allow content to flow freely between blocks. Selfishly, it allows users to adopt our blocks easier, knowing they can convert a block instead of having to create a block from scratch (or copy and paste content from one block to another). But it also allows users the flexibility to move away from our blocks as a courtesy.

Block transforms are a powerful tool that can help you save time and streamline your content creation process in WordPress. By enabling a user to easily convert one type of block into another, block transforms give all users more flexibility and control over the design and layout of content.

Whether you’re a seasoned developer or a beginner, Gutenberg’s block transforms feature makes it easier than ever to create engaging and visually appealing websites, and it’s worth keeping as a tool in your plugin creation toolkit.

block transform, gutenberg, WordPress
  • Add a Buttonless Search Form in WordPress

    Add a Buttonless Search Form in WordPress

    Reading time: 1 minute

    I love search forms.  But sometimes, designs call for forms to be placed in a tight space to save room for other elements or where buttons may look out of place.  If that’s the case, then you can add a special box that will allow users to search with the enter key (or the Done…

    WordPress
  • How to Update WordPress Themes and Plugins on WPEngine (Without the Repository)

    How to Update WordPress Themes and Plugins on WPEngine (Without the Repository)

    Reading time: 5 minutes

    Skip to the Tutorial My head is full and my heart is sad tonight. Thousands of WordPress users are left in a strange scenario today as Matt Mullenweg, Automattic’s CEO and founder, pulled access to the WordPress Repository for thousands of users on WPEngine. WPEngine is officially cut off from all updates – plugins, themes,…

    WordPress