I custom field permettono di assegnare informazioni aggiuntive ai contenuti del sito. Queste informazioni sono di solito note come metadati.

I metadati sono informazioni sulle informazioni. Nel caso di WordPress, si tratta di informazioni associate a post, utenti, commenti e termini.

Data la relazione molti-a-uno dei metadati in WordPress, le opzioni sono praticamente illimitate. Si possono quante opzioni di metadati si desiderano ed è possibile memorizzarci qualsiasi cosa.

–Plugin Handbook

Ecco alcuni esempi di metadati che possono essere allegati ad un post usando i custom field:

  • Le coordinate geografiche di un luogo o di una proprietà immobiliare
  • La data di un evento
  • L’ISBN o l’autore di un libro
  • L’umore di chi scrive l’articolo

E ce ne sono molti altri.

In WordPress non c’è un modo semplice per aggiungere e gestire i campi personalizzati. Nell’editor classico, i custom field sono visualizzati in un riquadro posto in fondo alla pagina, sotto l’editor degli articoli.

Schermata dell’editor classico di WordPress
Campi personalizzati nell’editor classico.

In Gutenberg, di default i custom field sono disabilitati, ma possono essere visualizzati selezionando la voce corrispondente nelle impostazioni dell’articolo.

Schermata dei campi personalizzati nell’editor a blocchi
Aggiungere il pannello dei campi personalizzati all’editor dei blocchi.

Purtroppo non esiste un modo per visualizzare i metadati nel frontend senza usare un plugin o sporcarsi le mani con il codice.

Se siete utenti WordPress, troverete diversi ottimi plugin che fanno questo lavoro al posto vostro. Ma se lavorate come developer e volete ottenere di più dai custom field di WordPress, integrarli perfettamente nell’editor di blocchi e visualizzarli sul frontend del vostro sito WordPress tramite un blocco Gutenberg personalizzato, allora siete nel posto giusto.

Quindi, se vi state chiedendo quale sia il modo migliore per utilizzare i campi personalizzati di WordPress sia in Gutenberg che nell’editor classico per chi sviluppa con WordPress, la risposta è “creare un plugin che funzioni sia per l’editor classico che per Gutenberg”.

Ma non preoccupatevi. Se creare un plugin per gestire i campi personalizzati in entrambi gli editor potrebbe sembrare un po’ complicato, cercheremo di rendere il processo il più semplice possibile. Una volta compresi i concetti di cui parleremo in questo articolo, acquisirete le competenze necessarie per gestire i “meta field” personalizzati in Gutenberg e realizzare siti web di ogni tipo.

Nota: prima di fare qualsiasi cosa, assicuratevi di avere una versione aggiornata di Node.js sul vostro computer

Detto questo, ecco di cosa ci occuperemo:

Creare un Plugin a Blocchi con lo Strumento Ufficiale create-block

Il primo passo consiste nel creare un nuovo plugin con tutti i file e le dipendenze necessarie per registrare un nuovo tipo di blocco. Il plugin di blocco vi permetterà di creare facilmente un tipo di blocco personalizzato per la gestione e la visualizzazione di metadati personalizzati.

Per creare un nuovo tipo di blocco, useremo lo strumento ufficiale create-block. Per una panoramica dettagliata su come usare lo strumento create-block, leggete il nostro precedente articolo sullo sviluppo dei blocchi di Gutenberg.

Aprite il vostro strumento per riga di comando, andate nella directory dei plugin del vostro sito web di sviluppo di WordPress ed eseguite il seguente comando:

npx @wordpress/create-block

Quando vi viene richiesto, aggiungete i seguenti dettagli:

  • La variante del template da usare per questo blocco: dynamic
  • Lo slug del blocco usato per l’identificazione (anche il nome della cartella di output): metadata-block
  • Il namespace interno per il nome del blocco (qualcosa di unico per i vostri prodotti): meta-fields
  • Il titolo del blocco: Meta Fields
  • La breve descrizione del blocco (facoltativa): Descrizione del blocco
  • La dashicon per facilitare l’identificazione del vostro blocco (opzionale): book
  • Il nome della categoria per aiutare gli utenti a sfogliare e scoprire il vostro blocco: widget
  • Volete personalizzare il plugin di WordPress? Sì/No

Esaminiamo un attimo questi dettagli e cerchiamo di capire dove vengono utilizzati.

  • Lo slug del blocco utilizzato per l’identificazione definisce il nome della cartella e il dominio di testo del plugin.
  • Il namespace interno per il nome del blocco definisce il namespace del blocco e il prefisso delle funzioni utilizzato nel codice del plugin.
  • Il titolo del blocco definisce il nome del plugin e il nome del blocco utilizzato nell’interfaccia dell’editor.

