Crea facilmente un blocco Gutenberg con Metabox.io

A mio parere Gutenberg è stato un grande passo in avanti per l’editor WordPress, grazie alla sua introduzione i suoi utenti possono avere una preview molto fedele del contenuto che stanno per pubblicare.

Allo stesso tempo questo passo in avanti è stato un duro colpo da digerire per tutta la comunità di sviluppatori WordPress che erano abituati a lavorare quasi esclusivamente con codice PHP.

Il nuovo editor è interamente sviluppato in React.js e neanche con la sua versione standard ma con un sottoinsieme che WordPress mette a disposizione attraverso l’oggetto globale wp.element.

Oltre a dover imparare una nuova libreria JavaScript gli sviluppatori WordPress devono prendere confidenza con JSX, una sintassi molto simile all’HTML (ma più potente), per creare nuovi elementi.

Tutto questo dovrebbe essere tenuto insieme da Webpack, o un altro module bundler, quindi devi anche imparare a creare un file di configurazione che ti permetta di lavorare con questi nuovi strumenti.

Insomma, c’è veramente tanto da imparare!

Non è mia intenzione entrare nel dettaglio con le sfide che dobbiamo affrontare perché sto scrivendo questo articolo per presentarti un modo semplificato per la creazione di blocchi Gutenberg utilizzando esclusivamente il nostro caro PHP.

Come creare un blocco esclusivamente con codice PHP

Come ti anticipavo, non è mia intenzione andare a descrivere tutte le conoscenze di cui avrai bisogno per creare il tuo primo blocco Gutenberg (non in questo articolo almeno) perché molte di queste riguardano linguaggi e strumenti che devi già conoscere.

Quello che voglio fare è descriverti una delle soluzioni che ti permette di creare dei blocchi Gutenberg con un linguaggio di programmazione che già conosci: il PHP.

Esistono molte aziende che hanno provato a risolvere questa sfida come ACF, Block Lab, Carbon Fields o Lazy Blocks…

All’interno di questo articolo ho deciso di spiegarti come creare il tuo primo blocco Gutenberg in PHP grazie alla nuova estensione di Metabox.io, ecco le mie motivazioni per aver scelto questa soluzione al posto delle precedenti.

Piccola introduzione a Metabox.io

La creazione di meta box all’interno di WordPress è un aspetto che mi ha sempre annoiato.

Trovo che la sintassi sia molto ripetitiva e in alcuni casi dobbiamo conoscere veramente bene WordPress per nascondere/mostrare i nostri campi nelle pagine specifiche.

Ecco perché ho sempre preferito delegare questo compito a librerie come CMB2, che ho utilizzato felicemente prima di conoscere Metabox.io

CMB2 e Metabox.io sono due soluzioni che ci aiutano a creare e configurare delle meta box all’interno di WordPress. Ci aiutano anche nella creazione di intere pagine opzioni per i nostri temi o plugin ma Metabox.io fa molte più cose.

In questo articolo andremo a scoprire come utilizzare la soluzione proposta da Metabox.io per creare blocchi Gutenberg ma ci sono altre cose interessanti che puoi fare con il suo utilizzo:

• utilizzo di campi avanzati – abbiamo a disposizione un’ampia scelta di campi che sono stati creati per rispondere alle necessità di noi sviluppatori;
• semplicità nell’inclusione/esclusione del nostro codice – abbiamo diverse opzioni che ci permettono di scegliere con precisione dove mostrare e dove nascondere le nostre opzioni;
• semplificata creazione opzioni nel Customizer – grazie a questa libreria anche creare dei campi nel Customizer diventa un gioco da ragazzi.

Mi fermo qua perché alla fine Metabox.io ha così tante caratteristiche interessanti che rischierei soltanto di replicare le (già ottime) pagine di documentazione disponibili.

Però prima di passare alla prossima sezione voglio dirti brevemente perché ho deciso di acquistare Metabox.io al posto di continuare a utilizzare CMB2 gratuitamente.

Sia chiaro, io sono incredibilmente grato al team di WebDevStudios per aver creato CMB2 che per anni mi ha permesso di creare custom fields e pagine opzioni per i miei progetti ma trattandosi di un progetto open source più volte ne ho visti i limiti.

Limiti che magari avrei potuto anche aiutare a risolvere ma il tempo è sempre tiranno.

