Sviluppo Gutenberg con esempi: Google Maps (parte 2)

Ciao! Siamo tornati con il nostro tutorial per sviluppare in Gutenberg. La scorsa settimana abbiamo avviato un progetto che ha aggiunto un blocco mappa in WordPress. In quel primo post abbiamo definito quali fossero i requisiti che il nostro plugin deve soddisfare e abbiamo preparato lo scheletro di quello che finirà per essere il prodotto finale, partendo dal fantastico plugin boilerplate che abbiamo creato in Nelio.

Oggi arriva la seconda parte del tutorial su come creare il blocco mappa . In questo post vedremo come aggiungere una mappa di Google Maps all'interno dell'editor di WordPress e come implementare un'interfaccia utente che ci permetta di manipolarne il comportamento.

Un rapido sguardo allo stato attuale del progetto...

Allo stato attuale del progetto abbiamo un semplice blocco Demo definito in packages/blocks/demo/ . Questo piccolo blocco è quello che viene fornito come esempio nel boilerplate del plugin di Nelio e si presenta così:

Ovviamente, questo non è quello che vogliamo. Non ci interessa un'icona a forma di cuore seguita da del testo, ma qualcosa del genere:

Cioè, vogliamo un blocco di Google Map con un indicatore opzionale al suo interno. Come possiamo passare dal blocco di esempio originale che aveva il nostro boilerplate a questo altro blocco più potente? Bene, questo è quello a cui risponderemo oggi!

Ma prima, lasciami investire un paio di minuti spiegando cosa abbiamo in questo momento e come andremo avanti. Penso che, se capisci lo stato attuale del progetto, ti sarà più facile seguire ciò che verrà dopo.

Capire il blocco Demo ...

Come ho già detto, il blocco demo è definito in packages/blocks/demo/ . In questa cartella troverai gli stili del blocco, la sua icona e diversi file con il codice che ne implementa il funzionamento. Vediamo i file più importanti.

Da un lato, c'è il file principale: index.js . Questo file esporta tre variabili: il nome del blocco ( name ), la definizione del blocco ( settings ) e gli stili supportati dal blocco ( styles ). Queste tre variabili sono quelle utilizzate in packages/blocks/index.js per registrare il blocco in Gutenberg (con registerBlockType ) e quindi renderlo disponibile agli utenti finali.

Questo file principale, quindi, funge da punto di ingresso per comprendere il blocco che stiamo creando. Nelle impostazioni dell'oggetto ( settings ), vediamo tre proprietà importanti: attributes , edit e save . Ognuna di queste proprietà ha il proprio file JavaScript (per semplicità e facilità di comprensione), ciascuna denominata in base alla proprietà corrispondente. Diamo una rapida occhiata a tutti loro:

• Il file attributes.js definisce tutte quelle proprietà del nostro blocco che sono dinamiche e, quindi, dovrebbero essere modificabili dai nostri utenti. Nel caso del nostro blocco Demo , l'unico attributo che esiste è il testo che l'utente ha scritto, ma il blocco mappa avrà molte più opzioni: le coordinate del centro della mappa, il livello di zoom predefinito che la mappa dovrebbe usare, cosa i pulsanti (se presenti) dovrebbero essere visibili per interagire con la mappa, ecc.
• Il file edit.js è quello che definisce come viene visualizzato il blocco nell'editor di WordPress e quali impostazioni vengono offerte all'utente (sia nella barra degli strumenti che nella barra laterale delle impostazioni del blocco). In Demo , la edit include semplicemente il componente RichText di WordPress per scrivere il contenuto. Come vedremo, il blocco della mappa sarà più complesso e includerà anche impostazioni aggiuntive.
• Infine, save.js definisce il metodo che converte il blocco che stavamo modificando in Gutenberg nell'HTML che deve essere renderizzato nel front-end. Di nuovo, in Demo vediamo che questa funzione salva semplicemente il contenuto di un RichText usando RichText.Content , ma potrebbe essere qualsiasi altra cosa (come vedremo la prossima settimana nella terza e ultima parte di questo tutorial).

Creazione del Blocco Mappa Basato sul Blocco Demo Incluso nel Plugin Boilerplate

