Aggiungi una barra laterale Custom Inspector in WordPress Gutenberg con Post Meta

In questo tutorial esamineremo come aggiungere una barra laterale personalizzata all’Inspector (barra laterale destra) in WordPress Gutenberg. All’interno implementeremo un campo collegato a un post meta. Tutto è implementato con Javascript, all’interno dell’editor Gutenberg, ed è un’alternativa all’aggiunta di metabox in modo tradizionale.

Dritta!

Questo è un tutorial per creare la tua barra laterale personalizzata. Ma se sei interessato solo ad aggiungere meta/impostazioni alla barra laterale standard di Inspector (scheda "Documento"), ho un tutorial esattamente per questo:

Cosa creeremo

WordPress Gutenberg consente agli sviluppatori di creare barre laterali personalizzate utilizzando la creazione di un cosiddetto plug-in Javascript. (Da non confondere con i tradizionali plugin di WordPress). Utilizzando un plug-in Javascript possiamo creare una nuova barra laterale e anche collegarci al menu "Strumenti e opzioni".

Aggiungeremo una nuova voce di menu negli "Strumenti" che aprirà la nostra barra laterale personalizzata. Il contenuto della barra laterale dipende interamente da te, ma analizzerò alcuni esempi, incluso come collegare un meta campo post al suo interno.

Configurazione del tuo Javascript

Per questo tutorial scriverò ES6/ESNext Javascript con JSX, il che significa che dobbiamo impostare un compilatore. Se vuoi seguire e non scrivere Javascript ES5 dovrai configurare un ambiente di sviluppo che compili il tuo Javascript mentre procedi. Se non hai familiarità con questo, segui il mio post che spiega come configurarlo e poi torna qui.

Ho impostato il mio webpack.config.jsper compilare il mio file Javascript di origine nella mia cartella del tema /assets/js/sidebar-plugin.js. Questo file compilato è ciò di cui abbiamo bisogno per accodare all’editor Gutenberg. Mentre scrivo questo codice ho avviato il compilatore di runtime che ricompila Javascript ogni volta che salvo le modifiche nel codice sorgente (npm run start). Tutto questo è spiegato in modo approfondito nel tutorial precedentemente menzionato.

Lo sto scrivendo in un tema, ma funziona allo stesso modo in un plugin. Ricorda solo di regolare i percorsi quando aggiungi lo script all’editor.

Aggiunta dello script all’editor

Per aggiungere il nostro script all’editor Gutenberg abbiamo bisogno di scrivere del PHP. Se ti trovi in ​​un tema, functions.phpè un buon punto di partenza o da qualche parte nei tuoi file di plugin. Si noti che è necessario aggiungere lo script compilato finale, non il codice sorgente. Nel mio esempio il Javascript compilato si trova nella cartella del mio tema /assets/js/sidebar-plugin.js.

Creiamo una funzione agganciata a enqueue_block_editor_assets. Dentro facciamo il solito [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). Come dipendenze allo script ne aggiungiamo due; wp-plugins, e wp-edit-post. Questi due pacchetti devono essere caricati prima del nostro script poiché utilizziamo le funzioni da essi.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});

Poiché accodiamo lo script nell’hook, il enqueue_block_editor_assetsnostro script verrà caricato solo quando l’editor Gutenberg è attivo. Grande! Ora è tutto pronto per scrivere il nostro plugin Javascript.

Registra un plugin Javascript

Il primo passo è la registrazione di un plugin. Lo facciamo con la [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)funzione in wp.plugins dall’interno del wp.pluginspacchetto.

Come parametro del registerPlugin forniamo un nome (assicurati che sia univoco) e un oggetto con le impostazioni. Come minimo è necessario fornire un componente per la proprietà render. Puoi anche aggiungere un’icona facoltativamente dai dashicon di WordPress. Tieni presente che se non specifichi un’icona ricadrà sull’icona del plug-in. A scopo dimostrativo sto usando l’ 'carrot'icona.

Per quanto riguarda il componente iniziamo definendo un componente base che restituisca un semplice div con del testo casuale al suo interno. E prima di tutto il codice destrutturiamo le funzioni dai pacchetti che vogliamo utilizzare.

Se non succede nulla (nemmeno errori) quando si aggiorna Gutenberg siamo tutti a posto. Non vediamo il nostro componente perché non abbiamo detto a WordPress dove renderizzarlo. Il passaggio successivo è l’aggancio al menu personalizzato della barra laterale e ai componenti del menu degli strumenti per il rendering delle nostre cose.

Registra una barra laterale personalizzata

Ma prima una spiegazione su come Gutenberg gestisce le barre laterali personalizzate e perché dobbiamo fare quello che faremo. Quando registriamo correttamente una barra laterale personalizzata, all’inizio accadrà automaticamente. Gutenberg aggiungerà una scorciatoia alla nostra barra laterale nella barra degli strumenti in alto, accanto al menu Strumenti. Ciò accade perché la nostra barra laterale viene automaticamente "bloccata".