Oltre a questo CMB2 non implementa una soluzione per la creazione di blocchi Gutenberg e, a quanto ho capito, non sono neanche interessati a farlo.

Cercando in rete un progetto che fosse mantenuto e ricco di funzionalità ho trovato Metabox.io.

Le soluzioni che ti ho elencato precedentemente , come ACF, non mi interessano perché permettono di creare campi e blocchi con un editor visuale e in alcuni casi non usano neanche la sintassi standard di WordPress.

Io voglio dichiarare i miei campi con il codice, così è più semplice spostarli da un progetto a un altro.

Ecco il primo motivo che mi ha spinto verso Metabox.io.

Anche se offre un editor online e un’estensione per la creazione di nuovi campi con il punta-e-clicca di base lavora dichiarando i campi come semplici array!

Il progetto inoltre è aggiornato quasi quotidianamente e ha anche un forum di supporto dove gli utenti si rispondono a vicenda per risolvere i propri problemi.

Non voglio fare il fan sfegatato di Metabox.io, anche se un po’ lo sono diventato, ma questo progetto mi è piaciuto talmente tanto che ho deciso di acquistare una licenza lifetime del progetto.

Installa Metabox.io come libreria attraverso Composer

Leggendo la documentazione su Metabox.io è facile accorgersi che viene suggerito l’uso di questa libreria attraverso l’installazione del plugin che si trova nel repository WordPress, attività che potresti svolgere anche attraverso l’uso della TGM Activation Library che ti ho già presentato.

Però c’è da dire che noi sviluppatori non sempre vogliamo mostrare al cliente quali sono gli strumenti che utilizziamo, quindi lasciarne traccia nella lista dei plugin utilizzati non sempre risulta essere una scelta professionale.

Ecco perché puoi usare i plugin e le estensioni di Metabox.io anche come semplice pacchetto da installare attraverso Composer.

Lo sviluppatore del progetto ci mette a disposizione un file composer.json che ci aiuta a trovare i nomi corretti per i pacchetti installabili attraverso Composer, per gli scopi di questo articolo abbiamo bisogno soltanto del core e dell’estensione MB Blocks.

{
   "repositories":[
      {
         "type":"composer",
         "url":"https://wpackagist.org"
      },
      {
         "type":"composer",
         "url":"https://packages.metabox.io/TUALICENZA"
      }
   ],
   "require":{
      "wpackagist-plugin/meta-box":"dev-trunk",
      "meta-box/mb-blocks":"dev-master"
   },
   "extra":{
      "installer-paths":{
         "vendor/meta-box/meta-box":[
            "wpackagist-plugin/meta-box"
         ],
         "vendor/meta-box/{$name}/":[
            "vendor:meta-box"
         ]
      }
   },
   "autoload":{
      "files":[
         "vendor/meta-box/meta-box/meta-box.php",
         "vendor/meta-box/mb-blocks/mb-blocks.php"
      ]
   }
}

Una volta salvato questo codice nel file composer.json nella cartella del tuo plugin o tema puoi lanciare composer install e lasciare che tutti i pacchetti di cui hai bisogno si installino in automatico all’interno del tuo progetto.

Ora che abbiamo installato Metabox e MB Blocks come pacchetti interni al nostro progetto dobbiamo caricare il loro codice per poterlo utilizzare nel nostro plugin.

Un’altra utilità di Composer è la generazione automatica di un autoloader, un file PHP che si occupererà di caricare al posto nostro tutti i pacchetti che andiamo ad installare con il suo supporto.

Tutto quello che ti resta da fare è richiamarlo all’interno del file principale del plugin, nel nostro caso questo file prende il nome di sam-mb-blocks.php.

Sotto ai commenti corrispondendi alla dichiarazione del plugin in WordPress non devi far altro che aggiungere quanto segue:

// Carico i pacchetti installati da Composer.
require plugin_dir_path( __FILE__ ) . 'vendor/autoload.php';

Con questa riga di codice adesso il tuo progetto caricherà automaticamente tutte le librerie che hai installato con Composer e tu non dovrai far altro che utilizzarle nel tuo progetto.

La struttura del plugin che andremo a realizzare

Mentre scrivevo l’articolo mi sono accorto che non ti ho fornito alcuna indicazione del progetto che stiamo realizzando.

Cercando di non allungare troppo il testo voglio dirti che una volta completata la lettura di questo articolo avrai creato il tuo primo blocco Gutenberg (con Metabox.io) che si presenterà come un blocco per creare delle alert box.

