Luigi Cavalieri - Authoring Open Source Code

Registrare Due o Più Blocchi Gutenberg Usando File block.json Distinti

Pubblicato il — Luigi Cavalieri

Registrare Due o Più Blocchi Gutenberg Usando File block.json Distinti

Lo sviluppo di plugin block-enabled è un processo perfettamente documentato nel Codex di WordPress, provvisto di tutte le informazioni necessarie per lanciarsi nell'impresa. Ad oggi però, la documentazione sembra essere manchevole di dettagli su come un plugin dovrebbe procedere per registrare due o più Blocchi Gutenberg tramite file di configurazione block.json distinti. Siccome recentemente mi sono trovato a dovermi confrontare con questo intoppo in prima persona, ho pensato di condividere quanto imparato.

Sono dell'idea che il modo migliore di trasferire conoscenze è farlo per esempi, ecco perché quello che sto per fare è accompagnarti passo passo nello sviluppo di un plugin block-enabled non-standard dal nome di Multiblock. Il plugin sarà in grado di registrare due Blocchi di esempio, ogniuno dei quali mostrerà un messaggio sia nell'editor Gutenberg che nella parte pubblica del sito. Siccome lo scopo del post è quello di mostrarti come usare, nello stesso plugin, file di configurazione block.json multipli, ti invito a dare una lettura al Block Editor Handbook nel Codex di WordPress per una spiegazione dettagliata su come sviluppare Blocchi Gutenberg.

Per poter replicare quanto scritto nel post, oltre ad un'installazione locale di WordPress, è necessario che Node.js, e quindi npm, siano installati sul tuo computer. Il mio ambiente di sviluppo è basato su macOS, quindi tutto quanto segue si intende valido in relazione allo sviluppo su macOS.

Se per qualsiasi ragione tu voglia andare dritto al nocciolo, sentiti libero di saltare alla sezione 'Riassunto degli Step Necessari'.

Sviluppo di un Plugin Block-enabled, Fase Preliminare

Per avviare gli sviluppi, useremo il package Node @wordpress/create-block:

  • Apri il Terminale e naviga con il comando cd fino a raggiungere la cartella wp-content/plugins della tua installazione locale di WordPress.

  • Poi, usa l'istruzione che segue per generare i file base del nostro plugin:

    1$ npx @wordpress/create-block multiblock

    Dopo aver premuto invio potrebbe venirti richiesto di installare il package sopraccitato. Se così fosse, procedi pure con l'installarlo.

Prima di poter iniziare a mettere mano al codice, dobbiamo apportare alcune modifiche alla struttura del plugin appena generato.

La Struttura di un Plugin Multi-blocco

Quando giungeremo alla fine di questo post, Multiblock sarà costituito dalla seguente lista di file:

1+ multiblock
2  + build
3      index.asset.php
4      index.css
5      index.js
6      style-index.css
7  + config
8      one-block.json
9      two-block.json
10  + src
11      index.js
12      style.scss
13      OneEdit.js
14      OneEdit.scss
15      OneSave.js
16      TwoEdit.js
17      TwoEdit.scss
18      TwoSave.js
19  - .editorconfig
20  - .gitignore
21  - multiblock.php
22  - package-lock.json
23  - package.json
24  - readme.txt

Un plugin multi-blocco come Multiblock deve includere tanti file block.json quanti sono i Blocchi Gutenberg da registrare. In generale conviene raggruppare tutti questi file di configurazione in una sotto-cartella, quindi crea una nuova cartella nella directory multiblock, chiamandola config.

In riferimento al nostro plugin di esempio, il contenuto dei nostri file block.json sarà molto simile a quello del file di default src/block.json generato dal package @wordpress/create-block. Per essere concisi, procederemo col registrarre due soli Blocchi. Possiamo creare il file di configurazione del nostro primo blocco spostando src/block.json nella sotto-cartella config e rinominandolo one-block.json — chiameremo i due Blocchi rispettivamente One e Two.

Il filename di file block.json custom deve necessariamente terminare con 'block.json', affinchè WordPress possa caricarlo senza inconvenienti.