La configurazione può richiedere un paio di minuti. Al termine del processo, otterrete un elenco dei comandi disponibili.

Schermata della riga di comando che conferma che il plugin Blockè stato installato
Il plugin Block è stato installato correttamente.

Prima di passare alla sezione successiva, nel vostro strumento a riga di comando, navigate nella cartella del plugin ed eseguite i seguenti comandi:

cd metadata-block
npm start

Ora tutto è pronto per costruire il codice. Il passo successivo consiste nel modificare il file PHP principale del plugin per creare un meta box per l’editor classico.

Quindi, prima di passare alla prossima sezione, installate e attivate il plugin Classic Editor.

Poi aprite la schermata dei plugin e attivate il nuovo plugin Meta Fields.

Schermata dei Plugins di WordPress con Classic Editor e Meta Fields attivati
Attivate i plugin.

Aggiungere un Meta Box all’Editor Classico

Nel contesto dell’editor classico, un meta box è un contenitore che contiene elementi del modulo per digitare informazioni specifiche, come l’autore del post, i tag, le categorie, ecc.

Oltre alle meta box integrate, chi sviluppa plugin può aggiungere un numero qualsiasi di meta box personalizzate per includere elementi di form HTML (o qualsiasi contenuto HTML) in cui gli utenti del plugin possono inserire dati specifici del plugin.

L’API di WordPress fornisce utili funzioni per registrare facilmente meta box personalizzate per includere tutti gli elementi HTML di cui il vostro plugin ha bisogno per funzionare.

Per iniziare, aggiungete il seguente codice al file PHP del plugin che avete appena creato:

// register meta box
function meta_fields_add_meta_box(){
    add_meta_box(
   	 'meta_fields_meta_box',
   	 __( 'Book details' ),
   	 'meta_fields_build_meta_box_callback',
   	 'post',
   	 'side',
   	 'default'
     );
}

// build meta box
function meta_fields_build_meta_box_callback( $post ){
      wp_nonce_field( 'meta_fields_save_meta_box_data', 'meta_fields_meta_box_nonce' );
      $title = get_post_meta( $post->ID, '_meta_fields_book_title', true );
      $author = get_post_meta( $post->ID, '_meta_fields_book_author', true );
      ?>
      <div class="inside">
     	   <p><strong>Title</strong></p>
   	   <p><input type="text" id="meta_fields_book_title" name="meta_fields_book_title" value="<?php echo esc_attr( $title ); ?>" /></p>    
   	   <p><strong>Author</strong></p>
   	   <p><input type="text" id="meta_fields_book_author" name="meta_fields_book_author" value="<?php echo esc_attr( $author ); ?>" /></p>
      </div>
      <?php
}
add_action( 'add_meta_boxes', 'meta_fields_add_meta_box' );

La funzione add_meta_box registra un nuovo meta box, mentre la funzione di callback crea l’HTML da iniettare nel meta box. Non approfondiremo questo argomento perché esula dagli scopi del nostro articolo, ma troverete tutti i dettagli necessari nella documentazione sull’hook add_meta_boxes, su quella della funzione add_meta_box() e in questo articolo di Smashing Magazine.

Il passo successivo è quello di creare una funzione che salvi i dati inseriti di chi ha scritto il post ogni volta che viene attivato l’hook save_post (si veda le Developer Resources):

// save metadata
function meta_fields_save_meta_box_data( $post_id ) {
    if ( ! isset( $_POST['meta_fields_meta_box_nonce'] ) )
   	 return;
    if ( ! wp_verify_nonce( $_POST['meta_fields_meta_box_nonce'], 'meta_fields_save_meta_box_data' ) )
   	 return;
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE )
   	 return;
    if ( ! current_user_can( 'edit_post', $post_id ) )
   	 return;

    if ( ! isset( $_POST['meta_fields_book_title'] ) )
   	 return;
    if ( ! isset( $_POST['meta_fields_book_author'] ) )
   	 return;

    $title = sanitize_text_field( $_POST['meta_fields_book_title'] );
    $author = sanitize_text_field( $_POST['meta_fields_book_author'] );

    update_post_meta( $post_id, '_meta_fields_book_title', $title );
    update_post_meta( $post_id, '_meta_fields_book_author', $author );
}
add_action( 'save_post', 'meta_fields_save_meta_box_data' );

Anche in questo caso, consultate la documentazione online per maggiori dettagli. Qui ci limiteremo ad evidenziare il carattere di sottolineatura (_) che precede la meta key. Questo indica a WordPress di nascondere le chiavi di questi campi personalizzati dall’elenco dei campi personalizzati disponibili per impostazione predefinita e rende i vostri campi personalizzati visibili solo nel vostro meta box personalizzato.

L’immagine seguente mostra l’aspetto del meta box personalizzato nell’editor classico:

Schermata di una Meta Box nell’editor classico
Un meta box personalizzato nell’editor classic.

Ora, se disattivate il plugin Classic Editor e controllate cosa succede nell’editor a blocchi, vedrete che il meta box appare e funziona ancora, ma non esattamente nel modo in cui vi aspettereste.

Il nostro obiettivo è quello di creare un sistema per la gestione dei metadati allegati agli articoli del blog o ai tipi di post personalizzati che si integri perfettamente nell’editor a blocchi. Per questo motivo, il codice mostrato finora sarà necessario solo per garantire la compatibilità con l’editor classico.

Quindi, prima di proseguire, indicheremo a WordPress di rimuovere il meta box personalizzato dall’editor a blocchi aggiungendo il flag __back_compat_meta_box alla funzione add_meta_box (si veda anche Meta Box Compatibility Flags e Backward Compatibility).

Torniamo alla funzione di callback che registra il meta box e modifichiamola come segue:

// register meta box
function meta_fields_add_meta_box(){
    add_meta_box(
   	 'meta_fields_meta_box',
   	 __( 'Book details' ),
   	 'meta_fields_build_meta_box_callback',
   	 'post',
   	 'side',
   	 'default',
   	 // hide the meta box in Gutenberg
   	 array('__back_compat_meta_box' => true)
     );
}

Salvate il file del plugin e tornate nell’amministrazione di WordPress. Ora non dovreste più vedere il meta box personalizzato nell’editor dei blocchi. Se invece riattivate l’editor classico, il meta box personalizzato verrà visualizzato di nuovo.

Aggiungere Custom Meta Field all’Editor a Blocchi di Gutenberg (3 Opzioni)

Nei nostri precedenti articoli sullo sviluppo dei blocchi di Gutenberg, abbiamo fornito una panoramica dettagliata dell’editor, delle sue parti e di come sviluppare blocchi statici e blocchi dinamici.

Come abbiamo detto, in questo articolo faremo un ulteriore passo avanti e parleremo di come aggiungere custom meta field agli articoli del blog.

Esistono diversi modi per memorizzare e utilizzare i metadati degli articoli in Gutenberg. In questo articolo tratteremo i seguenti:

Creare un Blocco Personalizzato per Memorizzare e Visualizzare i Custom Meta Field

In questa sezione vi mostreremo come creare e gestire i custom meta field all’interno di un blocco dinamico. Secondo il Manuale dell’editor di blocchi, un meta-field di un post “è un oggetto di WordPress utilizzato per memorizzare dati extra su un post” e dobbiamo registrare un nuovo meta-field prima di poterlo utilizzare.

Registrare i Custom Meta Field

Prima di registrare un custom meta field, dovete assicurarvi che il tipo di post che lo utilizzerà supporti i campi personalizzati. Inoltre, quando registrate un custom meta field, dovete impostare il parametro show_in_rest su true.

Ora torniamo al file del plugin. Aggiungete il seguente codice:

/**
 * Register the custom meta fields
 */
function meta_fields_register_meta() {

	$metafields = [ '_meta_fields_book_title', '_meta_fields_book_author' ];

	foreach( $metafields as $metafield ){
    	// Pass an empty string to register the meta key across all existing post types.
    	register_post_meta( '', $metafield, array(
        	'show_in_rest' => true,
        	'type' => 'string',
        	'single' => true,
        	'sanitize_callback' => 'sanitize_text_field',
        	'auth_callback' => function() {
            	return current_user_can( 'edit_posts' );
        	}
    	));
	}  
}
add_action( 'init', 'meta_fields_register_meta' );

register_post_meta registra un meta field per i tipi di post specificati. Nel codice qui sopra, abbiamo registrato due custom meta field per tutti i tipi di post registrati sul vostro sito web che supportano i campi personalizzati. Per maggiori informazioni, consultate il riferimento alla funzione.

Una volta fatto, aprite il file src/index.js del vostro plugin a blocchi.

Registrare il Tipo di Blocco sul Client

Ora andate nella cartella wp-content/plugins/metadata-block/src e aprite il file index.js:

import { registerBlockType } from '@wordpress/blocks';
import './style.scss';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata.name, {
    edit: Edit,
} );

Con i blocchi statici avremmo visto anche una funzionesave. In questo caso, la funzione save è assente perché abbiamo installato un blocco dinamico. Il contenuto mostrato nel frontend sarà generato dinamicamente tramite PHP.

Creare il Tipo di Blocco

Andate alla cartella wp-content/plugins/metadata-block/src e aprite il file edit.js. Dovreste vedere il seguente codice (commenti rimossi):

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
    return (
   	 <p { ...useBlockProps() }>
   		 { __( 'Meta Fields – hello from the editor!', 'metadata-block' ) }
   	 </p>
    );
}

