Come creare blocchi Gutenberg, nel modo più semplice

Cos’è Gutenberg?

Gutenberg è il nuovo editor per WordPress, che sostituirà il vecchio TinyMCE. Mentre scriviamo Gutenberg non è considerato abbastanza maturo per la produzione, ma lo sarà presto (è prevista la fusione completa in WordPress 5.0 alla fine del 2018); è disponibile come plugin, in modo che gli autori di blog e gli sviluppatori possano familiarizzare con esso – e dare un feedback.

Il concetto principale

Gutenberg sta cercando di superare la fase di authoring tradizionale dando all’autore la possibilità di inserire contenuti ricchi – non solo testo semplice, ma immagini, gallerie, video, citazioni, contenuti dei social media e molti molti altri – introducendo il concetto di “blocchi”.

Cos’è un blocco? Fondamentalmente è un’unità di (qualsiasi) contenuto che può essere modificato, organizzato (sorprendentemente) in un blocco. Gutenberg viene fornito con un set predefinito di blocchi, che vanno dalla semplice modifica del testo (titoli, paragrafi, elenco, ecc.) al contenuto multimediale (immagine, galleria, audio, video) al contenuto incorporato da più fonti (in particolare i social media); quindi, all’uso, il toolkit predefinito è abbastanza ricco e attraente.

Ma se volessi crearne uno nuovo? Ecco la buona notizia: è possibile!

Sviluppo di un blocco: le basi

I blocchi di Gutenberg sono fatti quasi interamente in JavaScript, quindi tutto quello che dovete sapere è la versione standard del linguaggio (ES5). Secondo le persone che lo hanno sviluppato, l’API non è legata a nessun framework – solo il vecchio e semplice JavaScript.

Tuttavia, il modo in cui funziona un blocco Gutenberg è davvero simile a un componente React e la comprensione di ES6 (JavaScript moderno) e JSX (la nuova sintassi JavaScript introdotta da React) farà scoprire tutto il suo potenziale. Anche se non è necessario, è altamente raccomandato:

• usare una sintassi JavaScript moderna (ES6) e JSX
• avere una comprensione almeno di base di React

Sembra davvero complicato…

Beh, non proprio…Per fortuna, c’è un’applicazione chiamata create-guten-block, disponibile come npm, che farà tutto il lavoro pesante per noi. L’app crea tutta l’impalcatura, cioè i file e le configurazioni necessarie al blocco per funzionare, lasciandoci concentrare solo sulla funzionalità. Viene anche fornito con un listener, così qualsiasi modifica che facciamo viene immediatamente tradotta nei file di build. Piuttosto comodo!

Allo stesso tempo, possiamo usare un sacco di oggetti predefiniti (principalmente componenti dell’editor) che vengono forniti di default con l’API del blocco, in modo da non dover scrivere molto codice per ottenere un’interfaccia piuttosto accattivante.

Anatomia di un blocco Gutenberg

Una volta che create-guten-block ha terminato il suo lavoro, possiamo osservare tutti i nuovi file e cartelle creati per noi nella cartella principale. Immergiamoci un pò. I file che andremo a modificare per sviluppare il blocco si trovano nella cartella src . Questi file verranno automaticamente trasferiti nel codice di produzione, che si trova nella cartella dist .

Quindi in realtà ciò che conta è in src, che è composto da:

• init.php, il file in cui è effettivamente registrato il plugin. Poiché l’app ha già svolto il lavoro per noi, possiamo lasciarla così com’è
• la cartella block , dove si trovano tutte le cose importanti. Ci prenderemo cura di tutti loro!

Il file editor.scss è l’aspetto grafico di come sarà il blocco nel back-end. Non sorprende che style.scss sia la sua controparte sul front-end, ovvero: la pagina web. Sono entrambi file SASS e verranno compilati in normali file CSS.

Il block.js è dove risiedono tutte le funzionalità ed è, quindi, la più importante. Tutta la magia viene eseguita all’interno del metodo create-guten-block registerBlockType , che è responsabile della creazione del blocco stesso. Occorrono quattro parametri:

• un nome univoco per il blocco;
• un oggetto di inizializzazione, contenente alcune informazioni di configurazione e gli speciali attributi oggetto;
• la funzione modifica ;
• la funzione salva .