La struttura del plugin è molto semplice.

Nella cartella principale del progetto, che nel nostro caso prenderà il nome di sam-mb-blocks/, dovrai creare i seguenti file e cartelle:

• sam-mb-blocks.php – il file principale del plugin dove viene dichiarata la sua intestazione includendo sia le costanti che i file principali con i quali lavoreremo,
• blocks/ – questa cartella conterrà tutti i blocchi che andremo a realizzare,
  • alert-box/ – in questa cartella, interna a blocks/, verranno salvati tutti i file relativi alla creazione del nostro blocco

Questa è la struttura di base del progetto che stiamo realizzando, puoi modificarla a tuo piacimento per soddisfare le tue necessità.

Le opzioni a disposizione per creare il blocco

Una tra le prime cose che mi sono saltate agli occhi quando ho letto come creare un blocco Gutenberg nell’handbook di WordPress, a parte dover registrare il blocco sia in JavaScript che in PHP, è stato il grandissimo numero di opzioni che possiamo impostare.

Certo creare un blocco con Metabox.io non riduce il numero di opzioni ma almeno ci permette di registrare il nostro blocco esclusivamente in PHP.

Crea il tuo primo blocco con Metabox.io

Creare un nuovo blocco con questa libreria è incredibilmente semplice e intuitivo perché se sai come creare un meta box con la sua sintassi hai già tutto quello che ti serve per partire!

Apriamo quindi il file sam-mb-blocks.php e sotto all’inclusione dell’autoloader inseriamo quanto segue:

add_filter( 'rwmb_meta_boxes', 'sam_mb_boxes' );
/**
 * Funzione generale per dichiarare tutti i blocchi creati con Metabox.io
 *
 * @param array $meta_boxes L'array che contiene tutti i blocchi e meta box dichiarati.
 *
 * @return array $meta_boxes
 */
function sam_mb_boxes( $meta_boxes ) {
	$prefix = 'sam-b';
  
	// Dichiaro il mio primo blocco.
	$meta_boxes[] = [
		'title' => __( 'SAM Alert Box', 'sam-mb-blocks' ),
		'id' => $prefix . '-alert-box',
		'description' => __( 'Un semplice Alert Box creato con Metabox.io', 'sam-mb-blocks' ),
		'type' => 'block',
		'icon' => 'awards',
		'category' => 'layout',
		'context' => 'side',
		'fields' => [
			[
				'type' => 'text',
				'id' => 'title',
				'name' => 'Titolo',
			],
			[
				'type' => 'textarea',
				'id' => 'text',
				'name' => 'Testo',
			],
		],
	];

	return $meta_boxes;
}

Questa è una sintassi molto base quando lavori con Metabox.io, agganciamo una nostra funzione al filtro rwmb_meta_boxes con la quale modifico l’array $meta_boxes passato come parametro. Modificare l’array mi permette di aggiungere i miei, in questo caso, blocchi.

Non voglio addentrarmi troppo nella configurazione di nuove meta box (se lo richiedi lo farò in un articolo dedicato) ma voglio mettere in luce le configurazioni più interessanti per lo scopo di questo articolo.

• type – questo parametro ci permette di specificare qualsiasi tipo di meta box, nel nostro caso utilizziamo block per indicare che stiamo creando un nuovo blocco,
• icon – permette di impostare un’icona per il blocco che stiamo creando. Questa può essere semplicemente una Dashicon oppure una tua SVG,
• category – specifica la categoria all’interno della quale inserire il nuovo blocco, se registri una tua categoria di blocchi puoi usare quella,
• context – permette di specificare dove mostrare il modulo per l’inserimento dei dati da usare nel blocco, nella sidebar (side) o direttamente nel blocco (basta ometterlo),
• fields – seguendo la classica sintassi di Metabox.io all’interno di questo array puoi dichiarare tutti i campi di cui hai bisogno per il tuo blocco.

Questi sono i principali parametri che ci permettono di configurare un blocco Gutenberg utilizzando Metabox.io ma c’è di più perché non ho ancora detto come utilizzare le informazioni che stai richiedendo attraverso i campi all’interno del tuo blocco.

Il codice che ti ho mostrato fino a ora funzionerà soltanto per mostrare il modulo che raccoglierà i dati perché non abbiamo ancora detto a Metabox.io come mostrarle.