Qui aggiungerete il codice per generare il blocco da visualizzare nell’editor.

Il primo passo è importare i componenti e le funzioni necessarie per creare il blocco. Ecco l’elenco completo delle dipendenze:

import { __ } from '@wordpress/i18n';
import { useBlockProps, InspectorControls, RichText } from '@wordpress/block-editor';
import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';
import { TextControl, PanelBody, PanelRow } from '@wordpress/components';
import './editor.scss';

Se avete letto i nostri articoli precedenti, dovreste conoscere molte di queste dichiarazioni di import. Qui ne indicheremo solo un paio:

import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';

Una volta importate queste dipendenze, ecco come useSelect e useEntityProp vengono inserite nella funzione Edit():

const postType = useSelect(
   	 ( select ) => select( 'core/editor' ).getCurrentPostType(),
   	 []
    );
const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );
  • useSelect è un hook personalizzato per recuperare le proprietà dai selettori registrati. Lo useremo per recuperare il tipo di post corrente (si veda anche il riferimento @wordpress/data e l’introduzione a useDispatch e useSelect)
  • useEntityProp è un hook personalizzato che permette ai blocchi di recuperare e modificare i meta field degli articoli. È definito come un “hook che restituisce il valore e un setter per la proprietà specificata dell’entità più vicina fornita del tipo specificato”. Restituisce “un array in cui il primo elemento è il valore della proprietà, il secondo è il setter e il terzo è l’oggetto valore completo dell’API REST contenente ulteriori informazioni come raw, rendered e protected props” (si veda anche General Block Editor API Updates).

Questo codice fornisce l’attuale postType, un oggetto di meta field (meta) e una funzione setter per aggiornarli (setMeta).

Ora sostituite il codice attuale della funzione Edit() con il seguente:

export default function Edit() {
    const blockProps = useBlockProps();
    const postType = useSelect(
   	 ( select ) => select( 'core/editor' ).getCurrentPostType(),
   	 []
    );
    const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );
    const bookTitle = meta[ '_meta_fields_book_title' ];
    const bookAuthor = meta[ '_meta_fields_book_author' ];
    const updateBookTitleMetaValue = ( newValue ) => {
   	 setMeta( { ...meta, _meta_fields_book_title: newValue } );
	};
    const updateBookAuthorMetaValue = ( newValue ) => {
   	 setMeta( { ...meta, _meta_fields_book_author: newValue } );
    };
return ( ... );
}

Di nuovo:

  • Abbiamo usato useSelect per ottenere il tipo di post corrente.
  • useEntityProp restituisce un array di meta field e una funzione setter per impostare i nuovi valori dei meta.
  • updateBookTitleMetaValue e updateBookAuthorMetaValue sono due gestori di eventi per salvare i valori dei meta campi.

Il passo successivo è costruire il codice JSX (JavaScript XML) restituito dalla funzione Edit():

export default function Edit() {
    ...
    return (
   	 <>
   		 <InspectorControls>
   			 <PanelBody
   				 title={ __( 'Book Details' )}
   				 initialOpen={true}
   			 >
   				 <PanelRow>
   					 <fieldset>
   						 <TextControl
   							 label={__( 'Book title' )}
   							 value={ bookTitle }
   							 onChange={ updateBookTitleMetaValue }
   						 />
   					 </fieldset>
   				 </PanelRow>
   				 <PanelRow>
   					 <fieldset>
   						 <TextControl
   							 label={ __( 'Book author' ) }
   							 value={ bookAuthor }
   							 onChange={ updateBookAuthorMetaValue }
   						 />
   					 </fieldset>
   				 </PanelRow>
   			 </PanelBody>
   		 </InspectorControls>
   		 <div { ...blockProps }>
   			 <RichText
   				 tagName="h3"
   				 onChange={ updateBookTitleMetaValue }
   				 allowedFormats={ [ 'core/bold', 'core/italic' ] }
   				 value={ bookTitle }
   				 placeholder={ __( 'Write your text...' ) }
   			 />
   			 <TextControl
   				 label="Book Author"
   				 value={ bookAuthor }
   				 onChange={ updateBookAuthorMetaValue }
   			 />
   		 </div>
   	 </>
    );
}

Il componente RichText fornisce un input contenteditable, mentre TextControl fornisce semplici campi di testo.

Abbiamo anche creato un pannello laterale contenente due campi di input da utilizzare al posto dei due controlli inclusi nel blocco.

Salvate il file e tornate all’editor. Aggiungete il blocco Meta Fields dall’inseritore di blocchi e inserite il titolo e l’autore del libro.

Schermata di un blocco personalizzato che include due custom meta field.
Un blocco personalizzato che include due custom meta field.