Le funzioni modifica e salva controllano il comportamento del blocco, rispettivamente, nella parte posteriore e nella parte anteriore. L’installazione predefinita dell’app mostra un semplice messaggio codificato con un testo (e colore di sfondo) diverso a seconda del lato (posteriore o anteriore o, in altri termini, modifica o  salva ). Questi sono i due pezzi di codice su cui lavoreremo di più.

Una menzione speciale per l’oggetto attributi. Questo oggetto è il modo in cui trattiamo i dati dinamici nel blocco ed è praticamente lo stesso di quello che React chiama “stato”. Quindi, se è probabile che i dati nel blocco cambino (e probabilmente lo faranno), ad esempio, un campo che può essere modificato da un editor di testo avanzato, dobbiamo salvarli negli attributi (e quindi saranno salvato nel database).

Immergiamoci nel codice

Creeremo un blocco molto semplice con i seguenti elementi:

• un titolo di secondo livello (h2)
• un’immagine
• una linea laterale
• un link “Leggi di più”

Il primo passaggio è eseguire create-guten-block e aprire il file block.js all’interno di src/block.

Nota: si consiglia di modificare il nome del blocco, che ora è “cgb/block-myblock”; ricorda che il nome deve contenere un prefisso (tutto prima della barra).

Importazione di tutte le utilità di cui abbiamo bisogno

Nel nostro blocco semplice utilizzeremo un editor di base (dove digiteremo il titolo e il testo della sideline), un componente di caricamento delle immagini e un campo di testo di base per l’URL di ancoraggio. Invece di sviluppare tutti questi componenti, possiamo semplicemente utilizzare quelli che WordPress ci offre, velocizzando così la fase di sviluppo. Tutto quello che dobbiamo fare è importarli all’inizio del nostro file:

import './style.scss';
import './editor.scss';
const {__} = wp.i18n;
const {registerBlockType} = wp.blocks;
const {RichText,MediaUpload,InspectorControls} = wp.editor;
const {PanelBody, PanelRow, Button } = wp.components;

Il componente RichText è un editor di base con pochi controlli; lo useremo per il titolo e la sideline. Il InspectorControls rappresenta la barra laterale di configurazione sulla destra: inseriremo qui il campo di testo per l’URL di ancoraggio. PanelBody e  PanelRow sono i sottocomponenti di InspectorControls. Infine,  MediaUpload è il componente per il caricamento dell’immagine; sfrutteremo l’elemento predefinito Pulsante per lo scopo.

L’oggetto init 

Il secondo parametro del metodo registerBlockType è un oggetto di inizializzazione in cui puoi specificare molte informazioni utili; ciò che conta di più è l’oggetto attributi. In base al risultato che stiamo cercando di ottenere, dobbiamo memorizzare le seguenti informazioni:

• il contenuto del titolo
• il file sorgente dell’immagine
• l’ID media (relativo alle funzionalità principali di WordPress)
• il contenuto sideline
• l’URL del collegamento

Ogni informazione ha bisogno di essere codificata in modo diverso, a seconda del suo ruolo; i suoi attributi principali sono:

• type
• source
• selector

Il tipo può essere una semplice stringa o un array. Ad esempio, il testo della sideline sarà un array perché al suo interno possiamo avere elementi nidificati (il testo in grassetto verrà tradotto in un tag forte , il testo in corsivo in un i tag; ciò è dovuto all’editor che useremo, che ci dà questo tipo di controllo sul testo). Per lo stesso motivo, la sua “fonte” (ovvero: contenuto) sarà l’intero set dei suoi figli (contenuto puro più markup – tag forti e i  come affermato in precedenza ).

Storia diversa per il file sorgente dell’immagine: è una semplice stringa, la cui sorgente è un attributo (quindi abbiamo bisogno della proprietà “attribute” con “src” come valore).

La proprietà selector corrisponderà all’elemento HTML nella funzione di modifica, in modo che possiamo dire al sistema quale contenuto dell’elemento è il contenuto dell’attributo. Può essere qualsiasi selettore CSS valido.

Il nostro init object dovrebbe essere:

{
   title : __('Immagine con testo'), // Titolo del Block.
   description : 'Un semplice blocco',
   icon: 'format-image', // Icona di blocco da Dashicons → https://developer.wordpress.org/resource/dashicons/.
   category : 'common', // Categoria di blocco: raggruppa i blocchi in base a tratti comuni, ad es. comune, formattazione, widget di layout, incorporamento.
    parole chiave : [
      __(image), __(text)
   ],
   attributes: {
      title: {
         type: 'array',
         source: 'children',
         selector: 'h2'
      },
      mediaID: {
         type: 'number'
      },
      mediaURL: {
         type: 'string',
         source: 'attribute',
         selector: 'img',
         attribute: 'src',
         sideline: {
            type: 'array',
            source: 'children',
            selector: 'p'
         },
         linkURL: {
            type: 'string',
            default: 'http://example.com'
         }
      }
   }
}

La funzione di modifica

La funzione di modifica rappresenta l’interfaccia sul back-end, quindi cosa vedremo una volta aggiunto il blocco nella pagina. Prende come parametro un oggetto (chiamato convenzionalmente ‘props’) all’interno del quale possiamo trovare tutte le informazioni disponibili nello ‘stato’ (l’oggetto ‘attributi’).

Quindi, il primo passo è ottenere tutte le informazioni di cui abbiamo bisogno:

const {attributes: {title,mediaID,mediaURL,sideline,linkURL }, setAttributes} = props;

All’interno della dichiarazione di ritorno c’è il codice effettivo che verrà visualizzato:

return (<div className={props.className}>
  <InspectorControls>
      <PanelBody title={__('Link URL')}>
         <PanelRow>
            <label>Link URL</label>
            <input type='text' value={linkURL} onChange={onChangeURL}>
      </PanelRow>
      </PanelBody>
   </InspectorControls>
   <RichText tagName='h2' placeholder={__('Title')} value={title} onChange={onChangeTitle}/>
      <div className='block-image'>
         <MediaUpload onSelect={onSelectImage} type='image' value={mediaID} render={({open}) => (<Button className={mediaID
                  ? 'image-button'
                  : 'button button-large'} onClick={open}>
               {
                  !mediaID
                     ? __('Upload Image')
                     : <img src={mediaURL} alt={__('Upload Image')}/>
               }
            </Button>)}/>
      </div>
      <RichText tagName='p' placeholder={__('Sideline’ )} value={sideline} onChange={onChangeSideline}/>
   </div>);

La prima cosa da osservare è come lo stato del blocco, ovvero: ciò che è contenuto all’interno dell’oggetto attributi, sia fonte di contenuto per tutti gli elementi. Questo approccio è lo stesso di lo stato come unica fonte di verità nelle applicazioni React; in pratica significa che il contenuto degli elementi è sempre la proprietà corrispondente dell’oggetto attributi e, non appena lo modifichiamo (ovvero: modificando il contenuto negli editor o scegliendo un’immagine diversa), aggiornare anche l’oggetto attributi. Questo avviene tramite la proprietà onChange di ogni elemento, all’interno della quale specifichiamo la funzione che se ne occupa. Per esempio:

function onChangeSideline(newValue) {
 setAttributes({sideline: newValue});
}

Dove setAttributes è la funzione principale di Gutenberg per aggiornare lo stato. Poiché tutte queste funzionalità vengono utilizzate solo all’interno della funzione modifica, ha senso definirle anche nello stesso ambito.

La funzione di salvataggio

Dove (finalmente) possiamo renderizzare il blocco sul front-end. Questa funzione prende come parametro lo stesso oggetto di quello di edit, quindi abbiamo tutte le informazioni che abbiamo modificato nel back-end:

save: ( props ) => {
      const {
         className,
         attributes: {
            title,
            mediaURL,
            sideline,
            
         },
      } = props;
      return (
         <div className={ className }>
            <RichText.Content tagName="h2" value={ title } />
            {
               mediaURL && (
                  <img src={ mediaURL } alt={ __( {title} ) } />
               )
            }
            <RichText.Content tagName="p" value={ sideline } />
         </div>
      );
   },

Niente di speciale da notare, a parte il fatto che stiamo ricevendo i contenuti degli editori attraverso la proprietà RichText.Content.

Passaggi successivi

Possiamo occuparci degli stili, sia nel back-end che nel front-end, modificando i file SASS corrispondenti.

Considerazioni finali

Questo è tutto, praticamente! Anche se piuttosto semplice, questo esempio dà l’idea di cosa puoi fare con questa potente API. Gutenberg è il futuro di WordPress, quindi è meglio iniziare a familiarizzare con esso e sviluppare dei bei blocchi!

Risorse

• Crea Guten Block – l’app 
• Esempi Gutenberg