Come aggiungere un pulsante all'editor Gutenberg usando @wordpress/scripts

Quasi un anno e mezzo fa, Antonio ha scritto questo post sul blog spiegando una delle difficoltà che abbiamo dovuto affrontare quando abbiamo adattato i nostri plugin al nuovo editor di blocchi di WordPress. Il risultato del suo tutorial era simile a questo:

Fortunatamente o sfortunatamente, Gutenberg è cambiato molto in quest'anno e mezzo. Lo stack di sviluppo si è ampliato e migliorato e gli sviluppatori di plugin e temi hanno dovuto abbracciare e adattare le nuove tecnologie. E quelli di noi che scrivono anche della nostra esperienza e condividono ciò che apprendiamo sono ora "costretti" ad aggiornare i nostri tutorial in modo che tu possa tenerti aggiornato. Ma ne siamo felici!

Qualche settimana fa, Ivan, uno dei nostri lettori, ci ha lasciato un commento nel tutorial di Antonio chiedendoci aiuto. Apparentemente non è stato in grado di implementare il plugin di Antonio. E, a dire il vero, questo non mi sorprende, perché ultimamente le cose sono molto cambiate. Quindi, per aiutare Ivan e tutti voi che ci leggete e volete continuare a conoscere WordPress, ricreiamo il tutorial su come aggiungere un pulsante all'editor dei blocchi di Gutenberg sfruttando tutti i nuovi strumenti che WordPress ci offre!

Crea un plug-in

La prima cosa che dobbiamo fare è creare un plugin per WordPress. Questo è abbastanza semplice. Fondamentalmente, non dobbiamo far altro che creare una cartella in wp-content/plugins con il nome che vogliamo dare al nostro plugin (ad esempio, gutenberg-button ) e, al suo interno, creare un file con lo stesso nome e un'estensione .php estensione .php . Quindi digita il seguente codice nel file del plug-in:

Ora, diamo un'occhiata più da vicino a ciò che fa lo snippet precedente:

• Per prima cosa apriamo un tag <?php . Nessuna sorpresa qui.
• Successivamente, in questo file principale, aggiungiamo un commento su più righe. Il commento include diverse righe con coppie "Chiave / Valore". Ad esempio, vediamo come specifichiamo il nome del plugin ( Plugin Name ), la sua versione ( Version ) o il nome dell'autore ( Author ). Tutte queste informazioni saranno quindi visibili nella sezione Plugin all'interno di WordPress.
• Infine, aggiungiamo del codice boilerplate:
  • specifichiamo uno namespace (ne abbiamo parlato qui),
  • ci assicuriamo che, se il file viene eseguito, venga eseguito come parte di WordPress e
  • definiamo alcune costanti sul plugin (che saranno utili in seguito).

Una volta che abbiamo fatto tutto questo, se andiamo nella schermata Plugin del nostro WordPress, vedremo che il pulsante Gutenberg è lì:

lo attiviamo e… voilà! Certo, non farà nulla, ma è già lì.

Sviluppo plugin JavaScript

Al giorno d'oggi, gli sviluppatori di WordPress devono essere esperti con JavaScript. Questa è una delle conseguenze del fatto che Gutenberg sia al centro, immagino. E questo tutorial non fa eccezione.

Preparare l'ambiente

Se vogliamo aggiungere un nuovo pulsante all'interfaccia di Gutenberg, dobbiamo codificare questa funzione in JavaScript. Quindi prepariamo l'ambiente di sviluppo JavaScript nel nostro plugin. Per fare ciò, esegui semplicemente il seguente comando dalla tua riga di comando (assicurati di essere in wp-content/plugins/gutenberg-button quando lo fai):

 npm init

e segui le istruzioni:

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

Il risultato di questo processo è un file package.json . Come vedrai tra pochi istanti, questo file sarà estremamente utile in futuro.

Come ho già rivelato nel titolo di questo post, useremo @wordpress/scripts per creare il nostro plugin. Quindi aggiungiamolo come dipendenza eseguendo il seguente comando:

 npm install --save-dev @wordpress/scripts

Questo comando scaricherà un sacco di dipendenze all'interno del nostro plugin (sotto node_modules ) e modificherà il nostro package.json in modo che sia chiaro che @wordpress/scripts è ora una dipendenza di sviluppo.