Il problema della semplice aggiunta di una barra laterale personalizzata è che qualsiasi utente può "sbloccare" questa scorciatoia. Quando lo fanno, non c’è alcun punto di accesso per aprire di nuovo la barra laterale! Questo è il motivo per cui dobbiamo aggiungere anche una voce di menu al menu Strumenti.

La registrazione di una barra laterale personalizzata viene eseguita con il componente PluginSidebardel wp.editPostpacchetto. L’aggiunta di una voce di menu al menu Strumenti viene eseguita con il componente con il nome appropriato PluginSidebarMoreMenuItem(anch’esso nel wp.editPostpacchetto).

Per il PluginSidebarcomponente dobbiamo fornire alcuni oggetti di scena. Dovresti fornire come minimo namee title. L’elica titlesi spiega da sé, questo è il nome che apparirà nella parte superiore della barra laterale. Nell’elica namefornire una lumaca unica. Quando aggiungi la voce di menu devi fare riferimento a questo slug.

L’aggiunta di un PluginSidebarMoreMenuItemcomponente (menu strumenti) richiede almeno un prop; target. Qui fornisci lo stesso nome che hai dato nel supporto della barra laterale name. Come contenuto del componente scrivi il testo che verrà visualizzato come voce di menu. Di solito questo sarebbe lo stesso della barra laterale title.

Poiché React richiede un singolo nodo di wrapping attorno al reso del componente, avvolgiamo tutto all’interno di un Fragmentcomponente (dal wp.elementpacchetto). Sto anche avvolgendo le mie stringhe __()dal wp.i18npacchetto per consentire la traduzione.

Con il codice sopra otterremo le seguenti due (molto probabilmente tre) cose che accadono. Otterrai una scorciatoia per l’icona di una carota nella barra degli strumenti (se non l’hai ancora sbloccata). Cliccando su questo si aprirà la barra laterale. Avrai anche una nuova voce di menu nella barra laterale nel menu Strumenti, sotto il titolo "Plugin".

Aggiunta di contenuti alla barra laterale

Il contenuto effettivo della barra laterale dipende interamente da te. Devi solo aggiungere HTML o componenti all’interno del PluginSidebarcomponente con quello che vuoi (al posto del testo "Hello there.").

Potresti notare che al contenuto della barra laterale manca il riempimento. Questo è intenzionale perché l’idea è che creerai pannelli all’interno di questa barra laterale. I pannelli sono le sezioni pieghevoli nella normale barra laterale di Gutenberg. Questi sono componenti che puoi facilmente aggiungere all’interno della tua barra laterale personalizzata. Puoi aggiungere tutti i pannelli che vuoi e sono ottimi per raggruppare cose diverse.

Aggiunta di pannelli nella nostra barra laterale

Diamo un’occhiata rapidamente a come possiamo aggiungere pannelli alla nostra barra laterale. Se hai creato i tuoi tipi di blocchi personalizzati, potresti avere familiarità con questi componenti. Usiamo PanelBodye facoltativamente PanelRowdal wp.componentspacchetto.

Per un PanelBodycomponente fornisci come minimo il prop title. Puoi opzionalmente fornire true o false initialOpenall’elica per decidere se il pannello deve essere espanso come predefinito o meno. Poiché il contenuto all’interno del componente è tutto all’interno del pannello.

All’interno di un PanelBodyè possibile utilizzare facoltativamente PanelRowdei componenti. Non sono realmente necessari ma possono aiutarti a ottenere uno stile buono per il contenuto del tuo pannello.

Per esempio, aggiungiamo due pannelli alla nostra barra laterale personalizzata.

Con questo codice la nostra barra laterale personalizzata inizia a sembrare davvero come se appartenesse a Gutenberg!

Aggiunta di meta campi post alla barra laterale personalizzata

Ora stiamo davvero entrando nel vivo delle cose utili per una barra laterale personalizzata; aggiungendo impostazioni e memorizzando i loro valori. Ma prima dobbiamo capire come.

È davvero facile aggiungere campi di impostazione (input, caselle di controllo, campi di commutazione, ecc.) Nella barra laterale utilizzando i componenti pronti all’uso nei pacchetti di WordPress. Tuttavia, dobbiamo considerare come memorizzare i valori. L’opzione più ovvia è salvarli come post meta. Ma il collegamento di un’impostazione a un meta campo post richiede del codice aggiuntivo. Più specificamente, abbiamo bisogno di utilizzare i cosiddetti componenti di ordine superiore per recuperare e aggiornare i post meta all’interno di Javascript. Dobbiamo anche registrare ogni meta post utilizzando PHP e renderli disponibili per l’API REST.

Per chiudere questo tutorial dimostrerò come aggiungere un meta post con una chiave awp_my_custom_metache dovrebbe essere archiviata come true o false. Nella barra laterale verrà visualizzato come un campo di commutazione (un componente vero/falso).

Registra il meta meta per l’API REST

Il primo passo per aggiungere post meta nel nostro file Javascript è registrarli e definirli come accessibili nell’API REST. Per fare ciò torniamo di nuovo a PHP.