Una volta capito esattamente come funziona il blocco Demo , è il momento di chiederci: come creiamo il nostro? Bene, molto semplice: come ci ha detto Toni qualche giorno fa, dobbiamo semplicemente duplicare la directory packages/blocks/demo/ in packages/blocks/nelio-maps/ e iniziare a modificare tutto il necessario. Lo so, è più facile a dirsi che a farsi.

Iniziamo con qualcosa di semplice: attributes.js . Questo file contiene tutte le proprietà che dovrebbero essere modificabili dai nostri utenti finali. Nel post precedente abbiamo specificato quali requisiti dovrebbe soddisfare il nostro plugin e, quindi, abbiamo delineato quali cose dovrebbero essere modificabili. Bene, dando un'occhiata agli attributes.js risultanti vedrai chiaramente cosa può essere modificato dal nostro blocco mappa: livello di zoom, centro mappa, visibilità di diversi pulsanti... Roba semplicissima!

Il punto successivo da modificare è tutto ciò che riguarda l'edizione del blocco di Gutenberg. Per fare ciò, dobbiamo immergerci in edit.js . Se guardi da vicino, vedrai che non è molto più complicato di quello che avevamo nel nostro blocco Demo originale.

La cosa più importante è nel metodo render del blocco (riga 33), dove recuperiamo gli attributi che abbiamo appena definito da un oggetto chiamato this.props . Useremo queste proprietà per renderizzare il blocco e le sue impostazioni, ovviamente. Questo è quello che abbiamo:

1. Una toolbar ToolbarControls (riga 66), che abbiamo definito in un file esterno chiamato toolbar.js (non preoccupatevi, ne vedremo il contenuto tra un minuto).
2. Le impostazioni del blocco che compaiono nella barra laterale dell'editor (riga 68), che troviamo in un componente chiamato Inspector che abbiamo definito in inspector.js .
3. Il contenuto del blocco stesso, che ha due stati:
   • Se non ho una chiave API di Google Maps disponibile, mostriamo un avviso per l'utente (riga 122).
   • Se abbiamo questa chiave, mostriamo la mappa usando MapBlock (riga 83). La mappa potrebbe includere un Marker (riga 97), che è visibile solo quando l'opzione è attivata, e potrebbe anche essere accompagnata da un div (riga 104) con informazioni aggiuntive a riguardo.

Google Maps come componente di reazione

Se vogliamo inserire una mappa di Google nel nostro editor, dobbiamo utilizzare un componente che ci consenta di utilizzare l'API Maps di Google Maps. Considerando che Gutenberg è costruito su React, la cosa logica da fare è scoprire se esiste un componente React di Google Maps. E, certo, ce n'è uno!

Come puoi leggere nella documentazione del progetto, prima dobbiamo aggiungere il componente al nostro progetto. Basta installare e aggiungere la dipendenza eseguendo il seguente comando:

 npm install react-google-maps --save-dev

che aggiunge una nuova voce nel nostro package.json e scarica il pacchetto in node_modules .

Come creare un componente WordPress che incapsula un componente React

Se continuiamo a guardare la documentazione di questo progetto React per Google Maps, vedremo che ci consigliano di avvolgere il loro componente GoogleMap con il nostro componente. Una volta incapsulato, dovremo utilizzare il nostro componente nel nostro plugin.

Bene, seguiamo il loro esempio e creiamo un componente chiamato MapBlock nel proprio file map-block.js . E questo è tutto! Ora abbiamo un componente mappa pronto che possiamo usare nel nostro blocco Gutenberg.

Come aggiungere le impostazioni dei blocchi nell'Inspector dell'editor di WordPress

Il passaggio successivo consiste nel configurare l'aspetto di questa mappa nell'editor e aggiungere alcune impostazioni per modificarne l'aspetto. Per fare ciò, dobbiamo aggiungere diverse sezioni delle impostazioni nella barra laterale di Gutenberg. Come ho già anticipato, lo otteniamo con un componente che abbiamo chiamato Inspector e che abbiamo definito nel file inspector.js .

Se dai un'occhiata a questo file, vedrai che segue lo stesso schema di sempre: stiamo definendo un Component con un metodo di render . Questo metodo estrae gli attributi rilevanti in this.props e restituisce JSX con tutti i controlli. In questo caso particolare, restituisce un'istanza di InspectorControls (questo dice a WordPress che questo contenuto va alla barra laterale) con diverse sezioni PanelBody . Vediamo ogni sezione nel dettaglio.