Noterete che ogni volta che modificate il valore del campo nel blocco, cambierà anche il valore del campo di testo corrispondente nella barra laterale.

Successivamente, dobbiamo creare il codice PHP che genera l’HTML da visualizzare nel frontend.

Visualizzare il Blocco nel Frontend

Aprite nuovamente il file PHP principale nel vostro editor di codice e riscrivete la funzione di callback che genera l’output del blocco come segue:

function meta_fields_metadata_block_block_init() {
    register_block_type(
   	 __DIR__ . '/build',
   	 array(
   		 'render_callback' => 'meta_fields_metadata_block_render_callback',
   	 )
    );
}
add_action( 'init', 'meta_fields_metadata_block_block_init' );

function meta_fields_metadata_block_render_callback( $attributes, $content, $block ) {
    
    $book_title = get_post_meta( get_the_ID(), '_meta_fields_book_title', true );
    $book_author = get_post_meta( get_the_ID(), '_meta_fields_book_author', true );
    
    $output = "";

    if( ! empty( $book_title ) ){
   	 $output .= '<h3>' . esc_html( $book_title ) . '</h3>';
    }
    if( ! empty( $book_author ) ){
   	 $output .= '<p>' . __( 'Book author: ' ) . esc_html( $book_author ) . '</p>';
    }
    if( strlen( $output ) > 0 ){
   	 return '<div ' . get_block_wrapper_attributes() . '>' . $output . '</div>';
    } else {
   	 return '<div ' . get_block_wrapper_attributes() . '>' . '<strong>' . __( 'Sorry. No fields available here!' ) . '</strong>' . '</div>';
    }
}

Questo codice si spiega da solo. Per prima cosa, usiamo get_post_meta per recuperare i valori dei custom meta field. Poi usiamo questi valori per costruire il contenuto del blocco. Infine, la funzione di callback restituisce l’HTML del blocco.

Il blocco è pronto per essere utilizzato. Abbiamo volutamente mantenuto il codice di questo esempio il più semplice possibile, ma utilizzando i componenti nativi di Gutenberg potete creare blocchi più avanzati e ottenere il massimo dai custom meta field di WordPress.

Schermata di un blocco personalizzato che include diversi campi personalizzati.
Un blocco personalizzato che include diversi meta campi.

Nel nostro esempio, abbiamo usato gli elementi h3 e p per costruire il blocco per il frontend.

Ma potete visualizzare i dati in molti modi. L’immagine seguente mostra un semplice elenco non ordinato di meta campi.

Schermata con esempio di blocco nel frontend
Un esempio di blocco nel frontend.

Potete trovare il codice completo di questo esempio in questo gist pubblico.

Aggiungere un Custom Meta Field alla Barra Laterale del Documento

La seconda opzione consiste nell’aggiungere custom meta field agli articoli utilizzando un plugin che genera un pannello di impostazioni nella barra laterale del documento.

Il processo è abbastanza simile a quello dell’esempio precedente, ma in questo caso non avremo bisogno di un blocco per gestire i metadati. Creeremo un componente per generare un pannello con una serie di controlli nella barra laterale del documento seguendo questi passaggi:

  1. Creare un nuovo plugin di blocco con create-block
  2. Registrare un meta field personalizzato per l’editor classico
  3. Registrare i custom meta field nel file principale del plugin tramite la funzione register_post_meta()
  4. Registrare un plugin nel file index.js
  5. Costruire il componente usando i componenti integrati di Gutenberg

Creare un Nuovo Plugin di Blocco con lo Strumento create-block

Per creare un nuovo plugin a blocchi, seguite i passi della sezione precedente. Potete creare un nuovo plugin o modificare gli script costruiti nell’esempio precedente.

Registrare un Meta Box Personalizzato per l’Editor Classico

Successivamente, dovete registrare un meta box personalizzato per garantire la compatibilità con i siti web WordPress che usano ancora l’editor classico. La procedura è la stessa descritta nella sezione precedente.

Registrare i Custom Meta Field nel File Principale del Plugin

Il passo successivo consiste nel registrare i custom meta field nel file principale del plugin tramite la funzione register_post_meta(). Anche in questo caso, potete seguire l’esempio precedente.

Registrare un Plugin nel File index.js

Una volta completati i passaggi precedenti, è il momento di registrare un plugin nel file index.js per rendere un componente personalizzato.

Prima di registrare il plugin, create una cartella components all’interno della cartella src del plugin. All’interno della cartella components, create un nuovo file MetaBox.js. Potete scegliere il nome che ritenete più adatto per il vostro componente, seguendo le best practice di denominazione in React.

Prima di proseguire, installate il modulo @wordpress/plugins dal vostro strumento a riga di comando.

Interrompete il processo (mac), installate il modulo e avviate nuovamente il processo:

^C
npm install @wordpress/plugins --save
npm start

Una volta terminato, aprite il file index.js del vostro plugin e aggiungete il seguente codice.

/**
 * Registers a plugin for adding items to the Gutenberg Toolbar
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/
 */
import { registerPlugin } from '@wordpress/plugins';

import MetaBox from './components/MetaBox';

Il codice è abbastanza esplicativo. Tuttavia, vogliamo soffermarci un attimo sulle due dichiarazioni di import per chi non ha conoscenze avanzate di React.

Con la prima istruzione import abbiamo racchiuso il nome della funzione tra parentesi graffe. Con la seconda istruzione import, il nome del componente non è racchiuso tra parentesi graffe.

Successivamente, registrate il vostro plugin:

registerPlugin( 'metadata-plugin', {
    render: MetaBox
} );

registerPlugin registra semplicemente un plugin. La funzione accetta due parametri:

  • Una stringa unica che identifica il plugin
  • Un oggetto di impostazioni del plugin. Notate che la proprietà render deve essere specificata e deve essere una funzione valida.

Costruire il Componente Utilizzando i Componenti Integrati di Gutenberg

È il momento di costruire il nostro componente React. Aprite il file MetaBox.js (o come lo avete chiamato) e aggiungete le seguenti dichiarazioni di importazione:

import { __ } from '@wordpress/i18n';
import { compose } from '@wordpress/compose';
import { withSelect, withDispatch } from '@wordpress/data';
import { PluginDocumentSettingPanel } from '@wordpress/edit-post';
import { PanelRow, TextControl, DateTimePicker } from '@wordpress/components';
  • La funzione compose esegue la composizione di funzioni, ovvero il risultato di una funzione viene passato a un’altra funzione. Prima di poter usare compose, potrebbe essere necessario installare il modulo corrispondente: 
    npm install @wordpress/compose --save

    Tra poco vedremo la funzione compose in azione.

  • withSelect withDispatch sono due componenti di ordine superiore che vi permettono di prelevare o inviare dati da o verso un negozio WordPress. withSelect viene utilizzato per iniettare props state-derived utilizzando selettori registrati, mentre withDispatch viene utilizzato per inviare oggetti di scena utilizzando action creators registrati.
  • PluginDocumentSettingPanel rende gli elementi della barra laterale del documento (si veda il codice sorgente su Github).

Successivamente, creerete il componente per visualizzare il pannello MetaBox nella barra laterale del documento. Nel file MetaBox.js, aggiungete il seguente codice:

const MetaBox = ( { postType, metaFields, setMetaFields } ) => {

    if ( 'post' !== postType ) return null;

    return(
   	 <PluginDocumentSettingPanel
   		 title={ __( 'Book details' ) }
   		 icon="book"
   		 initialOpen={ false }
   	 >
   		 <PanelRow>
   			 <TextControl
   				 value={ metaFields._meta_fields_book_title }
   				 label={ __( "Title" ) }
   				 onChange={ (value) => setMetaFields( { _meta_fields_book_title: value } ) }
   			 />
   		 </PanelRow>
   		 <PanelRow>
   			 <TextControl
   				 value={ metaFields._meta_fields_book_author }
   				 label={ __( "Author" ) }
   				 onChange={ (value) => setMetaFields( { _meta_fields_book_author: value } ) }
   			 />
   		 </PanelRow>
   		 <PanelRow>
   			 <TextControl
   				 value={ metaFields._meta_fields_book_publisher }
   				 label={ __( "Publisher" ) }
   				 onChange={ (value) => setMetaFields( { _meta_fields_book_publisher: value } ) }
   			 />
   		 </PanelRow>
   		 <PanelRow>
   			 <DateTimePicker
   				 currentDate={ metaFields._meta_fields_book_date }
   				 onChange={ ( newDate ) => setMetaFields( { _meta_fields_book_date: newDate } ) }
   				 __nextRemoveHelpButton
   				 __nextRemoveResetButton
   			 />
   		 </PanelRow>
   	 </PluginDocumentSettingPanel>
    );
}

const applyWithSelect = withSelect( ( select ) => {
    return {
   	 metaFields: select( 'core/editor' ).getEditedPostAttribute( 'meta' ),
   	 postType: select( 'core/editor' ).getCurrentPostType()
    };
} );

const applyWithDispatch = withDispatch( ( dispatch ) => {
    return {
   	 setMetaFields ( newValue ) {
   		 dispatch('core/editor').editPost( { meta: newValue } )
   	 }
    }
} );

export default compose([
    applyWithSelect,
    applyWithDispatch
])(MetaBox);