All’interno di una funzione agganciata initall’azione utilizziamo la [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()funzione. Come parametri dobbiamo definire il tipo di oggetto come ‘ post‘ perché lo stiamo usando come post meta (non esclude ad esempio il tipo di post di pagina). Forniamo la chiave meta e quindi un array di argomenti. La cosa fondamentale da aggiungere nell’array degli argomenti è impostare ‘ show_in_rest‘ su true. Post meta è comunemente usato come ‘ single‘ (pensa a come usi get_post_meta()). Definiamo anche il type. Per quanto riguarda il nostro caso, lo abbiamo impostato su ‘ boolean‘.

Con questo codice il campo ‘ awp_my_custom_meta‘ post meta è accessibile da Gutenberg. Devi ripetere register_meta()per ogni meta post che desideri aggiungere nella barra laterale.

Ora torniamo al nostro Javascript.

Aggiunta di un’impostazione alla nostra barra laterale

Iniziamo con la parte facile: aggiungere l’input alla nostra barra laterale. Successivamente aggiungeremo più codice per collegare effettivamente il campo delle impostazioni al post meta. A causa del modo in cui dobbiamo farlo, definiamo un nuovo componente separato per la nostra impostazione. Quindi all’interno del pannello a cui vuoi aggiungere le tue impostazioni chiama semplicemente questo nuovo componente.

Chiamiamo il componente CustomSidebarMetaComponent(potresti chiamarlo qualcosa di rilevante per il tuo progetto). All’interno di questo componente vogliamo rendere un campo di commutazione. Per fare ciò utilizziamo il ToggleControlcomponente del wp.componentspacchetto. Come supporto per ToggleControl forniamo un’etichetta di montaggio nell’oggetto title. Un ToggleControl necessita anche degli oggetti di scena onChangeper l’aggiornamento del valore e checkedper il valore corrente. Ometteremo questi due per ora fino al passaggio successivo.

Con il codice sopra dovresti ottenere un campo di attivazione/disattivazione nella barra laterale. È deselezionato e non accade nulla quando si fa clic su di esso. Questo è il passaggio successivo: collegarlo al nostro post meta.

Accesso al meta post con withSelect e withDispatch

Per accedere e aggiornare un meta valore post, dobbiamo utilizzare componenti di ordine superiore (HOC) per accedere alla versione dei negozi di WordPress (simile a Redux). WordPress ci fornisce alcuni utili HOC con funzioni che possiamo utilizzare nel wp.datapacchetto.

Il componente di ordine superiore [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)è fornire al nostro componente oggetti di scena che, nel nostro caso, vengono recuperati da post meta. Lo usiamo per ottenere il valore del nostro post meta. All’interno withSelectpossiamo usare select('core/editor').getEditedPostAttribute('meta')per recuperare il meta del post corrente.

D’altra parte, [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)è un componente di ordine superiore che può eseguire azioni. Nel nostro caso vogliamo aggiornare il meta del post quando l’impostazione del campo corrispondente viene modificata nella nostra barra laterale. All’interno di questo componente utilizziamo dispatch('core/editor').editPost()per informare WordPress per inviare un’azione. All’interno dell’oggetto che forniamo diciamo a WordPress che è meta che vogliamo aggiornare.

Infine dobbiamo combinare withSelecte withDispatchcon il nostro componente che gestisce il post meta campo (CustomSidebarMetaComponent). Per fare questo utilizziamo WordPress’ composedal wp.composepacchetto. L’idea è quella withSelecte withDispatchfornisce al nostro CustomSidebarMetaComponentcomponente oggetti di scena. withSelectfornisce il valore del meta post come prop e withDispatchfornisce una funzione che possiamo chiamare per aggiornare il valore come prop. Impostiamo questi oggetti di scena sul nostro ToggleField checkede onChange, di conseguenza.

Questo è molto da spiegare. Diamo un’occhiata al codice effettivo:

Cominciamo dall’inizio. Che è in fondo. Alla riga #36cambiamo il componente che renderizziamo nella nostra barra laterale con il componente che abbiamo creato con compose(alla riga #15). Il CustomSidebarMetacomponente unirà i componenti withSelecte withDispatche restituirà il CustomSidebarMetaComponent.

Avranno CustomSidebarMetaComponentaccesso customPostMetaValueall’elica di withSelect, e setCustomPostMetaall’elica di withDispatchQuesti due che usiamo per gli oggetti di scena checkede in .onChange``ToggleField

Nota che in linea #5aggiungiamo propscome parametri ai componenti in modo da rendere gli oggetti di scena accessibili nel componente.

Conclusione e parole finali

Spero che questo tutorial ti sia stato di qualche utilità. Questo è ciò che sono riuscito a comprendere sull’argomento durante molti tentativi ed errori. Non c’è ancora quasi nessuna documentazione su questo argomento. Sto ancora lottando con questo, specialmente quando si tratta di gestire in modo efficiente più meta meta. Se riesco ad imparare qualche buon trucco aggiornerò di sicuro questo tutorial!

Si spera che seguendo questo tutorial dovresti avere un codice che aggiunge con successo una nuova barra laterale personalizzata all’editor Gutenberg di WordPress e, si spera, con alcuni contenuti e impostazioni significativi. Ecco il codice finale per la barra laterale personalizzata con il meta campo post.