Questo succede perché al momento ho omesso alcuni parametri che possono essere utilizzati per questo scopo e che scopriremo nella prossima sezione di questo articolo.

Definisci template e stili separatamente

Ci siamo già semplificati molto la vita creando un blocco senza utilizzare JavaScript e complessi sistemi di compilazione del nostro codice con Webpack ma Metabox.io non può certo fare tutto da solo!

È giunto il momento di scoprire come utilizzare i dati che verranno inseriti dall’utente che utilizzerà il nostro blocco.

Per fare questo Metabox.io ci mette a disposizione due opzioni.

Con la prima possiamo creare il codice necessario al nostro blocco dichiarando una funzione (render_callback) nello stesso file mentre la seconda opzione ci permette di dichiarare un file PHP esterno che Metabox.io utilizzerà per generare il nostro blocco.

Il secondo metodo è quello che useremo all’interno di questo articolo e prende il nome di render_template.

A questo punto non dobbiamo far altro che inserire questo parametro seguito dal percorso al file e iniziare a creare la view del nostro nuovo blocco.

...
'context' => 'side',
'render_template' => plugin_dir_path( __FILE__ ) . 'blocks/alert-box/template.php',
'fields' => [
  ...
],
...

Ho semplificato il codice ma spero tu possa capire lo stesso, in fin dei conti aggiungo il parametro render_template all’interno della configurazione del nuovo meta box e specifico il percorso al file.

Nel nostro esempio il percorso corretto rispetta la struttura che ti ho presentato per questo plugin, ovvero abbiamo una cartella blocks/ che conterrà tutti i nostri blocchi.

Nel nostro caso il nuovo file template per generare il blocco si troverà in alert-box/template.php.

Cerchiamo di capire cosa inserire al suo interno.

Per prima cosa devi sapere che come per la funzione di callback render_callback abbiamo a disposizione tre parametri che vengono passati dal blocco:

• $attributes – un array che contiene tutti i valori che vengono passati dal blocco,
• $is_preview – semplice valore booleano che ci permette di sapere se siamo all’interno dell’editor o nel frontend,
• $post_id – l’ID del post che viene utilizzato.

Grazie a questi tre valori possiamo fare praticamente di tutto.

La prima cosa che dobbiamo fare è assicurarsi che abbiamo dei dati a disposizione con i quali lavorare.

// Controllo che siano stati passati dei dati.
if ( empty( $attributes['data'] ) ) {
	return;
}

Ora che sappiamo che i dati sono stati passati possiamo iniziare a organizzare meglio il nostro codice e creare un ID e una classe che vengono utilizzati all’interno del blocco.

// Se disponibile imposto un ID.
$block_id = $attributes['id'] ?? '';

// Imposto una classe per il blocco.
$block_class = 'alert-box';

Fatte queste operazioni di routine è giunto il momento di creare il nostro codice HTML che permetterà di visualizzare i dati che l’utente ha inserito.

$html = '<div id="' . $block_id . '" class="' . $block_class . '">';
$html .= '<h3>' . mb_get_block_field( 'title' ) . '</h3>';
$html .= '<p>' . mb_get_block_field( 'text' ) . '</p>';
$html .= '</div>';

echo $html;

All’interno del blocco di codice precedente è stata inserita una funzione che ancora non conosci: mb_get_block_field()

La funzione mb_get_block_field() è stata creata dal team di Metabox.io per semplificarci la vita quando dobbiamo prendere i dati utilizzati all’interno del blocco, se devi soltanto mostrarli puoi usare mb_the_block_fiels().

Entrambe queste funzioni accettano un singolo parametro, l’id del campo che è stato creato all’interno dell’array fields in sam-mb-blocks.php.

Se adesso provi a creare un nuovo articolo o pagina nella tua installazione WordPress troverai il nuovo SAM Alert Box disponibile all’interno dei blocchi raccolti nella categoria “Elementi del layout”.

Però adesso che abbiamo definito il template che genererà l’HTML del nostro blocco dobbiamo aggiungere soltanto gli stili CSS che lo renderanno unico.

Come fare?

Anche in questo caso la soluzione è molto semplice e non dovrai fare altro che aprire nuovamente il file sam-mb-blocks.php e aggiungere il nuovo parametro enqueue_style per indicare il percorso al file CSS.

...
'render_template' => plugin_dir_path( __FILE__ ) . 'blocks/alert-box/template.php',
'enqueue_style' => plugin_dir_url( __FILE__ ) . 'blocks/alert-box/style.css',
'fields' => [
  ...
],
...