Impostazioni di base della mappa

Il primo PanelBody che abbiamo trovato (riga 47) non ha title e, quindi, appare sempre come una sezione che non può essere chiusa:

La sezione definisce una coppia di RangeControl , il cui risultato puoi vedere nello screenshot precedente. Questi due controlli ci consentono di modificare l'altezza della mappa e il suo livello di zoom.

Un'altra sezione interessante e semplice è quella che si trova alla riga 121. Qui aggiungiamo alcune opzioni per attivare o disattivare i pulsanti che dovrebbero essere visualizzati sulla mappa quando visualizzati nel front-end :

Per fare ciò, dobbiamo semplicemente utilizzare il componente WordPress predefinito CheckboxControl .

Come aggiungere una sezione di stile personalizzato per il nostro blocco mappa

Un'altra sezione interessante del nostro blocco è la sezione degli stili (riga 68). Puoi vedere il risultato finale nel seguente screenshot:

È una sezione speciale perché il componente che utilizziamo ( MapStyles ) non è qualcosa che esiste in WordPress per impostazione predefinita, ma qualcosa che abbiamo creato per questo blocco in particolare. Come puoi vedere nel link precedente, è un componente che carica un insieme di stili predefiniti in un componente di tipo ImagePicker (che, per inciso, non esiste nemmeno per impostazione predefinita in WordPress: puoi trovarlo in packages/components/image-picker/ ).

Quando l'utente seleziona uno degli stili inclusi in ImagePicker , il componente MapStyles richiama la funzione onChange che gli è stata assegnata (vedi riga 76 di inspector.js ) passando due valori: il nome dello stile selezionato e il JSON associato.

Infine, nota che una delle opzioni incluse in MapStyles è uno stile personalizzato :

Quando selezionato, il componente esegue il rendering di una casella di testo aggiuntiva (riga 45) in modo che l'utente possa inserire il proprio stile in formato JSON. Nel caso non lo sapessi, le mappe di Google Maps possono essere molto personalizzate!

Come aggiungere un indicatore nella nostra mappa

La prossima sezione che abbiamo è quella che controlla il nostro marker (linea 81). Questa sezione ci permette di mostrare o nascondere il marker (riga 86) e, quando attiva, ci fornisce alcune impostazioni aggiuntive:

Come vedete, compare una casella di ricerca per cercare posizioni in Google Maps (che abbiamo implementato, ancora, con un componente personalizzato chiamato AddressSearch ) e la possibilità di mostrare o nascondere il blocco di testo in cui inserire informazioni aggiuntive sul marker.

A proposito, nota che il componente AddressSearch è basato su un componente chiamato StandaloneSearchBox , che fa anche parte del progetto React . Che piacere riutilizzare il lavoro degli altri!

Come configurare la barra degli strumenti di un blocco

L'ultima cosa di cui dobbiamo discutere è la barra degli strumenti. Se hai capito come funziona la barra laterale, la barra degli strumenti è un gioco da ragazzi.

La barra degli strumenti del nostro plugin è rappresentata dal componente ToolbarControls definito in toolbar.js . Qui aggiungiamo semplicemente un componente per definire l'allineamento del blocco ( BlockAlignmentToolbar , alla riga 42), una coppia di dropdown per centrare la mappa (riga 50) e per modificare la posizione del marker (riga 79), e un paio di pulsanti extra per modificare la posizione della casella di testo in cui possiamo inserire informazioni aggiuntive sul marker (righe 107 e 120).

In sintesi

Oggi abbiamo visto come creare l'intera interfaccia di modifica del nostro blocco mappa. Come puoi vedere, è un processo che potrebbe sembrare complicato a prima vista, ma diventa abbastanza naturale rapidamente. Alla fine, il segreto è partire da un esempio ben organizzato (come è il nostro plugin boilerplate) e costruire l'interfaccia passo dopo passo, riutilizzando i componenti che WordPress offre o che già esistono, o addirittura creandone di propri.

Alla prossima settimana con l'ultima parte di questo tutorial, dove vedremo come salvare la nostra mappa e come visualizzarla nel front-end .

Immagine in primo piano di rawpixel su Unsplash .