Costruire blocchi Gutenberg personalizzati: il tutorial per lo sviluppo di blocchi definitivi

Molte persone si lamentano degli ostacoli per iniziare a costruire blocchi e app Gutenberg. La curva di apprendimento è ripida, principalmente a causa della difficoltà di installazione e configurazione dell'ambiente di sviluppo. Inoltre, una solida conoscenza di JavaScript, Node.js, React e Redux sono ingredienti indispensabili per questa ricetta abbastanza complessa.

Il manuale ufficiale dell'editor di blocchi di WordPress fornisce agli sviluppatori un'enorme quantità di informazioni, ma potresti ritrovarti perso in quel mare di dettagli.

E vale la pena ricordare quanto riportato da Matias Ventura, capo architetto del progetto Gutenberg, nella sua intervista a WP Tavern:

Sebbene ci siano persone che possono impararlo rapidamente, è ancora una grande barriera per le persone. Penso che ci siano diversi livelli in questo; la documentazione potrebbe essere un ordine di grandezza migliore sia nell'organizzazione che nella presentazione. Spero che possiamo fare molto di più lì.

Con questo in mente, abbiamo deciso di fornire un tutorial passo dopo passo volto ad aiutare i nostri lettori a iniziare con lo sviluppo del blocco Gutenberg.

Sembra interessante? Immergiamoci!

Prerequisiti per lo sviluppo del blocco di Gutenberg

Per questo tutorial, le uniche competenze richieste sono una buona conoscenza dello sviluppo di plugin per WordPress e almeno una conoscenza di base di HTML, CSS, JavaScript e React.

Sarà un progetto ambizioso? Scommetti che lo sarà!

Non è stato facile trovare il giusto compromesso tra completezza e semplicità o decidere quali argomenti inserire e quali tralasciare.

Si spera che i lettori di livello intermedio e avanzato ci perdoneranno per non aver approfondito alcuni concetti come lo stato di React, il negozio Redux, i componenti di ordine elevato e così via. Questi argomenti richiedono spazio e attenzione aggiuntivi e sono probabilmente troppo avanzati per iniziare lo sviluppo a blocchi (a meno che tu non sia uno sviluppatore React).

Per lo stesso motivo, non tratteremo alcuni degli argomenti più avanzati relativi allo sviluppo dei blocchi di Gutenberg, come i blocchi dinamici e le meta box.

Con le conoscenze che acquisirai entro la fine di questo articolo, sarai in grado di iniziare subito a divertirti e ad essere produttivo.

Una volta che inizierai a costruire blocchi, sarai pronto per migliorare ulteriormente le tue abilità e costruire da solo blocchi Gutenberg ancora più avanzati.

Cos'è un blocco di Gutenberg?

Da quando è stato rilasciato per la prima volta a dicembre 2018, l'editor dei blocchi è stato notevolmente migliorato sotto tutti gli aspetti: API più potenti, un'interfaccia utente più avanzata, una migliore usabilità, un sacco di nuovi blocchi, le prime implementazioni di Full Site Editing e molto altro .

In breve, anche se Gutenberg è ancora in forte sviluppo, ha fatto molta strada e oggi l'editor di blocchi è un candidato a tutti gli effetti come costruttore di pagine e siti affidabile e funzionale.

Dal punto di vista dello sviluppatore, Gutenberg è un'applicazione a pagina singola (SPA) basata su React che consente agli utenti di WordPress di creare, modificare ed eliminare contenuti in WordPress. Tuttavia, questo non dovrebbe farti pensare a una versione migliorata del tradizionale editor di contenuti.

Vogliamo chiarire questo:

In Gutenberg, il contenuto è diviso in blocchi, che sono "mattoni" che gli utenti possono utilizzare per creare post e pagine o i loro interi siti web.

Ma cos'è tecnicamente un blocco?

Ci piace la definizione di WordPress:

"Blocco" è il termine astratto usato per descrivere unità di markup che, composte insieme, formano il contenuto o il layout di una pagina web. L'idea combina i concetti di ciò che in WordPress oggi otteniamo con codici brevi, HTML personalizzato e incorpora la scoperta in un'unica API coerente ed esperienza utente.

Titoli, paragrafi, colonne, immagini, gallerie e tutti gli elementi che compongono l'interfaccia dell'editor, dai pannelli della barra laterale ai controlli dei blocchi della barra degli strumenti, sono componenti di React.

Quindi, quali sono i componenti React? W3Schools fornisce la seguente definizione:

I componenti sono bit di codice indipendenti e riutilizzabili. Hanno lo stesso scopo delle funzioni JavaScript, ma funzionano in isolamento e restituiscono HTML tramite una funzione render() .

Sebbene l'esperienza di editing fornita da Gutenberg sia nuova rispetto al classico editor di WordPress, il modo in cui WordPress memorizza i tuoi contenuti nel database non cambia affatto. Questo perché Gutenberg è un'applicazione che funziona all'interno di WordPress ma non cambia il modo in cui funziona il CMS.

I post (e questo include post, pagine e tipi di post personalizzati) creati con Gutenberg sono ancora archiviati nella tabella wp_posts , esattamente come con l'editor classico.

Ma in un post creato con Gutenberg, troverai ulteriori informazioni nella tabella che rappresentano una differenza fondamentale tra i post creati tramite l'editor classico e Gutenberg.

Queste informazioni sembrano commenti HTML e hanno una funzione specifica: delimitare i blocchi:

I delimitatori di blocco indicano a WordPress quale blocco deve essere visualizzato sullo schermo. Forniscono anche valori per le proprietà del blocco in un oggetto JSON. Questi oggetti di scena determinano il modo in cui il blocco dovrebbe essere visualizzato sullo schermo:

Configurare il tuo ambiente di sviluppo WordPress

La configurazione di un moderno ambiente di sviluppo JavaScript richiede una solida conoscenza di tecnologie avanzate come Webpack, React e JSX, Babel, ESLint, ecc.

intimidito? Non essere! La community di WordPress è già venuta in soccorso fornendo potenti strumenti che ti consentono di evitare un disordinato processo di configurazione manuale.

