Kom godt i gang med WordPress blokudvikling

WordPress har efterhånden haft Gutenberg-editoren i nogle år, og de fleste bruger den til at oprette sider og blogindlæg. Men core-blokkene rækker ikke altid, og så opstår behovet for mere avanceret funktionalitet. I dette indlæg giver jeg en praktisk introduktion til at udvikle egne blokke med React (jsx) og WordPress-værktøjet @wordpress/scripts. Jeg anbefaler, at du er fortrolig med React og JavaScript generelt, og at du har grundlæggende erfaring med at køre npm i terminalen. Hvis du vil kode med undervejs, så sørg for, at du har en nyere version af Node.js installeret.

TL;DR: Hvis du vil springe direkte ud i det, har jeg lavet en plugin-skabelon, der er klar til brug. Hent den fra GitHub: https://github.com/cmk2179/wp-block-starter eller brug:

npx degit https://github.com/cmk2179/wp-block-starter <path/to/wordpress/wp-content/plugins/my-block-plugin>

Se README-filen for at komme hurtigt i gang.

Opsætning af WordPress

Jeg antager, at du allerede har en webserver som Apache eller Nginx sat op, eller ved hvordan det gøres. Download den nyeste version af WordPress og pak den ud i din webroot-mappe.

Åbn en terminal og naviger til mappen wp-content/plugins. Opret basis-pluginet med denne kommando: npx degit https://github.com/cmk2179/wp-block-starter wp-block-starter.

Gå derefter til plugin-sektionen i WordPress-administrationen og aktivér pluginet. Så er du klar til at udvikle.

Hvis du vil følge med trin for trin, så slet den eksisterende sample-block i src/blocks, da målet i indlægget er at bygge den op fra bunden.

Oprettelse af en blok

Lad os oprette den første blok. Vi gør det i mappen src/blocks ved at skifte mappe og køre scaffold-kommandoen:

cd src/blocks
npx @wordpress/create-block --no-plugin --no-wp-scripts --title "Sample block" --namespace wp-block-starter sample-block

Denne kommando klarer det tunge arbejde og opretter de filer, der er nødvendige for en blok. Som standard opretter scriptet et helt plugin og installerer en række pakker, men her vil vi kun generere selve blokken uden ekstra opsætning. Med flagene --no-plugin og --no-wp-scripts oprettes kun de filer, vi har brug for. Outputmappen får navnet fra sidste argument i kommandoen og oprettes i den aktuelle mappe. Grunden til, at blokken skal ligge i src, er, at @wordpress/scripts automatisk scanner den mappe for block.json-filer.

Den første fil, vi kigger på, er den genererede block.json. Her registreres al metadata for blokken, fx navn, beskrivelse, ikon og attributter. Den genererede fil indeholder ikke alle muligheder, så se dokumentationen for block.json for den fulde oversigt.

Nu bygger vi blokken og aktiverer filovervågning, så ændringer automatisk kompileres, når du genindlæser browseren. Kør: npm run dev.

Det opretter en build-mappe med output fra kompileringen af blokke i src. Næste trin er at registrere blokken i WordPress med funktionen register_block_type. I denne opsætning skal vi blot pege på mappen med block.json:

// wp_block_starter.php
<?php
/**
 * Plugin name: WP Block Starter
 */

if (!function_exists("wp_block_starter_register_blocks")) {
    function wp_block_starter_register_blocks()
    {
        register_block_type(__DIR__ . "/build/blocks/sample-block");
    }
}

add_action("init", "wp_block_starter_register_blocks");

Blokken er nu registreret, og vi kan bruge den i editoren. Opret et nyt indlæg og find blokken ved at søge efter “Sample block”. Du bør nu se standardindholdet fra scaffold-scriptet.

Blokudvikling

Nu kan den egentlige udvikling begynde. Vi laver en simpel blok med følgende funktioner:

Det skal være muligt at…

• …tilføje andre blokke inde i blokken (inner blocks)
• …ændre baggrundsfarven på blokken
• …ændre tekstfarven på blokken

Bemærk, at blokke er interaktive i editoren, men gemmes som statisk HTML, når indlægget publiceres. I dette indlæg fokuserer vi på den type blokke. Måske følger jeg op med et indlæg om dynamiske blokke senere. For statiske blokke har hver blok en edit- og en save-metode. Edit bruges i editoren, mens save genererer den markup, der gemmes i databasen. Hvis du vil læse mere om dynamiske blokke, findes der en god tutorial i WordPress-dokumentationen.

Tilføjelse af blokke som børn

I de fleste tilfælde er det heldigvis enkelt, fordi WordPress har en core-blok til formålet. Åbn edit.js, tilføj InnerBlocks-komponenten, og skift samtidig paragraph-tagget til et div:

// Opdater importen også for at gøre brug af InnerBlocks-komponenten
import { InnerBlocks, useBlockProps } from "@wordpress/block-editor";