Vediamo come suddividere il codice.

  • L’elemento PluginDocumentSettingPanel crea un nuovo pannello nella barra laterale del documento. Impostiamo il titolo (“Dettagli del libro”) e l’icona e impostiamo initialOpen su false, il che significa che inizialmente il pannello è chiuso.
  • All’interno di PluginDocumentSettingPanel abbiamo tre campi di testo e un elemento DateTimePicker che permette all’utente di impostare la data di pubblicazione.
  • withSelect fornisce l’accesso alla funzione select che usiamo per recuperare metaFields e postType. withDispatch fornisce l’accesso alla funzione dispatch, che permette di aggiornare i valori dei metadati.
  • Infine, la funzione compose ci permette di comporre il nostro componente con i componenti di ordine superiore withSelect e withDispatch. In questo modo il componente ha accesso alle proprietà metaFields e postType e alla funzione setMetaFields.

Salvate il file MetaBox.js, create un nuovo post nel vostro sito di sviluppo WordPress e guardate la barra laterale dei documenti. Dovreste vedere il nuovo pannello Dettagli del libro.

Un pannello di meta box personalizzato nel menu destro dell’editor Gutenberg: si chiama Dettagli del libro
Un pannello meta box personalizzato in Gutenberg.

Ora eseguite i vostri test. Impostate i valori dei vostri custom meta field e salvate l’articolo. Poi ricaricate la pagina e controllate se i valori inseriti sono al loro posto.

Aggiungete il blocco che abbiamo creato nella sezione precedente e verificate che tutto funzioni correttamente.

Aggiungere una Barra Laterale Personalizzata per Gestire i Metadati degli Articoli

Se avete un gran numero di custom meta field da aggiungere ai vostri articoli o ai tipi di post personalizzati, potete anche creare una barra laterale di impostazioni personalizzate specifica per il vostro plugin.

Il processo è molto simile a quello dell’esempio precedente, quindi se avete compreso i passaggi discussi nella sezione precedente, non avrete alcuna difficoltà a creare una barra laterale personalizzata per Gutenberg.

Ancora una volta:

  1. Creare un nuovo plugin di blocco con create-block
  2. Registrare un meta field personalizzato per l’editor classico
  3. Registrare i custom meta field nel file principale del plugin tramite la funzione register_post_meta()
  4. Registrare un plugin nel file index.js
  5. Costruire il componente utilizzando i componenti integrati di Gutenberg

Creare un Nuovo Plugin di Blocco con lo Strumento create-block

Anche in questo caso, per creare un nuovo plugin a blocchi, seguite i passi descritti in precedenza. Potete creare un nuovo plugin o modificare gli script creati negli esempi precedenti.

Registrare una Meta Box Personalizzata per l’Editor Classico

Ora registrate un meta box personalizzato per garantire la retrocompatibilità dei siti WordPress che usano ancora l’editor classico. La procedura è la stessa descritta nella sezione precedente.

Registrare i Custom Meta Field nel File Principale del Plugin

Registrate i custom meta field nel file principale del plugin tramite la funzione register_post_meta().

Registrare un Plugin nel File index.js

Ora create un file CustomSidebar.js vuoto nella cartella components.

Una volta fatto, modificate il file index.js come segue:

/**
 * Registers a plugin for adding items to the Gutenberg Toolbar
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/
 */
import { registerPlugin } from '@wordpress/plugins';

import CustomSidebar from './components/CustomSidebar';
// import MetaBox from './components/MetaBox';

registerPlugin( 'metadata-block', {
	render: CustomSidebar
} );

Con il codice qui sopra importiamo prima il componente CustomSidebar e poi diciamo alla funzione registerPlugin di eseguire il rendering del nuovo componente.

Creare il Componente Utilizzando i Componenti Gutenberg Integrati

Quindi, aprite il file CustomSidebar.js e aggiungete le seguenti dipendenze:

import { __ } from '@wordpress/i18n';
import { compose } from '@wordpress/compose';
import { withSelect, withDispatch } from '@wordpress/data';
import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/edit-post';
import { PanelBody, PanelRow, TextControl, DateTimePicker } from '@wordpress/components';

Dovreste notare che stiamo importando due nuovi componenti:

Ora potete creare il vostro componente personalizzato:

const CustomSidebar = ( { postType, metaFields, setMetaFields } ) => {
   	 
	if ( 'post' !== postType ) return null;

	return (
    	<>
        	<PluginSidebarMoreMenuItem
            	target="metadata-sidebar"
            	icon="book"
        	>
            	Metadata Sidebar
        	</PluginSidebarMoreMenuItem>
        	<PluginSidebar
            	name="metadata-sidebar"
            	icon="book"
            	title="My Sidebar"
        	>
            	<PanelBody title="Book details" initialOpen={ true }>
                	<PanelRow>
                    	<TextControl
                        	value={ metaFields._meta_fields_book_title }
                        	label={ __( "Title" ) }
                        	onChange={ (value) => setMetaFields( { _meta_fields_book_title: value } ) }
                    	/>
                	</PanelRow>
                	<PanelRow>
                    	<TextControl
                        	value={ metaFields._meta_fields_book_author }
                        	label={ __("Author", "textdomain") }
                        	onChange={ (value) => setMetaFields( { _meta_fields_book_author: value } ) }
                    	/>
                	</PanelRow>
                	<PanelRow>
                    	<TextControl
                        	value={ metaFields._meta_fields_book_publisher }
                        	label={ __("Publisher", "textdomain") }
                        	onChange={ (value) => setMetaFields( { _meta_fields_book_publisher: value } ) }
                    	/>
                	</PanelRow>
                	<PanelRow>
                    	<DateTimePicker
                        	currentDate={ metaFields._meta_fields_book_date }
                        	onChange={ ( newDate ) => setMetaFields( { _meta_fields_book_date: newDate } ) }
                        	__nextRemoveHelpButton
                        	__nextRemoveResetButton
                    	/>
                	</PanelRow>
            	</PanelBody>
        	</PluginSidebar>
    	</>
	)
}

Il passo finale è la composizione del componente con i componenti di ordine superiore withSelect e withDispatch:

const applyWithSelect = withSelect( ( select ) => {
	return {
    	metaFields: select( 'core/editor' ).getEditedPostAttribute( 'meta' ),
    	postType: select( 'core/editor' ).getCurrentPostType()
	};
} );

const applyWithDispatch = withDispatch( ( dispatch ) => {
	return {
    	setMetaFields ( newValue ) {
        	dispatch('core/editor').editPost( { meta: newValue } )
    	}
	}
} );

export default compose([
	applyWithSelect,
	applyWithDispatch
])(CustomSidebar);

Salvate le modifiche, quindi controllate l’interfaccia dell’editor. Se aprite il menu a tendina Opzioni, vedrete una nuova voce Metadata Sidebar nella sezione Plugin. Facendo clic su questa nuova voce, attiverete la vostra nuova barra laterale personalizzata.

Il componente PluginSidebarMoreMenuItem aggiunge una voce di menu in Opzioni - Plugin
Il componente PluginSidebarMoreMenuItem aggiunge una voce di menu sotto Opzioni – Plugin.

Lo stesso accade quando fate clic sull’icona del libro nell’angolo in alto a destra.

La barra laterale delle impostazioni dei plugin
La barra laterale delle impostazioni dei plugin.

Ora tornate al vostro sito di sviluppo e create un nuovo articolo sul blog. Compilate i meta field e poi aggiungete il blocco all’editor. Dovrebbe includere gli stessi valori meta inseriti nella barra laterale personalizzata.

Salvate l’articolo e visualizzate l’anteprima della pagina sul frontend. Dovreste vedere la vostra scheda con il titolo del libro, l’autore, l’editore e la data di pubblicazione.

Potete trovare il codice completo di questo articolo in questo gist pubblico.

Altre Letture

In questo articolo abbiamo trattato diversi argomenti, dai selettori ai componenti di ordine superiore e molto altro ancora. Abbiamo linkato le principali risorse che abbiamo usato come riferimento in tutto l’articolo.

Ma se volete approfondire questi argomenti, potete anche consultare le seguenti risorse aggiuntive:

Documentazione di Gutenberg e Risorse Ufficiali di WordPress

Altre Risorse Ufficiali

Altre Risorse dalla Comunità

Letture Utili dal Sito di Kinsta

Riepilogo

In questo terzo articolo della nostra serie sullo sviluppo dei blocchi di Gutenberg, abbiamo trattato nuovi argomenti avanzati che dovrebbero rendere più completo il quadro delineato negli articoli precedenti sullo sviluppo dei blocchi statici e dinamici.

Ora dovreste essere in grado di sfruttare le potenzialità dei campi personalizzati in Gutenberg e creare siti web WordPress più avanzati e funzionali.

Ma c’è di più. Grazie alle competenze acquisite con i nostri articoli sullo sviluppo dei blocchi, dovreste anche avere una buona idea di come sviluppare componenti React al di fuori di WordPress. Dopo tutto, Gutenberg è una SPA basata su React.

E ora tocca a voi! Avete già creato blocchi Gutenberg che usano custom meta field? Condividete con noi le vostre creazioni nei commenti qui sotto.

Carlo Daniele Kinsta

Carlo è cultore appassionato di webdesign e front-end development. Gioca con WordPress da oltre 20 anni, anche in collaborazione con università ed enti educativi italiani ed europei. Su WordPress ha scritto centinaia di articoli e guide, pubblicati sia in siti web italiani e internazionali, che su riviste a stampa. Lo trovate su LinkedIn.