Ora puoi dichiarare tutti gli stili che desideri per personalizzare gli elementi presenti all’interno del tuo blocco. Per esempio io ho realizzato qualcosa di questo tipo:

Ovviamente non sei costretto a includere un solo file CSS ma questo articolo sta diventando troppo lungo e non voglio approfittarmi del tuo tempo, per questo motivo ho deciso di concludere questa sezione presentandoti velocemente altri due parametri che ti potranno aiutare a personalizzare i blocchi che creerai con Metabox.io:

• enqueue_script – permette di indicare il percorso a un file JavaScript, ricorda jQuery è già caricato in WordPress;
• enqueue_assets – a differenza di enqueue_style o enqueue_script, dove puoi collegare un solo file, grazie a questo potrai caricare tutti gli asset di cui hai bisogno grazie alla funzione di callback.

Limiti e curiosità di questa soluzione

Adesso hai tutto quello che ti serve per creare i tuoi blocchi grazie all’aiuto di Metabox.io e dell’estensione MB Blocks però prima di salutarti vorrei condividere con te un paio di riflessioni che ho avuto mentre utilizzavo questa soluzione.

Mancanza di una live preview

Il primissimo limite che trovo in questa soluzione è che manca l’esperienza di modifica diretta che ci offrono i blocchi Gutenberg.

Il nostro utente dovrà comunque passare dalla preview alla funzionalità di editing per compilare i propri campi, non importa che si usi context o meno.

Certo non è assolutamente niente di così limitante e una volta che si è presa la mano a utilizzare questi blocchi diventerà una seconda natura però è un punto che desidero sollevare perché sicuramente creare blocchi con Metabox.io non è la soluzione a tutti i nostri problemi.

Lavorare con i campi messi a disposizione

Metabox.io offre veramente moltissimi campi che possiamo utilizzare nei nostri blocchi e nelle nostre Meta Box però possiamo utilizzare soltanto quelli.

Ti faccio un veloce esempio.

Io desidero creare un blocco per mostrare blocchi di codice all’interno dei miei articoli ma non posso farlo perché tra gli innumerevoli campi offerti non c’è alcun campo dedicato al codice.

Potrei utilizzare una textarea come faccio per il campo testo del blocco appena realizzato ma non è la soluzione ideale perché il codice inserito non sempre viene mostrato (per motivi di sicurezza viene automaticamente ripulito con un escape) e soprattutto non rende facile l’inserimento del codice dato che una textarea non è in grado di gestire correttamente le spaziature.

Mentre se creo un blocco Gutenberg nativo potrei anche richiamare un web component già pronto dedicato.

Minore possibilità di personalizzazione

Lavorare con Metabox.io è molto piacevole e mi vedrai tornare spesso a parlare di questa potente libreria ma quando si utilizzano degli strumenti che ci semplificano la vita in molti casi la nostra capacità di personalizzazione viene limitata.

L’esempio precedente del blocco di codice è, appunto, solo un esempio ma credo che sia sufficiente per farti capire quello che intendo.

È lo stesso motivo per il quale sconsiglio l’uso di un qualsiasi page builder, se vuoi essere uno sviluppatore WordPress ti capitera di raggiungere molto spesso i limiti di queste soluzioni e a questo punto dovrai:

1. creare un add-on per il page builder in questione,
2. diventare matto cercando soluzioni online.

Se credi di aver bisogno di un totale controllo il mio consiglio è quello di studiare React.js (cosa che potrai fare anche con futuri articoli e corsi che pubblicheremo) e imparare a creare i tuoi blocchi Gutenberg!

Conclusioni

Spero che questo articolo ti abbia aiutato a scoprire una soluzione utile per proporre blocchi Gutenberg personalizzati ai tuoi clienti.

In fin dei conti Metabox.io e tutte le sue estensioni sono state create proprio per questo, come una soluzione per semplificare la vita a noi sviluppatori.

In questo articolo ti ho presentato soltanto l’estensione MB Blocks ma grazie a questa libreria potrai fare molto altro!

Ritengo che questa soluzione sia ottima per tutti quei progetti che hanno un basso budget dove il tempo risulta è la risorsa più preziosa che abbiamo a disposizione ma se accetti un consiglio: impara anche a creare blocchi Gutenberg nativi.

Almeno questo è quello che farò io ?