In questa parte scriveremo Javascript per registrare e configurare il nostro blocco personalizzato. Alla fine registreremo lo script con PHP e faremo il codice PHP necessario affinché WordPress lo riconosca come un nuovo blocco.
Innanzitutto una breve nota su come accedere alle funzioni e ai componenti di WordPress Gutenberg.
wpIl pacchetto globale e la destrutturazione
Quando ci troviamo in un file Javascript accodato nell’editor Gutenberg, abbiamo accesso a un oggetto/pacchetto globale: wp. Questo è un oggetto Javascript molto, molto grande e contiene un sacco di componenti e funzioni utili che useremo per creare blocchi. Quando scrivi Javascript per blocchi personalizzati ti riferirai a wpparecchio.
Pertanto è comune, sia nel moderno Javascript che in React, destrutturare ciò che vogliamo utilizzare da esso. Fondamentalmente significa solo che definiamo variabili locali da parti di una struttura più grande. Ad esempio, la prima funzione che useremo è registerBlockType()che esiste all’interno di wp.blocks. Potremmo invocare la funzione in questo modo:
wp.blocks.registerBlockType();Ma è più facile destrutturarlo in questo modo:
const { registerBlockType } = wp.blocks;
registerBlockType();Ora puoi fare riferimento direttamente alla funzione senza anteporre ad essa la sua struttura. Diventa molto più utile quando ci riferiamo a funzioni o componenti che ripeteremo spesso.
Effettueremo la ristrutturazione in questa serie e man mano che avanziamo nel tutorial vedremo quanto diventa più leggibile e più breve il nostro codice.
Registrazione di un nuovo blocco
Nel pacchetto è registerBlockType()disponibile la funzione per la registrazione di un nuovo blocco personalizzato. wp.blocksAccetta due parametri; prima una stringa con lo spazio dei nomi e il nome del blocco e, in secondo luogo, un oggetto con la configurazione completa del blocco.
Gutenberg si aspetta che tutti i blocchi abbiano uno spazio dei nomi e un nome, definiti con una barra nel mezzo. Lo spazio dei nomi serve a garantire che il nome del blocco non sia in conflitto con altri blocchi che potrebbero utilizzare lo stesso nome. Tutti i blocchi in WordPress utilizzano lo spazio dei nomi core. Ad esempio, il blocco di paragrafo standard in WordPress ha il nome core/paragraph. Se scegli un altro spazio dei nomi puoi anche creare un blocco denominato paragrafo senza causare problemi.
Decidi uno spazio dei nomi della versione slug che sia unico per te. Userò lo spazio dei nomi awp(versione breve di A White Pixel) in questa serie.
Apri il file sorgente che abbiamo creato nell’ultimo passaggio; src/block-awhitepixel-myfirstblock.js, in un editore. Per prima cosa chiameremo registerBlockTypeda destructed wp.blocks, con il nome awp/firstblock. Modifica il tuo nome e spazio dei nomi mentre procedi.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});Nel secondo parametro, l’oggetto di configurazione del blocco, è necessario definire alcune proprietà affinché venga registrato correttamente. Ricorda che la configurazione del blocco è un oggetto, il che significa che devi scrivere tutto come coppie chiave + valore, separate da virgola. Ci sono alcune possibili proprietà di configurazione, quindi esaminiamole e vedremo il codice finale alla fine.
Richiesto: titolo
La prima proprietà richiesta è title. Questo è il nome che apparirà quando selezioni tra i blocchi. Imposta questa proprietà come qualsiasi nome desideri in una stringa.
Aggiungeremo quanto segue come titolo:
title: 'My first block',PS: Rivisiteremo il modo in cui scriviamo tutte le stringhe nel nostro blocco per assicurarci che possano essere tradotte nella parte 8. Ma per ora lo manterremo semplice e scriveremo semplicemente stringhe.
Obbligatorio: categoria
La proprietà categorydefinisce dove in quale categoria di blocco apparirà il tuo blocco quando selezioni i blocchi da inserire nell’editor. I valori possibili sono common, formatting, layout, widgets, embed.
Mettiamola in common, la prima categoria di blocco.
category: 'common',Opzionale: icona
Se hai usato Gutenberg, probabilmente avrai notato che tutti i blocchi hanno icone. Puoi aggiungere un’icona al tuo blocco con una stringa che fa riferimento a qualsiasi Dashicon di WordPress oppure puoi fornire un svgelemento personalizzato.
Scelgo solo uno dei dashicon di WordPress, lo smiley, ma puoi scegliere quello che vuoi. Nota che salti l’inclusione di "dashicon-" nel nome della classe dell’icona.
icon: 'smiley',Facoltativo: descrizione
Puoi fornire una descrizione che verrà visualizzata nella barra laterale Impostazioni (sul lato destro) quando il blocco è attivo.
Aggiungo solo un breve testo come esempio:
description: 'Learning in progress',Facoltativo: parole chiave
Gutenberg supporta una funzionalità di ricerca quando si scelgono i tipi di blocco. È possibile fornire una serie di possibili corrispondenze nella proprietà keywords. Senza keywordsdi te troveresti il tuo blocco solo cercando il suo nome.
Aggiungerò examplee test, in modo da poter trovare facilmente il nostro blocco personalizzato quando iniziamo a digitare una di queste parole chiave.
keywords: ['example', 'test'],Facoltativo: attributi
La proprietà attributesè una proprietà molto importante che rivisiteremo abbastanza spesso in questa serie di tutorial. Qui è dove memorizzi i tuoi dati strutturati e le informazioni di input dell’utente per il tuo blocco. Puoi immaginarlo come variabile. Non lo aggiungeremo per ora, ma torneremo sicuramente su questo molto presto.
(Tipo di) richiesto: modifica e facoltativo: salva
All’interno edite savele proprietà è in realtà dove aggiungerai tutto il codice sia per l’output dell’editor che per il rendering del frontend. Entrambe queste proprietà si aspettano una funzione che dovrebbe restituire un output.
La proprietà editdescrive la struttura del blocco all’interno dell’editor. La saveproprietà gestisce fondamentalmente due cose; l’output del tuo blocco nel frontend, ma anche la struttura di come il tuo blocco viene salvato nel database. Lavorerai principalmente in editquanto è qui che aggiungi input per inserire o scegliere cose e aggiornare i dati del blocco. La savefunzione non dovrebbe aggiornare o modificare i dati in alcun modo, dovrebbe solo emettere.
Gutenberg deve essere in grado di ricostruire il tuo blocco con tutte le sue impostazioni nell’editor da ciò che viene restituito nella savefunzione (e negli attributi). Se Gutenberg apre un post in cui l’output del blocco salvato in precedenza differisce (anche solo leggermente) da ciò che è definito in save, il tuo blocco non sarà più valido.
Posso garantirti che lo incontrerai molto durante lo sviluppo di blocchi personalizzati. Quando ciò accade è necessario rimuovere il blocco (dai punti nella barra degli strumenti) e aggiungerlo nuovamente. Consiglio anche di eseguire un aggiornamento del browser (F5 o CTRL+R).
WordPress ha una pagina di documentazione dedicata per le funzioni di modifica e salvataggio del blocco se vuoi saperne di più.
Per quanto riguarda il nostro primo blocco, produciamo qualcosa di base. Restituiremo lo stesso per entrambi edite save; un “:)" avvolto in <div>. Dopotutto, l’icona del blocco è una faccina.
Altre proprietà
Ci sono più proprietà facoltative per registerBlockType; parent, supports, transforms, example, e styles. Salteremo questi per ora poiché la maggior parte sono per la costruzione di blocchi più avanzati o personalizzati. Se sei interessato a leggere di più su questi, dai un’occhiata alla documentazione di WordPress.
Codice blocco registro finale
Il nostro codice ora assomiglia a questo.
Con questo abbiamo abbastanza per registrare con successo il nostro blocco come blocco personalizzato. Vediamolo in pratica all’interno dell’editor di Gutenberg.
Ti sei ricordato di compilare il tuo Javascript? Nel passaggio precedente abbiamo appreso che non possiamo caricare questo file Javascript in Gutenberg; abbiamo bisogno della versione compilata. Di solito ti svilupperesti con npm run startl’esecuzione in background, oppure puoi eseguire solo npm run builduna volta ora. Questo dovrebbe compilare il nostro Javascript sorgente e posizionarlo dove l’hai definito per essere inserito e nominato nel tuo webpack.config.js.
La parte PHP della registrazione di un blocco
Per ogni blocco è necessario registrare il file Javascript e questo è proprio come registreresti qualsiasi altro script in WordPress, utilizzando [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Si noti che registriamo lo script, non lo accodiamo. Questo perché abbiamo anche bisogno di chiamare una funzione PHP per registrare ogni blocco personalizzato e quella funzione è responsabile dell’accodamento dello script quando è necessario.
Preferisco mantenere il codice relativo a Gutenberg in un file separato nei miei temi. Ma puoi, e lo faremo in questo tutorial, scrivere semplicemente tutto il codice PHP direttamente all’interno del tema functions.phpper motivi di semplicità.
Consiglio di usare l’ inithook per la tua funzione e non enqueue_block_assets. Possiamo mettere insieme sia la registrazione dello script che la registrazione del blocco.
La funzione PHP che useremo per registrare un nuovo blocco è [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). Allo stesso modo di Javascript, registerBlockType()accetta due parametri; lo spazio dei nomi e il nome del blocco e un array con argomenti. Assicurati di fornire lo stesso spazio dei nomi e lo stesso nome in PHP come in Javascript.
Nel secondo argomento ci sono alcuni possibili argomenti (alcuni dei quali torneremo più avanti in questa serie). Ma il più importante è editor_scriptdove si fornisce l’handle (primo parametro di wp_register_script()) dello script registrato.
E questo è tutto!
Il nostro blocco nell’editor di Gutenberg
Ora, quando aggiorni il tuo editor in alcuni post, dovresti trovare il nostro blocco, aprendo la categoria Comune o cercando una qualsiasi delle parole chiave o del nome che hai fornito.
Il nostro blocco rende un semplice ":)" sia nell’editor che nel frontend. A partire da ora non puoi modificare nulla nel blocco, ma questo è ciò che impareremo nei prossimi passaggi!