Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. WordPress Gutenberg

Block API di WordPress Gutenberg: Creazione dei blocchi personalizzati

by
Difficulty:IntermediateLength:LongLanguages:
This post is part of a series called WordPress Gutenberg Block API.
WordPress Gutenberg Block API: Block Look and Feel
WordPress Gutenberg Block API: Extending Blocks

Italian (Italiano) translation by Cinzia Sgariglia (you can also view the original English article)

Il nuovo editor di WordPress (nome in codice Gutenberg) sarà rilasciato nella versione 5.0. Ora è il momento perfetto per prendere confidenza con esso prima che finisca nel core di WordPress. In questa serie, vi mostrerò come lavorare con le Block API e creare i vostri blocchi di contenuto che potete utilizzare per costruire il vostro post e le pagine.

Nell'articolo precedente, abbiamo visto come utilizzare il toolkit create-guten-block per creare un plugin contenente un blocco campione pronto su cui lavorare. Possiamo facilmente estenderlo come previsto, ma è una buona idea sapere come creare un blocco da zero per comprendere appieno tutti gli aspetti dello sviluppo del blocco di Gutenberg.

In questo articolo creeremo un secondo blocco nel nostro plugin mio-blocco-personalizzato per visualizzare un'immagine casuale dal servizio web PlaceIMG. Sarete anche in grado di personalizzare il blocco selezionando la categoria dell'immagine da un controllo di selezione a discesa.

Ma prima impareremo come gli script e gli stili dei blocchi vengono accodati prima di passare all'importantissima funzione registerBlockType(), che è fondamentale per la creazione di blocchi in Gutenberg.

Accodare gli script e gli stili di blocco

Per aggiungere il codice JavaScript e CSS richiesti da nostri blocchi, possiamo usare due nuovi WordPress hook forniti da Gutenberg:

  • enqueue_block_editor_assets
  • enqueue_block_assets

Questi sono disponibili solo se il plugin di Gutenberg è attivo, e funzionano in modo simile agli hook standard di WordPress per accodare gli script. Tuttavia, essi sono destinati specificamente per lavorare con i blocchi di Gutenberg.

L'hook enqueue_block_editor_assets aggiunge gli stili e gli script solo all'editor di admin. Questo lo rende ideale per accodare JavaScript ai blocchi del registro e CSS agli elementi di stile dell'interfaccia utente per le impostazioni di blocco.

Per l'output del blocco, però, vorrete che i blocchi restituiscano lo stesso nell'editor come fanno sul front-end la maggior parte delle volte. Utilizzare enqueue_block_assets lo rende facile poiché gli  stili vengono aggiunti automaticamente sia all'editor che al front end. È anche possibile utilizzare questo hook per caricare JavaScript se necessario.

Ma vi starete chiedendo come accodare gli script e gli stili solo al front-end. Non c'è un hook di WordPress che permetta di farlo direttamente, ma è possibile aggirarlo aggiungendo un'istruzione condizionale all'interno della funzione di callback dell'hook enqueue_block_assets.

In realtà per accodare gli script e gli stili utilizzando questi due hook nuovi, potete utilizzare le funzioni standard wp_enqueue_style() e wp_enqueue_scripts() come fareste normalmente.

Tuttavia, è necessario assicurarvi che state utilizzando le dipendenze degli script corrette. Per gli script di accodamento nell'editor, potete utilizzare le seguenti dipendenze:

  • script: array( 'wp-blocks', 'wp-i18n', 'wp-element', 'wp-components' )
  • stili: array( 'wp-edit-blocks' )

E quando accodate stili sia per l'editor che per il front-end, è possibile utilizzare questa dipendenza:

  • array( 'wp-blocks' )

Un aspetto degno di nota qui è che i file effettivi accodati dal nostro plugin il mio-blocco-personalizzato sono le versioni compilate di JavaScript e CSS e non i file contenenti il codice sorgente JSX e Sass.

È solo qualcosa da tenere a mente quando manualmente accodate i file. Se tentate di accodare il codice sorgente puro che include React, ES6+, o Sass allora incontrerete numerosi errori.

Questo perché è utile usare un toolkit come create-guten-block poiché elabora e accoda gli script automaticamente!

Registrare i blocchi di Gutenberg

Per creare un nuovo blocco, abbiamo bisogno di registrarlo con Gutenberg chiamando registerBlockType() e incrociando il nome del blocco più un oggetto di configurazione. Questo oggetto ha alcune proprietà che richiedono una spiegazione adeguata.