Per semplificare le cose, in questo articolo non tratteremo il transpiling (con cui tuttavia consigliamo di familiarizzare una volta apprese le basi dello sviluppo a blocchi). Invece, introdurremo due strumenti alternativi che puoi utilizzare per configurare rapidamente e facilmente un moderno ambiente di sviluppo JavaScript in pochi minuti. Sta a te scegliere quello che ritieni più conveniente per il tuo progetto.

La configurazione di un ambiente di sviluppo JavaScript per creare blocchi Gutenberg è un processo in tre fasi:

1. Installa Node.js e npm
2. Impostare l'ambiente di sviluppo
3. Configura il plug-in di blocco

Iniziamo.

1. Installa Node.js e npm

Prima di installare il tuo ambiente di sviluppo e registrare il tuo primo blocco, dovrai installare Node.js e il gestore di pacchetti Node (npm).

Puoi installare Node.js e npm in diversi modi. Ma prima, potresti voler controllare se il software è già installato sulla tua macchina.

Per fare ciò, avvia il terminale ed esegui il seguente comando:

 node -v

Se il risultato è command not found , Node.js non è installato sul tuo computer e puoi procedere con l'installazione.

Per questo articolo, abbiamo scelto l'opzione di installazione più semplice, ovvero Node Installer. Tutto quello che devi fare è scaricare la versione corrispondente al tuo sistema operativo e avviare la procedura guidata di installazione:

Dopo aver installato Node.js, esegui nuovamente il comando node -v nel tuo terminale. Puoi anche eseguire il comando npm -v per confermare di avere il pacchetto npm disponibile.

Ora sei dotato dei seguenti strumenti:

• Il corridore di pacchetti npx Node.js (vedi documenti). Ciò consente di eseguire un comando npm senza prima installarlo.
• Il gestore di pacchetti npm Node.js (vedi documenti). Viene utilizzato per installare dipendenze ed eseguire script.

Il passaggio successivo consiste nell'installare l'ambiente di sviluppo.

2. Configura il tuo ambiente di sviluppo

Una volta che hai le ultime versioni di Node.js e npm sul tuo computer locale, avrai bisogno di un ambiente di sviluppo per WordPress.

Puoi utilizzare un ambiente di sviluppo locale come DevKinsta o utilizzare lo strumento WordPress ufficiale. Diamo un'occhiata a entrambe le opzioni.

Opzione 1: ambiente di sviluppo locale (DevKinsta)

Con pochi clic, puoi installare WordPress localmente utilizzando DevKinsta, il nostro moderno strumento di sviluppo locale di WordPress. Oppure potresti optare per un diverso strumento di sviluppo locale, come MAMP o XAMPP:

Opzione 2: wp-env

Puoi anche optare per lo strumento ufficiale wp-env , che fornisce un ambiente di sviluppo WordPress locale che puoi avviare direttamente dalla riga di comando. Noah Alen lo definisce così:

Gli ambienti WordPress locali ora sono semplici come eseguire un singolo comando. wp-env è uno strumento di configurazione zero per ambienti WordPress locali indolori. Fornisce decisioni sulle opzioni in modo che gli utenti possano avviare rapidamente WordPress senza perdere tempo. In effetti, l'obiettivo è rendere questi ambienti facilmente accessibili a tutti, che tu sia uno sviluppatore, un designer, un manager o chiunque altro.

Se decidi di provarlo, l'installazione wp-env richiede uno sforzo minimo. Basta seguire questi passaggi:

Passaggio 1: conferma l'installazione di Docker e Node.js

Per soddisfare i requisiti tecnici, devi prima avere sia Docker che Node.js installati sul tuo computer. Questo perché wp-env crea un'istanza Docker che esegue un sito Web WordPress. Qualsiasi modifica apportata al codice si riflette immediatamente nell'istanza di WordPress.

Passaggio 2: installa @wordpress/env dalla riga di comando

Con Docker e Node.js in esecuzione sul tuo computer, puoi andare avanti e installare l'ambiente di sviluppo di WordPress.

È possibile installare wp-env a livello globale o locale. Per farlo a livello globale, dovrai eseguire il seguente comando dalla directory dei plugin (ulteriori informazioni nella casella di avviso "Importante" di seguito):

 npm install -g @wordpress/env

Analizziamolo:

• npm install installa il pacchetto.
• -g aggiunto al comando installa il pacchetto specificato a livello globale.
• @wordpress/env è il pacchetto che stai per installare.

Per confermare che wp-env è stato installato correttamente, eseguire il comando seguente:

 wp-env --version

Dovresti vedere la versione corrente wp-env , il che significa che ora puoi avviare l'ambiente usando il seguente comando dalla cartella del tuo plugin:

 wp-env start

Puoi accedere alla dashboard di WordPress utilizzando il seguente indirizzo:

• http://localhost:8888/wp-admin/

Le credenziali predefinite sono le seguenti:

• Nome utente: admin
• Password: password

Configura il tuo plug-in di blocco

Ora hai bisogno di un plug-in per il blocco di base su cui basarti. Ma invece di creare manualmente un plug-in per blocchi di sviluppo con tutti i file e le cartelle necessari, puoi semplicemente eseguire uno strumento di sviluppo che fornisce tutti i file e le configurazioni necessarie per iniziare con lo sviluppo dei blocchi.

Ancora una volta, hai un paio di opzioni tra cui scegliere. Diamo un'occhiata a ciascuno.

Opzione 1: configurazione di un plug-in di blocco con @wordpress/create-block

@wordpress/create-block è lo strumento di configurazione zero ufficiale per la creazione di blocchi Gutenberg:

Crea blocco è un modo ufficialmente supportato per creare blocchi per la registrazione di un blocco per un plug-in WordPress. Offre una configurazione di build moderna senza configurazione. Genera codice PHP, JS, CSS e tutto il necessario per avviare il progetto.

È in gran parte ispirato da create-react-app. Grandi complimenti a @gaearon, all'intero team di Facebook e alla community di React.

Una volta che il tuo ambiente locale è attivo e funzionante, puoi impostare un blocco di avvio semplicemente eseguendo il npx @wordpress/create-block e fornirà tutti i file e le cartelle necessari per creare l'impalcatura del plug-in e registrare un nuovo blocco .

Eseguiamo un test per vedere come funziona.

Dal tuo strumento della riga di comando, vai alla directory /wp-content/plugins/ ed esegui il comando seguente:

 npx @wordpress/create-block my-first-block