Se dai un'occhiata alla documentazione di questo pacchetto, vedrai che include molti script per costruire, convalidare la sintassi, formattare il codice, ecc:

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

quindi modifichiamo il nostro file package.json in modo che la sezione "scripts" contenga tutti i comandi consigliati.

Come verificare che tutto funzioni...

Creiamo una cartella src nella radice del tuo progetto e aggiungiamo un file index.js al suo interno. Questo sarà il file JavaScript principale del nostro plugin e conterrà tutto il tuo codice (puoi quindi organizzare il codice a tuo piacimento, purché il file principale sia src/index.js ).

Proviamo se le cose funzionano come previsto aggiungendo la seguente istruzione index.js :

 console.log( 'Hi!' );

e costruire il progetto usando npm run build . Questo trasformerà il tuo codice in qualcosa che può essere eseguito da un browser (in realtà non era necessario in questo momento, ma lo sarà tra un paio di minuti) e genererà un nuovo script all'interno di una cartella di build .

Tutto quello che dobbiamo fare ora è dire a WordPress che questo script esiste in modo che possa caricarlo. Per farlo, apri semplicemente il file principale del tuo plugin ( gutenberg-button.php ) e aggiungi le seguenti righe alla fine:

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Se presti attenzione, vedrai che stiamo semplicemente dicendo a WordPress di accodare il nostro nuovo script /build/index.js come risorsa dell'editor di blocchi. In questo modo, quando un utente accede all'editor di blocchi, il nostro script farà parte degli asset che l'editor includerà.

Quindi diamo un'occhiata. Vai alla dashboard di WordPress, modifica un post e guarda la console JavaScript del tuo browser. Se le cose sono andate come previsto, dovresti vedere "Ciao!" scritto sulla console:

Replicando il nostro tutorial per aggiungere un pulsante a Gutenberg

Ok, ora che abbiamo visto che possiamo scrivere codice JavaScript e npm run build it in qualcosa che i nostri browser capiranno, è tempo di replicare il tutorial di Antonio. E questo, caro lettore, è estremamente semplice.

Aprire il file src/index.js e sostituire l'istruzione console.log precedente con la seguente:

Come puoi vedere, questo è quasi lo stesso codice scritto da Antonio qualche mese fa. La differenza principale è il fatto che non utilizziamo più la variabile globale wp per accedere alle funzioni e ai componenti di Gutenberg; invece, ora ci affidiamo alle istruzioni di import . Ma a parte questo, è praticamente lo stesso.

Una volta che hai scritto il codice, esegui semplicemente npm run build it e il gioco è fatto! Ora hai il pulsante in Gutenberg:

Assicuriamoci che funzioni selezionando del testo e facendo clic sul pulsante:

e il gioco è fatto, vediamo che il testo appare di nuovo nella console!

Un'ultima nota sulle dipendenze...

Se dai un'occhiata all'interno della cartella build , vedrai che @wordpress/scripts non solo ha creato un file index.js , ma ha un file index.asset.php . Questo file definisce un piccolo oggetto con due proprietà:

• un elenco di dipendenze (vale a dire, script WordPress) richieste dal nostro plugin
• una versione build

Possiamo (e dovremmo) usare entrambe queste proprietà quando accodiamo il nostro script in WordPress se vogliamo assicurarci che lo script funzioni correttamente. Per farlo, torna semplicemente su gutenberg-button.php e modificalo come mostrato di seguito:

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Carica semplicemente l'oggetto in index.asset.php usando un'istruzione include e sostituisci l'elenco delle dipendenze che avevamo ( [] ) con le dipendenze effettive e usa il numero di build come versione del plugin.

Conclusioni

Creare plugin per WordPress davvero utili è complicato. Devi capire bene come funziona JavaScript e avere familiarità con tutte le risorse di WordPress. Ma grazie al pacchetto @wordpress/scripts , preparare l'ambiente di sviluppo JavaScript e creare un plug-in JavaScript che possa essere eseguito all'interno di WordPress è più facile che mai.

Spero che il post di oggi ti sia piaciuto. E, come sempre, se in qualsiasi momento rimani bloccato o hai domande, lascia un commento e ti aiuteremo.

Oh e, a proposito, ecco un link al progetto, pronto per essere scaricato e testato se lo desideri. Basta clonare il progetto, npm install tutte le dipendenze, npm run build e provalo!

Immagine in primo piano di Ashim D'Silva su Unsplash.