export default function Edit() {
  return (
    <div {...useBlockProps()}>
        {__("Sample block – hello from the editor!", "sample-block")}
        <InnerBlocks template={[["core/paragraph"]]}></InnerBlocks> // <-- tilføj InnerBlocks-komponenten her
    </div>
  );
}

Du har måske bemærket, at vi tilføjede template-egenskaben på InnerBlocks. Uden den har inner blocks som udgangspunkt ingen højde, og det gør dem svære at opdage i editoren. Ved at tilføje en paragraph får du placeholder-tekst, så det tydeligt fremgår, at der kan indsættes indhold.

Vi skal også opdatere save-funktionen, så blokken gemmes korrekt. Åbn save.js og tilføj også InnerBlocks her.

// Opdater importen også for at gøre brug af InnerBlocks-komponenten
import { InnerBlocks, useBlockProps } from "@wordpress/block-editor";

export default function save() {
  return (
    <div {...useBlockProps.save()}>
      {"Sample block – hello from the saved content!"}
      <InnerBlocks.Content></InnerBlocks.Content> // <-- tilføj InnerBlocks.Content-komponenten her
    </div>
  );
}

I save-metoden bruger vi InnerBlocks.Content, som sørger for at rendere de indsatte inner blocks til HTML, så indholdet kan gemmes i databasen.

Nogle gange kan du støde på en blokvalideringsfejl på grund af den måde, WordPress serialiserer og deserialiserer blokke. Når en side åbnes i editoren, sammenlignes det gemte indhold med det nygenererede indhold fra blokken. Hvis de afviger på bestemte måder, får du en fejl. Som regel er “Attempt Block Recovery” nok, men i enkelte tilfælde skal du indsætte nogle inner blocks igen. Husk altid at gemme indlægget bagefter.

Ændring af baggrundsfarven

Før vi går i gang, rydder vi op i den styling, som scaffold-scriptet har lavet, og som giver blokken en blå baggrund. Åbn style.scss og fjern reglerne:

.wp-block-wp-block-starter-sample-block {
  /* slet disse tre linjer */
  background-color: #21759b;
  color: #fff;
  padding: 2px;
}

Næste trin er attributter. Det er dem, der sørger for, at værdier bevares mellem gemninger, og de bruges både i edit- og save-metoden. Attributter defineres i block.json, og dokumentationen findes her.

Vi skal definere en attribut til baggrundsfarven. Åbn block.json og tilføj:

"attributes": {
  "backgroundColor": {
    "type": "string",
    "default": "transparent"
  }
},

Nu tilføjer vi en color picker i inspektøren. Det gør vi med InspectorControls, som skal ligge som sibling til indholdet i editoren. Efter ændringen kan edit se sådan ud:

export default function Edit({ attributes, setAttributes }) {
  return (
    <>
      <InspectorControls>
        <PanelBody title="Colors">
          <BaseControl label="Background color">
            <ColorPalette
              value={attributes.backgroundColor}
              onChange={(backgroundColor) => setAttributes({ backgroundColor })}
            ></ColorPalette>
          </BaseControl>
        </PanelBody>
      </InspectorControls>

      <div
        {...useBlockProps()}
        style={{ backgroundColor: attributes.backgroundColor }}
      >
        {__("Sample block – hello from the editor!", "sample-block")}
        <InnerBlocks template={[["core/paragraph"]]}></InnerBlocks>
      </div>
    </>
  );
}

Der findes mange måder at bygge layoutet i inspektøren på. Her bruger jeg den enkle løsning med PanelBody. Komponenten laver en fold-ud sektion, der gør det nemt at gruppere relaterede indstillinger. Hvis du vil have en mere avanceret opsætning, så kig på ToolsPanel-komponenten. Du finder dokumentation og eksempel her.

Vi opdaterer også save-funktionen, så det virker i det publicerede indlæg:

export default function save({ attributes }) {
  return (
    <div
      {...useBlockProps.save()}
      style={{ backgroundColor: attributes.backgroundColor }}
    >
      {"Sample block – hello from the saved content!"}
      <InnerBlocks.Content></InnerBlocks.Content>
    </div>
  );
}

Ændring af tekstfarven

Den del er ret ligetil. Prøv selv at implementere den ved at bruge samme mønster som for baggrundsfarven ovenfor.

Konklusion

Det var en kort introduktion til at komme i gang med blokudvikling til WordPress Gutenberg-editoren. Jeg er selv stadig i gang med at bygge erfaring op på området, men dette indlæg samler de vigtigste trin, jeg selv manglede, da jeg begyndte. Min egen start var præget af en del trial-and-error og meget tid i dokumentationen, fordi jeg savnede en enkel praktisk guide. Jeg håber, at denne gennemgang, sammen med de links jeg selv har brugt, kan gøre det lettere for andre at komme i gang med at udvikle Gutenberg-blokke.