Quando ti viene chiesto di confermare, inserisci y per procedere:

Il processo richiede pochi istanti. Al termine, dovresti ricevere la seguente risposta:

E questo è tutto!

Ora avvia il tuo ambiente di sviluppo WordPress e vai alla schermata Plugin nella dashboard di WordPress. Un nuovo plug-in denominato "Il mio primo blocco" dovrebbe essere stato aggiunto all'elenco dei plug-in:

Attiva il plug-in se necessario, crea un nuovo post sul blog, scorri verso il basso l'inseritore di blocchi fino alla sezione Widget e seleziona il tuo nuovo blocco:

Ora torna al terminale e cambia la directory corrente in my-first-block :

 cd my-first-block

Quindi esegui il seguente comando:

 npm start

Ciò consente di eseguire il plug-in in modalità di sviluppo. Per creare il codice di produzione, dovresti usare il seguente comando:

 npm run build

Opzione 2: configurazione di un plug-in di blocco con create-guten-block

create-guten-block è uno strumento di sviluppo di terze parti per la creazione di blocchi Gutenberg:

create-guten-block è zero configuration dev-toolkit (#0CJS) per sviluppare blocchi WordPress Gutenberg in pochi minuti senza configurare React, webpack, ES6/7/8/Next, ESLint, Babel, ecc.

Proprio come lo strumento ufficiale create-block , create-guten-block si basa su create-react-app e può aiutarti a generare il tuo primo plug-in di blocco senza problemi.

Il toolkit fornisce tutto il necessario per creare un moderno plugin per WordPress, inclusi i seguenti:

• Supporto per la sintassi React, JSX ed ES6.
• processo di sviluppo/produzione di webpack dietro le quinte.
• Extra linguistici oltre ES6 come l'operatore di diffusione degli oggetti.
• CSS con prefisso automatico, quindi non hai bisogno di -webkit o altri prefissi.
• Uno script di compilazione per raggruppare JS, CSS e immagini per la produzione con le mappe dei sorgenti.
• Aggiornamenti senza problemi per gli strumenti di cui sopra con una singola dipendenza cgb-scripts.

Nota il seguente avvertimento:

Il compromesso è che questi strumenti sono preconfigurati per funzionare in un modo specifico. Se il tuo progetto ha bisogno di una maggiore personalizzazione, puoi "espellerlo" e personalizzarlo, ma poi dovrai mantenere questa configurazione.

Una volta che hai un sito Web WordPress locale a portata di mano, avvia lo strumento della riga di comando, vai alla cartella /wp-content/plugins della tua installazione ed esegui il comando seguente:

 npx create-guten-block my-first-block

Dovrai attendere un minuto o due mentre viene creata la struttura del progetto e scaricate le dipendenze:

Al termine del processo, dovresti visualizzare la seguente schermata:

Questa immagine successiva mostra la struttura del progetto con il terminale in esecuzione in Visual Studio Code:

Ora torna alla dashboard di WordPress. Un nuovo elemento dovrebbe essere elencato nella schermata Plugin: è il plug-in del mio primo blocco :

Attiva il plugin e torna al terminale. Cambia la directory corrente in my-first-block , quindi esegui npm start :

 cd my-first-block npm start

Dovresti ottenere la seguente risposta:

Ancora una volta, questo ti consente di eseguire il plug-in in modalità di sviluppo. Per creare il codice di produzione, dovresti usare:

 npm run build

Attiva il plugin e crea un nuovo post o pagina, quindi sfoglia i tuoi blocchi e seleziona il tuo nuovissimo blocco Gutenberg:

Per una panoramica più approfondita o in caso di errori, fare riferimento alla documentazione fornita da Ahmad Awais.

Una procedura dettagliata dell'impalcatura del blocco di avviamento

Qualunque dei due strumenti di sviluppo - create-block o create-guten-block - tu scelga, ora hai un'impalcatura a blocchi che puoi utilizzare come punto di partenza per creare un plug-in di blocchi.

Ma cos'è esattamente un ponteggio a blocchi?

Block scaffolding è un termine abbreviato che descrive la struttura di directory di supporto necessaria affinché WordPress riconosca un blocco. In genere quella directory include file come index.php , index.js , style.css e altri, che a loro volta contengono chiamate come register_block_type .

Abbiamo optato per lo strumento di sviluppo ufficiale Create Block , poiché è utilizzato nel Block Editor Handbook. Ma anche se decidessi di utilizzare uno strumento di terze parti come create-guten-block , la tua esperienza non sarà troppo diversa.

Detto questo, immergiamoci nello strumento create-block .

Uno sguardo più da vicino al Crea Block Dev-Tool

Come accennato in precedenza, Crea blocco è lo strumento da riga di comando ufficiale per creare blocchi Gutenberg. L'esecuzione @wordpress/create-block nel terminale genera i file PHP, JS e SCSS e il codice necessari per registrare un nuovo tipo di blocco:

 npx @wordpress/create-block [options] [slug]

• [slug] (opzionale): utilizzato per assegnare lo slug del blocco e installare il plug-in
• [options] (opzionale) — opzioni disponibili

Per impostazione predefinita, viene assegnato un modello ESNext. Ciò significa che otterrai la prossima versione di JavaScript, con l'aggiunta della sintassi JSX.

Se ometti il ​​nome del blocco, il comando viene eseguito in modalità interattiva, consentendoti di personalizzare diverse opzioni prima di generare i file:

 npx @wordpress/create-block

L'immagine seguente mostra la struttura del file di un plug-in di blocco creato con lo strumento ufficiale Crea blocco:

Detto questo, esaminiamo i file e le cartelle principali del nostro nuovo plug-in di blocco.

Il file plug-in

Con il file del plugin principale registri il blocco sul server:

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * Requires PHP: 7.0 * Version: 0.1.0 * Author: The WordPress Contributors * License: GPL-2.0-or-later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

La funzione register_block_type registra un tipo di blocco sul server utilizzando i metadati archiviati nel file block.json .

La funzione accetta due parametri:

• Il nome del tipo di blocco incluso lo spazio dei nomi o un percorso della cartella in cui si trova il file block.json o un oggetto WP_Block_Type completo
• Una matrice di argomenti di tipo blocco

Nel codice sopra, l'argomento del tipo di blocco è fornito dalla costante magica __DIR__ . Ciò significa che il file block.json risiede nella stessa cartella del file del plug-in.

Il file package.json

Il file package.json definisce le proprietà JavaScript e gli script per il tuo progetto. Qui è dove puoi installare le dipendenze del tuo progetto.

Per capire meglio a cosa serve questo file, aprilo con il tuo editor di codice preferito:

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

La proprietà scripts è un dizionario contenente comandi che vengono eseguiti in vari momenti del ciclo di vita di un pacchetto utilizzando npm run [cmd] .

In questo articolo utilizzeremo i seguenti comandi:

• npm run build : crea una build di produzione (compressa).
• npm run start — crea una build di sviluppo (non compressa).

dependencies e devDependencies sono due oggetti che associano un nome di pacchetto a una versione. dependencies sono richieste in produzione, mentre devDependences sono necessarie solo per lo sviluppo locale (leggi di più).

L'unica dipendenza dev predefinita è il pacchetto @wordpress/scripts , definito come "una raccolta di script riutilizzabili su misura per lo sviluppo di WordPress".

Il file block.json

A partire da WordPress 5.8, il file di metadati block.json è il modo canonico per registrare i tipi di blocco.

Avere un file block.json offre numerosi vantaggi, tra cui prestazioni migliorate e una migliore visibilità nella directory dei plugin di WordPress:

Dal punto di vista delle prestazioni, quando i temi supportano il caricamento lento delle risorse, i blocchi registrati con block.json avranno l'accodamento delle risorse ottimizzato immediatamente. Gli asset CSS e JavaScript frontend elencati nelle proprietà dello style o script verranno accodati solo quando il blocco è presente nella pagina, con conseguente riduzione delle dimensioni della pagina.

L'esecuzione del comando @wordpress/create-block genera il seguente file block.json :

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Ecco l'elenco completo delle proprietà predefinite:

• apiVersion — la versione dell'API utilizzata dal blocco (la versione corrente è 2)
• name — un identificatore univoco per un blocco che include uno spazio dei nomi
• version — la versione corrente di un blocco
• title — un titolo visualizzato per un blocco
• category — una categoria di blocco
• icon — uno slug Dashicon o un'icona SVG personalizzata
• description — una breve descrizione visibile nell'ispettore blocchi
• supports : un insieme di opzioni per controllare le funzioni utilizzate nell'editor
• textdomain — il plugin text-domain
• editorScript — definizione dello script dell'editor
• editorStyle — definizione dello stile dell'editor
• style : fornisce stili alternativi per un blocco

Oltre alle proprietà sopra elencate, puoi (e probabilmente lo farai) definire un oggetto attributes che fornisce informazioni sui dati memorizzati dal tuo blocco. Nel tuo block.json puoi impostare un numero qualsiasi di attributi nelle coppie chiave/valore , dove la chiave è il nome dell'attributo e il valore è la definizione dell'attributo.

Dai un'occhiata al seguente esempio di definizioni di attributi:

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

Approfondiremo il file block.json più avanti nell'articolo, ma potresti anche voler controllare il Manuale dell'editor di blocchi per informazioni più dettagliate sui metadati e gli attributi block.json .

La cartella src

La cartella src è dove avviene lo sviluppo. In quella cartella troverai i seguenti file:

• index.js
• edit.js
• save.js
• editor.scss
• style.scss

index.js

Il file index.js è il tuo punto di partenza. Qui importerai le dipendenze e registrerai il tipo di blocco sul client:

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

La prima istruzione importa la funzione registerBlockType dal pacchetto @wordpress/blocks . Le seguenti istruzioni import importano il foglio di stile insieme alle funzioni di Edit e save .

La funzione registerBlockType registra il componente sul client. La funzione accetta due parametri: un nome del blocco namespace/block-name (lo stesso registrato sul server) e un oggetto di configurazione del blocco.

La funzione Edit fornisce l'interfaccia del blocco resa nell'editor dei blocchi, mentre la funzione save fornisce la struttura che verrà serializzata e salvata nel database (leggi di più).

edit.js

edit.js è dove creerai l'interfaccia di amministrazione del blocco:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Innanzitutto, importa la funzione __ dal pacchetto @wordpress/i18n (questo pacchetto contiene una versione JavaScript delle funzioni di traduzione), l'hook useBlockProps React e il file editor.scss .

Successivamente, esporta il componente React (leggi di più sulle istruzioni di importazione ed esportazione).

save.js

Il file save.js è dove costruiamo la struttura a blocchi da salvare nel database:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

editor.scss e style.scss

Oltre agli script, due file SASS risiedono nelle cartelle src . Il file editor.scss contiene gli stili applicati al blocco nel contesto dell'editor, mentre il file style.scss contiene gli stili del blocco per la visualizzazione nel frontend. Approfondiremo questi file nella seconda parte di questa guida.

I node_modules e le cartelle di build

La cartella node_modules contiene i moduli del nodo e le relative dipendenze. Non ci addentreremo più a fondo nei pacchetti di nodi poiché esula dallo scopo di questo articolo, ma puoi leggere di più in questo articolo su dove npm installa i pacchetti.

La cartella build contiene i file JS e CSS risultanti dal processo di build. Puoi approfondire il processo di compilazione nella sintassi ESNext e nelle guide JavaScript Build Setup.

Il progetto: costruire il tuo primo blocco Gutenberg

È ora di sporcarci le mani. Questa sezione ti insegnerà come creare un plug-in che fornisce un blocco CTA chiamato Affiliate Block.

Il blocco sarà composto da due colonne, con un'immagine a sinistra e un paragrafo di testo a destra. Sotto il testo verrà posizionato un pulsante con un collegamento personalizzabile:

Questo è solo un semplice esempio, ma ci permette di coprire le basi dello sviluppo dei blocchi di Gutenberg. Dopo aver acquisito una chiara comprensione delle basi, puoi procedere e creare blocchi Gutenberg sempre più complessi con l'aiuto del Block Editor Handbook e di qualsiasi altra delle vaste risorse disponibili.

Supponendo che tu abbia l'ultima versione di WordPress in esecuzione nel tuo ambiente di sviluppo locale, ecco cosa imparerai da qui in poi:

• Come configurare il plug-in Starter Block
• block.json al lavoro
• Utilizzo di componenti integrati: il componente RichText
• Aggiunta di controlli alla barra degli strumenti del blocco
• Personalizzazione della barra laterale delle impostazioni dei blocchi
• Aggiunta e personalizzazione di un collegamento esterno
• Aggiunta di più stili di blocco
• Nidificazione di blocchi con il componente InnerBlocks
• Ulteriori miglioramenti

Pronto... pronto... via!

Come configurare il plug-in Starter Block

Avvia il tuo strumento da riga di comando e vai alla cartella /wp-content/plugins :

Ora, esegui il seguente comando:

 npx @wordpress/create-block

Questo comando genera i file PHP, SCSS e JS per la registrazione di un blocco in modalità interattiva, consentendoti di aggiungere facilmente i dati necessari per il tuo blocco. Per il nostro esempio utilizzeremo i seguenti dettagli:

• Block slug : blocco mio-affiliato
• Spazio dei nomi interno : my-affiliate-plugin
• Titolo di visualizzazione del blocco : Blocco affiliato
• Breve descrizione del blocco : un blocco di esempio per i lettori di Kinsta
• Dashicon : soldi
• Nome della categoria : design
• Autore del plugin : il tuo nome
• Licenza : –
• Link al testo della licenza : –
• Versione corrente del plugin : 0.1.0

L'installazione del plugin e di tutte le dipendenze richiede un paio di minuti. Al termine del processo, vedrai la seguente risposta:

Ora, esegui il seguente comando dalla cartella /wp-content/plugins :

 cd my-affiliate-block

Infine, dalla cartella del tuo plugin ( my-affiliate-block nel nostro esempio), puoi iniziare lo sviluppo con:

 npm start

Ora apri la schermata Plugin per trovare e attivare il plugin Affiliate Block :

Crea un nuovo post, apri l'inseritore di blocchi e scorri verso il basso fino alla categoria Design . Fai clic per aggiungere il Blocco affiliato:

block.json al lavoro

Come accennato in precedenza, la registrazione del blocco lato server avviene nel file .php principale. Tuttavia, non definiremo le impostazioni nel file .php . Useremo invece il file block.json .

Quindi, apri nuovamente block.json e dai un'occhiata più da vicino alle impostazioni predefinite:

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Script e stili

editorScript , editorStyle e le proprietà style forniscono i percorsi relativi agli script e agli stili front-end e back-end.

Non è necessario registrare manualmente gli script e gli stili definiti qui perché questi vengono automaticamente registrati e accodati da WordPress. Per dimostrarlo, avvia l'ispettore del browser e apri la scheda Rete :

Come puoi vedere dall'immagine sopra, il nostro script index.js che risiede nella cartella build è stato regolarmente accodato senza dover aggiungere alcun codice PHP .

Etichette dell'interfaccia utente

Le proprietà del title e della description forniscono le etichette necessarie per identificare il blocco nell'editor:

Parole chiave

Come accennato in precedenza, puoi configurare accuratamente le impostazioni del blocco utilizzando proprietà e attributi. Ad esempio, puoi aggiungere una o più keywords per aiutare gli utenti a cercare i blocchi:

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

Localizzazione

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Questo codice genera un blocco statico con testo semplice e non modificabile. Ma possiamo cambiare le cose facilmente:

Per rendere modificabile il testo dovrai sostituire il tag <p> corrente con un componente che renda modificabile il contenuto di input. Per questo, Gutenberg fornisce il componente RichText integrato.

L'aggiunta di un componente integrato al blocco è un processo in 5 fasi:

1. Importa i componenti richiesti da un pacchetto WordPress
2. Includi gli elementi corrispondenti nel tuo codice JSX
3. Definisci gli attributi necessari nel file block.json
4. Definisci gestori di eventi
5. Salvare i dati

Passaggio 1: importa i componenti richiesti da un pacchetto WordPress

Ora apri il file edit.js e modifica la seguente istruzione di import :

 import { useBlockProps } from '@wordpress/block-editor';

…a:

 import { useBlockProps, RichText } from '@wordpress/block-editor';

In questo modo importi la funzione useBlockProps e il componente RichText dal pacchetto @wordpress/block-editor .

useBlockProps

L'hook useBlockProps React contrassegna l'elemento wrapper del blocco:

Quando si utilizza l'API versione 2, è necessario utilizzare il nuovo hook useBlockProps nella funzione di edit del blocco per contrassegnare l'elemento wrapper del blocco. L'hook inserirà gli attributi e i gestori di eventi necessari per abilitare il comportamento del blocco. Qualsiasi attributo che desideri passare all'elemento block deve essere passato tramite useBlockProps e il valore restituito deve essere distribuito sull'elemento.

Per dirla semplicemente, useBlockProps assegna automaticamente attributi e classi all'elemento wrapper (l'elemento p nel nostro esempio):