Il nostro one-block.json ha bisogno di un pò di personalizzazione. Per lo meno dobbiamo aggiornare le property name e title. Quindi, aggiorna i loro valori rispettivamente con one/multiblock e Multiblock - One. Inoltre, dobbiamo dire a WordPress che i file .js e .css finali, necessari al front-end per mostrare, controllare e dare uno stile al nostro Blocco 'One', saranno contenuti nella cartella build, quindi bisogna aggiornare one-block.json con le seguenti coppie chiave-valore:

1{
2  // ....
3  "editorScript": "file:../build/index.js",
4  "editorStyle":  "file:../build/index.css",
5  "style":        "file:../build/style-index.css"
6}

config/two-block.json, il file di configurazione del Blocco 'Two', è per lo più uno copia di one-block.json dove le occorrenze della parola one vanno sostituite con la parola two, facendo attenzione a preservarne la capitalizzazione. C'è un ma: siccome solo uno dei file di configurazione in un set di file block.json dovrebbe includere informazioni riguardo i path degli script e stylesheet finali, i nostri due file di configurazione hanno caratteristiche ben distinte. La ragione di ciò è che dobbiamo dire a WordPress di caricare i file nella cartella build solo una volta.

Quindi, dopo aver duplicato one-block.json, rinominato la sua copia come two-block.json e sostituito le occorrenze della parola one con la parola two preservandone la capitalizzazione, devi aprire il file two-block.json e cancellare le tre property finali: editorScript, editorStyle e style.

Abbiamo fatto con i file di configurazione. Ora, siccome di solito ogni Blocco ha il proprio set di componenti "Edit" e "Save" ospitati nella sotto-cartella src, è tempo di scrivere del codice!

Popoliamo la Sotto-cartella 'src'!

La sotto-cartella 'src' è dove va inserito il nostro codice custom. Questa conterrà i seguenti file:

  • index.js: il punto di inizio della parte React del nostro plugin di esempio. Qui andranno le chiamate alla funzione registerBlockType().
  • style.scss: lo stylesheet importato da src/index.js. Conterrà il CSS usato per definire l'aspetto dei nostri Blocchi sia nell'editor Gutenberg che nella parte pubblica del sito.
  • Un file "Edit.js" e uno "Edit.scss" per ciascuno dei nostri due Blocchi. Conterranno rispettivamente il componente "Edit" (controlla il Blocco nell'editor) e le sue regole di stile CSS (applicate solo al markup nell'editor).
  • Un file "Save.js" per ogniuno dei nostri due Blocchi. Conterrà il componente "Save", il componente che controlla il markup di un Blocco nella parte pubblica del sito.

Prima di procedere col riempire i file sopra elencati con il codice necessario, bisogna ripulire la cartella src di tutti i file che non useremo, quindi occorre che cancelli tutti i file di default eccetto src/index.js e src/style.scss.

Ora puoi creare il file src/OneEdit.js — contiene il componente "Edit" che registreremo per il Blocco 'One':

1import { __ } from '@wordpress/i18n';
2import { useBlockProps } from '@wordpress/block-editor';
3
4import './OneEdit.scss';
5
6export default function OneEdit() {
7  return (
8    <p {...useBlockProps()}>
9      {__( "Multiblock – hello from the editor, I'm One!", 'multiblock' )}
10    </p>
11  );
12}

Noterai che tra gli import c'é anche l'instruzione di import per il file src/OneEdit.scss. Come scritto poc'anzi, questo file contiene le regole CSS applicate al markup mostrato nell'editor Gutenberg. Il contenuto è minimale:

1.wp-block-one-multiblock {
2  color: #00ff73;
3}

L'ultimo file di cui il Blocco 'One' ha bisogno è src/OneSave.js, quindi è necessiario crearlo e popolarlo con questo codice:

1import { __ } from '@wordpress/i18n';
2import { useBlockProps } from '@wordpress/block-editor';
3
4export default function OneSave() {
5  return (
6    <p {...useBlockProps.save()}>
7      {__( "Multiblock – hello from the saved content, I'm One!", 'multiblock' )}
8    </p>
9  );
10}

I file di cui abbiamo bisogno per il Blocco 'Two' possono essere ricavati dai tre file appena creati per il Blocco 'One' semplicemente duplicandoli e rinominando le occorrenze della parola 'one' con la parla 'two' sia nel contenuto che nel nome dei file. Per differenziare un minimo il modo in cui i due Blocchi appariranno nell'editor, possiamo modificare il colore del testo del Blocco 'Two', per esempio. Per farlo, ti occorre giusto scrivere quanto segue in src/TwoEdit.scss:

1.wp-block-two-multiblock {
2  color: #fbff00;
3}

Il File 'src/index.js'

Infine, in src/index.js dobbiamo importare tutte le dipendenze e registrare i due Blocchi con due distinte chiamate di registerBlockType():

1import { registerBlockType } from '@wordpress/blocks';
2
3import './style.scss';
4
5import OneEdit from './OneEdit';
6import TwoEdit from './TwoEdit';
7import OneSave from './OneSave';
8import TwoSave from './TwoSave';
9
10registerBlockType( 'one/multiblock', {
11  edit: OneEdit,
12  save: OneSave
13});
14registerBlockType( 'two/multiblock', {
15  edit: TwoEdit,
16  save: TwoSave
17});

Il CSS dello stylesheet src/style.scss, che controlla l'aspetto dei Blocchi sia nell'editor Gutenberg che nella parte pubblica del sito, non deve necessariamente distinguersi dal codice generato dal package @wordpress/create-block, dopo tutto Multiblock è solo un'esemplificazione, per cui lo andremo a modificare solo per far si che le regole CSS ivi contenute vengano applicate al markup dei nostri due Blocchi:

1.wp-block-one-multiblock,
2.wp-block-two-multiblock {
3  background-color: #21759b;
4  color: #fff;
5  padding: 2px;
6}

Un Ultimo Passo, ed Abbiamo Fatto

A questo punto siamo quasi pronti a lanciare lo script build. Quello che rimane da fare è far si che il back-end di WordPress sappia riguardo l'esistenza dei nostri due Blocchi. In altre parole bisogna registrare i due Blocchi usando i metadati contenuti nei nostri file block.json personalizzati. Quindi, nel file multiblock.php, aggiorna create_block_multiblock_block_init() come segue:

1function create_block_multiblock_block_init() {
2  register_block_type( __DIR__ . '/config/one-block.json' );
3  register_block_type( __DIR__ . '/config/two-block.json' );
4}
5add_action( 'init', 'create_block_multiblock_block_init' );

Ora possiamo dirigerci dritti verso il nostro Terminale, dove faremo un cd verso la cartella wp-content/plugins/multiblock e lanceremo lo script build in questo modo:

1$ npm run build

È finalmente possibile attivare il plugin dall'area di amministrazione di WordPress, e testarlo ovviamente! Se provi ad inserire i due Blocchi ('Multiblock - One' e 'Multiblock - Two') in un qualsiasi post, per esempio, l'editor Gutenberg dovrebbe mostrare qualcosa molto simile a questo:

Blocks One and Two shown by the Gutenberg Editor.
Blocks One and Two shown by the Gutenberg Editor.

Riassunto degli Step Necessari

Se vuoi leggere il post per intero in un secondo momento, qui trovi il riassunto degli step necessari affichè un plugin block-enabled possa registrare più Blocchi Gutenberg:

  • Il tuo plugin deve includere tanti file block.json custom quanti sono i Blocchi Gutenberg da registrare, tenendo a mente che il filename di questi block.json custom deve necessariamente terminare con block.json e che solo un file di configurazione in un set di file block.json deve includere informazioni riguardo i path dei file JavaScript e CSS finali – questi file saranno quelli automaticamente inseriti nella sotto-cartella build da parte dello script build.
  • Per ogni Blocco, è consigliabile creare una coppia distinta di componenti "Edit" e "Save", ciascuno salvato in un file a se stante. Conviene inoltre cerare uno stylesheet distinto per ogni componente "Edit".
  • src/index.js deve contenere una chiamata distinta alla funzione registerBlockType() per ogniuno dei Blocchi.
  • Il file PHP principale del tuo plugin deve registrare ogni Blocco usando i metadati contenuti nel tuoi file block.json custom. Questo è fattibile inserendo in una callback dell'Action Hook init tante chiamate register_block_type( 'path-to/custom-block.js' ) quanti sono i Blocchi da registrare.

Al momento della stesura di questo post, WordPress 5.9.1 è l'ultima versione stabile che il team di sviluppo ha reso disponibile al mondo.

TOP