In primo luogo, però, diamo un'occhiata al nome del blocco. Questo è il primo parametro ed è una stringa composta da due parti, un namespace e il nome del blocco stesso, separati da un carattere barra obliqua.

Per esempio:

Se state registrando diversi blocchi in un plugin, allora potete utilizzare lo stesso namespace per organizzare tutti i vostri blocchi. Il namespace deve essere univoco per il vostro plugin, però, cosa che aiuta a prevenire i conflitti di denominazione. Questo può accadere se un blocco con lo stesso nome è già stato registrato tramite un altro plugin.

Il secondo parametro registerBlockType() è un oggetto impostazioni e richiede un numero di proprietà che deve essere specificato:

  • title (stringa): visualizzato nell'editor come etichetta di blocco ricercabile
  • description (stringa facoltativa): descrive lo scopo di un blocco
  • icon (elemento facoltativo di Dashicon o JSX): icona associata a un blocco
  • category (stringa): dove il blocco viene visualizzato nella finestra di dialogo Aggiungi blocchi
  • keywords (array facoltativo): fino a tre parole chiave utilizzate nelle ricerche di blocco
  • attributes (oggetto facoltativo): gestisce i dati di blocco dinamico
  • edit (funzione): una funzione che restituisce il markup da visualizzare nell'editor
  • save (funzione): una funzione che restituisce il markup da visualizzare sul front-end
  • useOnce (boolean facoltativo): limita il blocco dall'essere aggiunto più di una volta
  • supports (oggetto facoltativo): definisce la funzionalità del blocco-supportato

Supponendo che stiamo usando JSX per lo sviluppo del blocco, ecco come un esempio di chiamata di registerBlockType() potrebbe apparire in un blocco molto semplice:

Notate come non abbiamo incluso una voce per le proprietà description, attributes, useOnce e supports? Tutti i campi che sono opzionali (e non rilevanti per il vostro blocco) possono essere omessi in modo sicuro. Ad esempio, poiché questo blocco non coinvolge tutti i dati dinamici, non abbiamo bisogno di preoccuparci di specificare eventuali attributi.

Ora copriamo le proprietà dell'oggetto di configurazione registerBlockType()  più in dettaglio una per una.

Title e description

Quando si inserisce o si ricerca un blocco nell'editor, il titolo verrà visualizzato nell'elenco dei blocchi disponibili.

Viene visualizzato anche nella finestra ispeziona del blocco, insieme con la descrizione del blocco se definito. Se la finestra ispeziona del blocco non è attualmente visibile è possibile utilizzare l'icona a ingranaggio in alto a destra dell'editor di Gutenberg per attivare la visibilità.

Block title and description

Sia i campi titolo e descrizione dovrebbero idealmente essere avvolto nelle funzioni i18n per consentire la traduzione in altre lingue.

Category

Ci sono cinque categorie di blocco attualmente disponibili:

  • common
  • formatting
  • layout
  • widgets
  • embed

Queste determinano la sezione della categoria dove il vostro blocco è elencato all'interno della finestra Aggiungi blocco.

Block categories

La scheda Blocchi contiene le categorie Blocchi comuni, Formattazione, Elementi di layout e Widget, mentre la categoria Embeds ha una propria scheda.

Le categorie attualmente sono fisse in Gutenberg, ma questo potrebbe essere soggetto a modifiche in futuro. Questo sarebbe utile, per esempio, se stavate sviluppando più blocchi in un unico plugin e li volevate tutti elencati sotto una categoria comune, così gli utenti potrebbero individuarli più facilmente.

Icon

Per impostazione predefinita, al vostro blocco viene assegnato lo scudo Dashicon, ma è possibile ignorare questo specificando un Dashicon personalizzato nel campo icon.

Dashicons

Ogni Dashicon è preceduto da dashicons- seguito da una stringa univoca. Ad esempio, l'icona dell'ingranaggio ha il nome dashicons-admin-generic. Per utilizzarlo come un'icona di blocco, è sufficiente rimuovere il prefisso dashicons- per essere riconosciuto, ad esempio, icon: 'admin-generic'.

Tuttavia, non siete limitati solo a utilizzare Dashicons come proprietà icon. La funzione accetta anche un elemento JSX, che significa che potete utilizzare qualsiasi immagine o elemento SVG come icona del blocco.

Siate solo certi di mantenere la dimensione dell'icona coerente con le altre icone del blocco, che è 20 x 20 pixel per impostazione predefinita.

Keywords