Se rimuovi useBlockProps dall'elemento wrapper, avresti una semplice stringa di testo senza accesso alla funzionalità e allo stile del blocco:

Come spiegheremo più avanti, puoi anche passare a useBlockProps un oggetto di proprietà per personalizzare l'output.

RichText

Il componente RichText fornisce un input modificabile dal contenuto, consentendo agli utenti di modificare e formattare il contenuto.

Troverai il componente documentato su GitHub in gutenberg/packages/block-editor/src/components/rich-text/README.md.

Passaggio 2: includi gli elementi corrispondenti nel codice JSX

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

Commentiamo il codice riga per riga:

• tagName — il nome del tag dell'elemento HTML modificabile
• onChange — funzione chiamata quando il contenuto dell'elemento cambia
• allowedFormats — una matrice di formati consentiti. Per impostazione predefinita, tutti i formati sono consentiti
• value — la stringa HTML da rendere modificabile
• placeholder : testo segnaposto da mostrare quando l'elemento è vuoto

Passaggio 3: definire gli attributi necessari nel file block.json

Gli attributi forniscono informazioni sui dati archiviati da un blocco, come contenuto avanzato, colore di sfondo, URL, ecc.

È possibile impostare un numero arbitrario di attributi all'interno di un oggetto attributes in coppie chiave/valore, dove la chiave è il nome dell'attributo e il valore è la definizione dell'attributo.

