Sinds de komst van de block editor in WordPress is er in mijn ogen veel veranderd. In de eerste plaats kijken we op een andere manier naar hoe content geschreven wordt. Want eigenlijk is een tekst op te delen in allemaal kleine blokjes. Zo heb je paragrafen, maar ook koppen en afbeeldingen. Alles is dus een blok. Maar hoe bouw je deze nu zelf?

Deze post geeft een kleine inleiding in hoe ik zelf mijn omgeving heb opgezet om de blokken die ik heb gemaakt om te zetten naar javascript. Want als je zelf een blok gaat maken, dan schrijf je deze bij voorkeur in ‘moderne’ javascript. Hierbij maak je gebruik van imports en van React voor de opmaak. Om het voor elke browser begrijpelijk te maken, vertaal je deze code weer naar iets minder moderne JS.

Stap 1: Een block.json bestand maken

Sinds een aantal versies werkt de block-editor met een zogeheten block.json bestand. Dit bestand bevat niets meer dan metadata over het block zelf. Zo hoef je deze data niet op verschillende plekken te registeren. Want het registreren van een blok doe je in zowel de javascript als in de PHP code.

{
    "apiVersion": 2,
    "name": "andy/mijn-blok",
    "title": "Mijn blok",
    "editorScript": "file:./block.js"
}

Stap 2: Het registeren van een blok in PHP

De tweede stap is het registeren van het blok in PHP. Hiervoor verwijzen we naar de directory waar het block.json bestand staat. Laten we voor het voorbeeld even aannemen dat alle bestanden zich in dezelfde directory bevinden.

function register_block() {
    register_block_type( __DIR__ );
}

// We registreren het op de init actie.
add_action( 'init', 'register_block' );

Stap 3: Het registreren van een blok in javascript

Het blok is geregistreerd in WordPress en het editorScript uit de block.json wordt gebruikt om dat editor bestand ook daadwerkelijk in te laden. In het ingeladen script moet wel het block nogmaals geregistreerd worden. Ditmaal doen we dat in de javascript code.

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

registerBlockType( "andy/mijn-blok", {
    edit: function() {

    },

    save: function() {

    }
});

De belangrijkste twee functies die geregistreerd moeten worden zijn edit en save. In de edit wordt alles gedefinieerd voor het gebruik in de editor. De save property bevat de uiteindelijke output, dus hoe het blok er op de voorkant uit ziet.

De edit functie inhoud geven

Een leeg edit attribuut zal zorgen dat er een leeg element geladen wordt in de editor. Dat is eigenlijk niet wenselijk. In WordPress zijn er gelukkig een aantal componenten beschikbaar, alternatief is om zelf de onderdelen te ontwikkelen. Maar dat gaat voor nu misschien iets te ver.

Een component uit WordPress die ik wil toelichten is het RichText component. Dit component wordt onder andere gebruikt om paragrafen, lijsten en koppen te maken in de editor.

Als ik een blok maak, dan probeer ik deze waarden die ik nog heb op te slaan als zijnde attributen. Deze attributen kun je vastleggen in de block.json. Mijn ervaring tot dusver is om dit in de javascript zelf te doen.

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

const attributes ={
    description: {
        type: "string",
    }
};

registerBlockType( "andy/mijn-blok", {
    attributes,

    edit: function( { attributes, setAttributes } ) {
        return <RichText
            tagName="p"
            value={ attributes.description }
            onChange={ description => setAttributes( { description } )}
        />;
    }
} );

Klein toelichting op het bovenstaande: eerst importeren we eerst op regel 2 het RichText component. Op regel 4 tot en met 7 staan de attributes gedefinieerd, deze geven we als argument mee. Bij de edit functie krijgen we twee parameters binnen: attributes en de setAttributes.

In de attributes staan de opslagen waarden van het block en de setAttributes kunnen we gebruiken om een nieuwe waarde te zetten.

De save functie inhoud geven

De volgende stap is om de save functie van inhoud te voorzien. Dit is in principe het blok zoals deze gerenderd moet worden op de voorkant van de website.

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

const attributes ={
    description: {
        type: "string",
    }
};

registerBlockType( "andy/mijn-blok", {
    attributes,

    edit: function( { attributes, setAttributes } ) {
        return <RichText
            tagName="p"
            value={ attributes.description }
            onChange={ description => setAttributes( { description } )}
        />;
    },

    save: function( { attributes } ) {
        return <RichText.Content
            tagName="p"
            value={ attributes.description }
        />; 
    }
} );

Server side renderen

Het alternatief is de save property leeglaten en in PHP een callback mee te geven als argument in de register_block_type functie. Het blok wordt dan on request geladen, dit gebeurt dus server side. Deze aanpak is bijvoorbeeld handig als je met vluchtige of dynamische data werkt zoals een externe bron.

function register_block() {
    register_block_type(
        __DIR__,
        [
            'render_callback' => 'render_server_side',
        ]
    );
}

Dit is in het kort hoe je zelf een blok kunt maken. Er is echter veel meer hierover te schrijven en dat probeer ik ook snel te doen. Wat je in ieder geval kunt verwachten is een toelichting in hoe ik dit alles compile naar javascript. Verder is er ook genoeg te vertellen over het toevoegen van zogeheten controls in bijvoorbeeld de sidebar.