Scegliete fino a tre parole chiave traducibili che vi aiutino a far risaltare il vostro blocco quando gli utenti cercano un blocco. È meglio scegliere parole chiave strettamente correlate alla funzionalità del blocco per ottenere i migliori risultati.

Potreste dichiarare anche il nome della vostra azienda e/o plugin come parole chiave in modo che se disponete di più blocchi, gli utenti possono iniziare a digitare il nome della vostra azienda e tutti i tuoi blocchi verranno visualizzati nei risultati di ricerca.

Anche se l'aggiunta di parole chiave è del tutto facoltativa, è un ottimo modo per rendere più facile agli utenti trovare i blocchi.

Attributes

Gli attributi consentono la gestione dinamica dei dati in un blocco. Questa proprietà è facoltativa poiché non ne avete bisogno per blocchi molto semplici che generano contenuto statico.

Tuttavia, se il blocco si occupa di dati che potrebbero cambiare (ad esempio il contenuto di un'area di testo modificabile) o avete bisogno di memorizzare le impostazioni del blocco, allora la strada da percorrere è utilizzare attributes.

Attributes funziona archiviando i dati del blocco dinamico o nel contenuto dell'articolo salvato nel database o nel post meta. In questo tutorial useremo solo gli attributi che archiviano i dati con il contenuto del post.

Per recuperare dati di attributo memorizzati nel contenuto dell'articolo, abbiamo bisogno di specificare dove si trova nel markup. Possiamo farlo specificando un selettore CSS che indichi i dati di attributo.

A esempio, se il nostro blocco contiene un tag di ancoraggio, possiamo utilizzarne il campo title come nostro attributo come segue:

Qui, il nome dell'attributo è linktitle, che è una stringa arbitraria e può essere qualsiasi cosa vi piaccia.

A esempio, potevamo utilizzare questo attributo per archiviare il titolo del collegamento <a title="some title"> che è stato immesso tramite una casella di testo nelle impostazioni del blocco. Facendo così all'improvviso rende dinamico il campo del titolo e vi permette di cambiare il suo valore nell'editor.

Quando l'articolo viene salvato, il valore dell'attributo viene inserito nel campo del collegamento title. Allo stesso modo, quando l'editor viene caricato, il valore del tag title è recuperato dal contenuto e inserito nell'attributo linktitle.

Ci sono molti modi in cui potete utilizzare source per determinare come i contenuti del blocco siano archiviati o recuperati tramite gli attributi. Per esempio, potete utilizzare il source di 'text' per estrarre il testo interno da un elemento paragrafo.

Potete anche utilizzare il source children per estrarre tutti i nodi figlio di un elemento in un array e memorizzarlo in un attribute.

Questo seleziona l'elemento con classe .parent e memorizza tutti i nodi figlio nell'attributo editablecontent.

Se non specificate una source allora il valore dell'attributo viene salvato nei commenti HTML come parte del markup dell'articolo quando salvato nel database. Questi commenti vengono rimossi prima che il post viene eseguito sul front-end.

Vedremo un esempio specifico di questo tipo di attributo quando ci occuperemo dell'implementazione del nostro blocco di immagine casuale più avanti in questo tutorial.

Ci vorrà un po' per abituarsi agli attributi, quindi non preoccupatevi se non li capite completamente la prima volta. Consiglierei di dare un'occhiata alla sezione attributi del manuale di Gutenberg per ulteriori dettagli ed esempi.

Edit

La funzione edit controlla come il blocco viene visualizzato all'interno dell'interfaccia dell'editor. I dati dinamici sono passati a ogni blocco come props, inclusi gli eventuali attributi personalizzati che sono stati definiti.

È pratica comune aggiungere className={props.className} all'elemento di blocco principale per produrre una classe CSS specifica per il vostro blocco. WordPress non lo aggiunge per voi all'interno dell'editor, quindi deve essere aggiunto manualmente per ogni blocco se volete includerlo.

Utilizzare props.className è una pratica standard ed è raccomandata in quanto fornisce un modo per personalizzare gli stili CSS per ogni singolo blocco. Il formato della classe CSS generata è .wp-block-{namespace}-{name}. Come potete vedere, è basato sul namespace/nome del blocco e lo rende ideale per essere utilizzato come un identificatore unico del blocco.

La funzione edit vi richiede di restituire un markup valido tramite il metodo render(), che viene quindi utilizzato per eseguire il blocco all'interno dell'editor.

Save

Similmente alla funzione edit, save mostra una rappresentazione visiva del blocco, ma sul front end. Riceve anche i dati del blocco dinamico (se definito) tramite props.

Una differenza principale è che props.className non è disponibile all'interno di save, ma questo non è un problema, perché viene inserita automaticamente da Gutenberg.

Supports

La proprietà supports accetta un oggetto di valori booleani per determinare se il vostro blocco supporta alcune funzionalità fondamentali.

Le proprietà dell'oggetto disponibile che potete impostare sono le seguenti.

  • anchor (valore predefinito false): consente di collegarvi direttamente a un blocco specifico
  • customClassName (true): aggiunge un campo nella finestra di ispezione del blocco per definire un className personalizzato per il blocco
  • className (true): aggiunge un className all'elemento radice del blocco basato sul nome del blocco
  • html (true): consente di modificare il markup del blocco direttamente

La proprietà useOnce

È una proprietà utile che consente di limitare un blocco dall'essere aggiunto più di una volta a una pagina. Un esempio di questo è il blocco fondamentale More, che non può essere aggiunto a una pagina se già presente.

useOnce property

Come si può vedere, una volta che il blocco More è stato aggiunto, l'icona di blocco è inattivo e non può essere selezionato. La proprietà useOnce è impostata su false per impostazione predefinita.

Diventiamo creativi!

È tempo ora di utilizzare la conoscenza che abbiamo accumulato finora per implementare un solido esempio di utilizzo di un blocco che fa qualcosa di più interessante che del semplice contenuto statico di output.

Costruiremo un blocco che dia come output un'immagine casuale ottenuta tramite una richiesta esterna al sito PlaceIMG, che restituisce un'immagine casuale. Inoltre, sarete in grado di selezionare la categoria di immagine restituita tramite un controllo con selezione a discesa.

Our random image block

Per comodità, aggiungeremo il nostro nuovo blocco per lo stesso plugin mio-blocco-personalizzato, anziché creare un nuovo plugin. Il codice per il blocco predefinito si trova all'interno della cartella /src/block, quindi aggiungete un'altra cartella all'interno di /src chiamata random-image e aggiungete tre nuovi file:

  • index.js: registra il nostro nuovo blocco
  • editor.scss: per gli stili dell'editor 
  • style.scss: gli stili per l'editor e il front end

In alternativa, potreste copiare la cartella /src/block e rinominarla se non volete digitare tutto a mano. Assicuratevi che, però, di rinominare block.js in index. js all'interno della nuova cartella del blocco.

Stiamo usando index.js per il nome del blocco principale poiché questo permette di semplificare l'istruzione di importazione all'interno di blocks.js. Invece di dover includere il percorso e il nome completo del file del blocco, possiamo specificare il percorso della cartella del blocco e import cercherà automaticamente un file index.js.

Aprite /src/blocks.js e aggiungete un riferimento al nostro nuovo blocco nella parte superiore del file, direttamente sotto l'attuale istruzione di importazione.

All'interno di /src/random-image/index.js, aggiungete il seguente codice per rilanciare il nostro nuovo blocco.

Questo imposta il framework del nostro blocco ed è abbastanza simile al codice boilerplate del blocco generato dal toolkit create-guten-block.

Iniziamo importando i fogli di stile dell'editor e del front-end, e poi estrarremo alcune funzioni comunemente utilizzate da wp.i18n e wp.blocks nelle variabili locali.

All'interno di registerBlockType(), i valori sono stati immessi per le proprietà title, icon, category e keywords, mentre le funzioni edit e save attualmente producono solo contenuto statico.

Aggiungete il blocco dell'immagine casuale a una nuova pagina per vedere l'output generato finora.

Bare bones block output

Assicuratevi che state ancora guardando i file per le modifiche poiché qualsiasi codice sorgente del blocco (JSX, ES6+, Sass, ecc.) viene tradotto in JavaScript e CSS validi. Se non state attualmente guardando i file per le modifiche, allora aprite una finestra della riga di comando all'interno della cartella radice del plugin mio-blocco-personalizzato e inserite npm start.

Potreste chiedervi perché non abbiamo dovuto aggiungere alcun codice PHP per accodare degli script di blocco aggiuntivo. Gli script di blocco per il blocco di my-custom-block vengono accodati tramite init.php, ma non abbiamo bisogno di accodare gli script appositamente per il nostro nuovo blocco poiché questo pensa per noi create-guten-block.

Fintanto che importiamo i nostri file del blocco principale in src/blocks.js (come abbiamo fatto sopra) poi non abbiamo bisogno di fare alcun lavoro supplementare. Tutto il codice JSX, ES6+ e Sass sarà compilato automaticamente nei file seguenti:

  • dist/blocks.style.build.css: stili per l'editor e il front end
  • dist/blocks.build.js: JavaScript per il solo editor
  • dist/blocks.editor.build.css: stili per il solo editor

Questi file contengono il codice JavaScript e CSS per tutti i blocchi, quindi solo un set di file deve essere accodato, indipendentemente dal numero dei blocchi creati!

Ora siamo pronti ad aggiungere un po' di interattività al nostro blocco, e possiamo farlo prima di tutto aggiungendo un attributo per memorizzare la categoria immagine.

Questo crea un attributo denominato category, che memorizza una stringa con un valore predefinito di 'nature'. Non abbiamo specificato un posizione nel markup per archiviare e recuperare il valore dell'attributo, quindi verranno utilizzati invece commenti HTML speciali. Questo è il comportamento predefinito se si omette una fonte dell'attributo.

Abbiamo bisogno di qualche modo per cambiare la categoria dell'immagine, che possiamo fare tramite un controllo di selezione a discesa. Aggiornate la funzione edit come segue:

Ecco come apparirà:

Adding a block select drop down control

È abbastanza diversa dalla precedente funzione statica edit, quindi ripercorriamo i cambiamenti.

In primo luogo abbiamo aggiunto un controllo di selezione a discesa con diverse scelte corrispondenti alle categorie dell'immagine disponibili sul sito PlaceIMG.

PlaceIMG image categories

Quando cambia il valore dell'elenco a discesa, viene chiamata la funzione setCategory, che trova la categoria attualmente selezionata e poi a sua volta chiama la funzione setAttributes. Questa è una funzione fondamentale di Gutenberg e aggiorna un valore dell'attributo correttamente. Si consiglia di aggiornare solo un attributo utilizzando questa funzione.

Ora, ogni volta che una nuova categoria è selezionata, il valore dell'attributo si aggiorna ed è passato nuovamente nella funzione edit, che aggiorna il messaggio di output.

Image category updated

Dobbiamo completare un ultimo passo per ottenere l'immagine casuale da visualizzare. Abbiamo bisogno di creare un componente semplice che porterà nella categoria corrente e produrrà un tag <img> con un'immagine casuale reperita sul sito PlaceIMG.

La richiesta che dobbiamo fare a PlaceIMG assume la forma: https://placeimg.com/[width]/[height]/[category]

Terremo la larghezza e l'altezza fisse per ora, poiché dobbiamo solo aggiungere la categoria corrente alla fine della richiesta dell'URL. A esempio, se la categoria è stata 'nature' quindi la richiesta dell'URL completa sarebbe: https://placeimg.com/320/220/nature.

Aggiungete un componente RandomImage sopra registerBlockType():

Per utilizzarlo, basta aggiungerlo all'interno della funzione edit e rimuovere il messaggio di output statico. Già che ci siamo, fate lo stesso per la funzione save.

Il file index.js completo ora dovrebbe assomigliare a questo:

Infine (per ora), aggiungete i seguenti stili a editor.scss per aggiungere un bordo colorato intorno all'immagine.

Avrete anche bisogno di alcuni stili in style.css.

Ogni volta che la pagina viene aggiornata nell'editor o sul front-end, verrà visualizzata una nuova immagine casuale.

Finished editor view
Final front end view

Se vedrete la stessa immagine visualizzata più e più volte, si può fare un aggiornamento forzato per evitare che l'immagine abbia il benservito dalla cache del vostro browser.

Conclusione

In questo tutorial abbiamo fatto un bel po' di strada. Se avete fatto tutto il percorso fino a ora allora datevi una ben meritata pacca sulla spalla! Lo sviluppo del blocco di Gutenberg può essere molto divertente, ma è sicuramente difficile da cogliere ogni concetto alla prima esposizione.

Lungo la strada, abbiamo imparato come accodare gli script e gli stili del blocco e coperto la funzione registerBlockType() in profondità.

Abbiamo continuato passando dalla teoria alla pratica e creando un blocco personalizzato da zero per visualizzare un'immagine casuale da una categoria specifica utilizzando il servizio web PlaceIMG.

Nella prossima e ultima parte di questa serie di tutorial, aggiungeremo ulteriori funzionalità al nostro blocco dell'immagine casuale tramite il pannello delle impostazioni nella finestra di ispezione del blocco.

Se state seguendo questo tutorial e volete semplicemente sperimentare il codice senza digitare tutto, potete scaricare il plugin finale del mio-blocco-personalizzato nel prossimo tutorial.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.