Ora apri il file block.json e aggiungi i seguenti attributes prop:

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

L'attributo content permette di memorizzare il testo digitato dall'utente nel campo modificabile:

• type indica il tipo di dati archiviati dall'attributo. Il tipo è obbligatorio a meno che non si definisca una proprietà enum .
• source definisce come il valore dell'attributo viene estratto dal contenuto del post. Nel nostro esempio, è il contenuto HTML. Nota che se non fornisci una proprietà di origine, i dati vengono archiviati nel delimitatore di blocchi (leggi di più).
• selector è un tag HTML o qualsiasi altro selettore, come il nome di una classe o un attributo id.

Passeremo alla funzione Edit un oggetto di proprietà. Quindi, torna al file edit.js e apporta la seguente modifica:

 export default function Edit( { attributes, setAttributes } ) { ... }

Passaggio 4: definire i gestori di eventi

L'elemento RichText ha un attributo onChange , che fornisce una funzione da chiamare quando il contenuto dell'elemento cambia.

Definiamo quella funzione e vediamo l'intero script edit.js :

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

Ora salva il file ed esegui npm run start nella finestra del tuo terminale. Quindi, torna alla dashboard di WordPress, crea un nuovo post o una nuova pagina e aggiungi il tuo blocco di affiliazione:

Aggiungi del testo e passa alla vista Codice. Ecco come dovrebbe essere il tuo codice:

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Se ora salvi la pagina e controlli il risultato del frontend, potresti essere un po' deluso perché le tue modifiche non influiscono sul sito. Questo perché devi modificare il file save.js per memorizzare l'input dell'utente nel database quando il post viene salvato.

Passaggio 5: salva i dati

Ora apri il file save.js e modifica lo script come segue:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

Questo è quello che stiamo facendo qui:

• Importa il componente RichText dal pacchetto block-editor .
• Passa diverse proprietà tramite un argomento oggetto alla funzione di save (in questo esempio, stiamo solo passando la proprietà degli attributes )
• Restituisce il contenuto del componente RichText

Puoi leggere di più sul componente RichText nel Block Editor Handbook e trovare l'elenco completo degli oggetti di scena su Github.

Ora facciamo un ulteriore passo avanti. Nella prossima sezione imparerai come aggiungere controlli alla barra degli strumenti del blocco.

Aggiunta di controlli alla barra degli strumenti del blocco

La barra degli strumenti del blocco contiene una serie di controlli che consentono agli utenti di manipolare parti del contenuto del blocco. Per ogni controllo della barra degli strumenti, troverai un componente:

Ad esempio, puoi aggiungere un controllo di allineamento del testo per il tuo blocco. Tutto quello che devi fare è importare due componenti dal pacchetto @wordpress/block-editor .

Seguiremo gli stessi passaggi dell'esempio precedente:

1. Importa i componenti richiesti dai pacchetti di WordPress
2. Includi gli elementi corrispondenti nel tuo codice JSX
3. Definisci gli attributi necessari nel file block.json
4. Definisci gestori di eventi
5. Salvare i dati

Passaggio 1: importa BlockControls e AlignmentControl Components da @wordpress/block-editor

Per aggiungere un controllo di allineamento alla barra degli strumenti del blocco, sono necessari due componenti:

• BlockControls rendering di una barra degli strumenti dinamica di controlli (non documentata).
• AlignmentControl rende un menu a discesa che mostra le opzioni di allineamento per il blocco selezionato (leggi di più)

Apri il file edit.js e modifica la dichiarazione di import come mostrato di seguito:

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

Passaggio 2: aggiungi BlockControls e AlignmentControl Elements

Vai alla funzione Edit e inserisci l'elemento <BlockControls /> allo stesso livello di <RichText /> . Quindi aggiungi e <AlignmentControl /> all'interno di <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Nel codice sopra, <> e </> sono la sintassi breve per dichiarare i frammenti di React, che è il modo in cui restituiamo più elementi in React.

In questo esempio, AlignmentControl ha due attributi:

• value fornisce il valore corrente per l'elemento
• onChange fornisce un gestore di eventi da eseguire quando il valore cambia

Abbiamo anche definito attributi aggiuntivi per l'elemento RichText (controlla l'elenco completo degli attributi con esempi)

Passaggio 3: definisci l'attributo align in block.json

Ora vai al file block.json e aggiungi l'attributo align :

 "align": { "type": "string", "default": "none" }

Torna al terminale, interrompi il processo corrente con ^C e riavvia lo script con npm run start . Quindi torna all'editor dei blocchi, aggiorna la pagina e seleziona il blocco. Dovresti vedere la barra degli strumenti del blocco con un controllo di allineamento:

Ora, se provi a formattare il contenuto del blocco utilizzando i nuovi controlli di allineamento, vedrai che non succede nulla. Questo perché non abbiamo ancora definito il gestore dell'evento.

Passaggio 4: definire i gestori di eventi

Ora definisci onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

Se newAlign è undefined , impostiamo newAlign su none . Altrimenti, utilizziamo newAlign .

Il nostro script edit.js dovrebbe essere completo (per ora):

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Ora puoi tornare all'editor e allineare il contenuto del blocco.

È necessario modificare la funzione di salvataggio per memorizzare il contenuto del blocco e gli attributi nel database.

Passaggio 5: salva i dati

Apri save.js e modifica la funzione di save come segue:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

Infine, per rendere più leggibile il codice, è possibile estrarre le singole proprietà dall'oggetto attribute utilizzando la sintassi dell'assegnazione di destrutturazione:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

Salvare il file, riavviare il processo e tornare all'editor in modalità Editor codice. Il codice dovrebbe assomigliare a questo:

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

E questo è tutto! Hai appena aggiunto un controllo di allineamento alla barra degli strumenti del blocco

Puoi leggere ulteriori informazioni sui controlli della barra degli strumenti dei blocchi nel Manuale dell'editor blocchi.

Personalizzazione della barra laterale delle impostazioni dei blocchi

Puoi anche aggiungere controlli alla barra laterale delle impostazioni del blocco (o persino creare una nuova barra laterale per la tua applicazione).

L'API fornisce un componente InspectorControls per questo.

Il Manuale dell'editor blocchi spiega come utilizzare la barra laterale delle impostazioni:

La barra laterale delle impostazioni viene utilizzata per visualizzare le impostazioni meno utilizzate o le impostazioni che richiedono più spazio sullo schermo. La barra laterale delle impostazioni deve essere utilizzata solo per le impostazioni a livello di blocco .

Se hai impostazioni che interessano solo il contenuto selezionato all'interno di un blocco (esempio: l'impostazione "grassetto" per il testo selezionato all'interno di un paragrafo): non posizionarlo all'interno della barra laterale Impostazioni. La barra laterale delle impostazioni viene visualizzata anche durante la modifica di un blocco in modalità HTML, quindi dovrebbe contenere solo impostazioni a livello di blocco.

Ancora:

1. Importa i componenti richiesti dai pacchetti di WordPress
2. Includi gli elementi corrispondenti nel tuo codice JSX
3. Definisci gli attributi necessari nel file block.json
4. Definisci gestori di eventi
5. Salvare i dati

Passaggio 1. Importa InspectorControls e componenti PanelColorSettings da @wordpress/block-editor

Puoi aggiungere diversi controlli per consentire agli utenti di personalizzare aspetti specifici del blocco. Ad esempio, puoi fornire un pannello di controllo del colore. Per fare ciò, dovrai importare i componenti InspectorControls e PanelColorSettings dal modulo block-editor :

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

Passaggio 2: includi gli elementi corrispondenti nel codice JSX

Ora puoi aggiungere gli elementi corrispondenti al JSX restituito dalla funzione Edit :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

Nota che abbiamo anche aggiornato l'attributo style dell'elemento RichText :

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

Passaggio 3: definisci gli attributi necessari in block.json

Ora definisci gli attributi backgroundColor e textColor nel file block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

Passaggio 4: definire i gestori di eventi

Ora devi definire due funzioni per aggiornare backgroundColor e textColor su input dell'utente:

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

Passaggio 5: salva i dati

Un ultimo passaggio: apri il file save.js e modifica lo script come segue:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

Ora ferma il processo (^C) ed esegui npm run start nuovo. Aggiorna la pagina, elimina qualsiasi istanza del tuo blocco e aggiungila di nuovo al tuo post:

Apporta le modifiche, salva il post e visualizzalo nel frontend. Le modifiche apportate nell'editor dei blocchi dovrebbero essere riportate sul sito principale.

Aggiunta e personalizzazione di un collegamento esterno

In questa sezione, aggiungerai nuovi componenti al tuo tipo di blocco:

• Un componente ExternalLink che consente agli utenti di aggiungere un collegamento personalizzabile al blocco di affiliazione
• Diversi controlli della barra laterale che consentono agli utenti di personalizzare le impostazioni dei collegamenti

Passaggio 1. Importa i componenti da @wordpress/components

Ora devi importare diversi componenti da @wordpress/components . Apri il tuo file edit.js e aggiungi la seguente dichiarazione di import :

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• PanelBody aggiunge un contenitore comprimibile alla barra laterale Impostazioni.
• PaneRow produce un contenitore generico per i controlli della barra laterale.
• TextControl fornisce un controllo di input di testo.
• ToggleControl fornisce un interruttore che consente agli utenti di abilitare/disabilitare un'opzione specifica
• ExternalLink è un semplice componente per aggiungere un collegamento esterno.

Passaggio 2. Includi gli elementi corrispondenti nel codice JSX

Per prima cosa aggiungerai l'elemento ExternalLink allo stesso livello di RichText in un contenitore div :

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

Il componente ExternalLink non è documentato, quindi abbiamo fatto riferimento al componente stesso per ottenere l'elenco degli attributi disponibili. Qui stiamo usando gli attributi href , className e rel .

Per impostazione predefinita, il valore dell'attributo rel è impostato su noopener noreferrer . Il nostro codice aggiungerà la parola chiave nofollow all'attributo rel del tag risultante quando a controllo toggle è attivo .

Ora puoi aggiungere le impostazioni dei link alla barra laterale dei blocchi.

Innanzitutto, aggiungerai un elemento PanelBody all'interno di InspectorControls allo stesso livello di PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

Ecco cosa stiamo facendo con questo:

1. L'attributo title fornisce il titolo del pannello.
2. initialOpen imposta se il pannello è inizialmente aperto o meno.

Successivamente, aggiungeremo due elementi PanelRow all'interno PanelBody e un elemento TextControl all'interno di ogni PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

Il codice sopra ora dovrebbe apparire piuttosto semplice. I due controlli di testo consentono agli utenti di impostare l'etichetta e l'URL del collegamento.

Aggiungeremo anche un PanelRow aggiuntivo con un ToggleControl per attivare/disattivare un'opzione specifica, ad esempio se includere o meno un attributo:

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

Passaggio 3: definisci gli attributi necessari in block.json

Ora definisci gli attributi affiliateLink , linkLabel e hasLinkNofollow nel file block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

Nient'altro da aggiungere qui! Passiamo alla definizione delle funzioni di gestione degli eventi.

Passaggio 4: definire i gestori di eventi

Torna al file edit.js e aggiungi le seguenti funzioni:

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

Queste funzioni aggiornano i valori degli attributi corrispondenti sull'input dell'utente.

Passaggio 5: salva i dati

Infine, dobbiamo aggiornare la funzione di save in save.js :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

Nota che qui abbiamo usato a elemento regolare invece di ExternalLink :

Ora salva i dati e riavvia il tuo ambiente.

Aggiunta di più stili di blocco

In una sezione precedente, hai appreso come aggiungere un controllo della barra degli strumenti del blocco che consente agli utenti di allineare l'input dell'utente. Possiamo aggiungere più controlli di stile alla barra degli strumenti del blocco, ma possiamo anche fornire una serie di stili di blocco predefiniti tra cui l'utente può scegliere con un solo clic.

A questo scopo, utilizzeremo una funzione utile dell'API Block: Block Styles.

Tutto quello che devi fare è definire la proprietà degli styles block.json e dichiarare gli stili corrispondenti nei tuoi fogli di stile.

Ad esempio, puoi aggiungere la seguente matrice di stili:

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

Con questo, hai appena aggiunto uno stile predefinito e uno stile aggiuntivo chiamato border . Ora torna all'editor dei blocchi:

Gli stili saranno disponibili per l'utente facendo clic sul selettore di blocchi e quindi cercando il pannello Stili nella barra laterale Impostazioni blocco .

Seleziona uno stile e controlla le classi applicate all'elemento p . Fare clic con il pulsante destro del mouse sul blocco e Ispeziona . È stata aggiunta una nuova classe con un nome strutturato come segue:

 is-style-{style-name}

Se hai selezionato lo stile "Border", una classe is-style-border verrà aggiunta all'elemento p . Se hai selezionato lo stile "Predefinito", verrà invece aggiunta una classe is-style-default .

Ora devi solo dichiarare le proprietà CSS. Apri il file editor.scss e sostituisci gli stili correnti con i seguenti:

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Ora puoi fare lo stesso con style.scss :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Arresta il processo (^C) ed esegui npm run start nuovo.

E questo è tutto! Aggiorna la pagina e divertiti con i tuoi nuovi stili di blocco:

Nidificazione di blocchi di Gutenberg con il componente InnerBlocks

Sebbene completamente funzionante, il nostro Blocco affiliato non è ancora molto interessante. Per renderlo più coinvolgente per il pubblico, potremmo aggiungere un'immagine.

Questo potrebbe aggiungere un livello di complessità al nostro blocco, ma fortunatamente non è necessario reinventare la ruota perché Gutenberg fornisce un componente specifico che puoi utilizzare per creare una struttura di blocchi nidificati.

Il componente InnerBlocks è definito come segue:

InnerBlocks esporta una coppia di componenti che possono essere utilizzati nelle implementazioni di blocchi per abilitare il contenuto di blocchi nidificati.

Innanzitutto, dovrai creare un nuovo file .js nella cartella src . Nel nostro esempio, chiameremo questo file container.js .

Ora dovrai importare la nuova risorsa nel file index.js :

 import './container';

Torna a container.js e importa i componenti necessari:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

Il passo successivo è definire un modello che fornisca la struttura all'interno della quale verranno posizionati i blocchi. Nell'esempio seguente, definiamo un modello composto da due colonne contenenti un blocco immagine principale e il nostro blocco di affiliazione personalizzato:

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

Il modello è strutturato come un array di blockTypes (nome del blocco e attributi facoltativi).

Nel codice sopra, abbiamo utilizzato diversi attributi per configurare i blocchi Colonne e Colonne. In particolare, l'attributo templateLock: 'all' blocca i blocchi di colonne in modo che l'utente non aggiunga, riordini o elimini blocchi esistenti. templateLock può assumere uno dei seguenti valori:

• all — InnerBlocks è bloccato e non è possibile aggiungere, riordinare o rimuovere blocchi.
• insert — I blocchi possono essere solo riordinati o rimossi.
• false — Il modello non è bloccato.

Il modello viene quindi assegnato all'elemento InnerBlocks :

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

Per prevenire qualsiasi problema di compatibilità, abbiamo anche aggiunto un attributo templateLock al componente InnerBlocks (vedi anche problema n. 17262 e pull n. 26128).

Ecco il nostro file container.js finale:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

Ulteriori miglioramenti

Il nostro blocco è perfettamente funzionante, ma potremmo migliorarlo un po' con alcune piccole modifiche.

Abbiamo assegnato l'attributo backgroundColor al paragrafo generato dal componente RichText . Tuttavia, potremmo preferire assegnare il colore di sfondo al contenitore div :

Quindi, cambia il file edit.js e save.js div s come segue:

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

Ciò consentirà all'utente di modificare lo sfondo dell'intero blocco.

D'altra parte, una modifica più rilevante riguarda il metodo useBlockProps . Nel codice originale, abbiamo definito la costante blockProps come segue:

 const blockProps = useBlockProps();

Ma possiamo usare useBlockProps in modo più efficace passando un insieme di proprietà. Ad esempio, possiamo importare i nomi delle classnames dal classnames nomi delle classi e impostare il nome della classe wrapper di conseguenza.

Nell'esempio seguente, assegniamo un nome di classe in base al valore dell'attributo align ( edit.js ):

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

Faremo la stessa modifica nel file save.js :

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

E questo è un involucro! È ora possibile eseguire la build per la produzione.

Sommario

Ed eccoci alla fine di questo incredibile viaggio! Abbiamo iniziato con la configurazione dell'ambiente di sviluppo e abbiamo finito per creare un tipo di blocco completo.

Come accennato nell'introduzione, una solida conoscenza di Node.js, Webpack, Babel e React è essenziale per creare blocchi Gutenberg avanzati e posizionarsi sul mercato come sviluppatore Gutenberg professionista.

Tuttavia, non è necessario aver stabilito l'esperienza React per iniziare a divertirti con lo sviluppo dei blocchi. Lo sviluppo dei blocchi potrebbe darti motivazione e obiettivi per acquisire competenze sempre più ampie nelle tecnologie alla base dei blocchi Gutenberg.

Questa guida, quindi, è lungi dall'essere completa. È semplicemente un'introduzione a un'ampia varietà di argomenti che ti aiuteranno a iniziare a costruire i tuoi primissimi blocchi Gutenberg.

Per questo motivo ti consigliamo di approfondire le tue conoscenze leggendo attentamente la documentazione e le guide online. Tra le tante risorse disponibili, ti consigliamo quanto segue:

• Tutorial ufficiale per creare un blocco per principianti
• Tutorial ufficiale sui blocchi per sviluppatori intermedi
• Blocchi dinamici
• Scatole Meta
• Creazione di una barra laterale per il tuo plugin

Se stai appena iniziando con lo sviluppo di WordPress, potresti voler comprendere i concetti di base dello sviluppo del frontend. Ecco un rapido elenco di risorse che possono aiutarti a iniziare:

• Come installare WordPress in locale (ebook gratuito)
• Il vero valore dell'hosting WordPress gestito (ebook gratuito)
• Cos'è JavaScript?
• HTML vs HTML5
• Come modificare CSS in WordPress
• Che cos'è PHP?
• Il Bootcamp di WordPress Hooks: come utilizzare azioni, filtri e hook personalizzati

E ricorda che il codice completo degli esempi di questa guida è disponibile su Gist.

Ora tocca a te: hai sviluppato dei blocchi Gutenberg? Quali sono le principali difficoltà che hai riscontrato finora? Facci sapere la tua esperienza nei commenti!