Share
Il nuovo editor WordPress (nome in codice Gutenberg) è previsto per il rilascio nella versione 5.0. Ora è il momento perfetto per fare i conti con esso prima che arrivi al nucleo di WordPress. In questa serie, ti sto mostrando come lavorare con l'API Block e creare blocchi di contenuti molto personali che puoi utilizzare per creare post e pagine.
Nel post precedente, abbiamo visto come usare il creare-Guten-block toolkit per creare un plugin contenente un blocco di esempio pronto per essere utilizzato con noi. Possiamo facilmente estenderlo come richiesto, ma è una buona idea sapere come creare un blocco da zero per comprendere appieno tutti gli aspetti dello sviluppo dei blocchi di Gutenberg.
In questo post creeremo un secondo blocco nel nostro my-custom-block plugin per visualizzare un'immagine casuale dal servizio web PlaceIMG. Potrai anche personalizzare il blocco selezionando la categoria di immagini da un controllo di selezione a discesa.
Ma prima impareremo come gli script e gli stili dei blocchi vengono accodati prima di passare all'essenziale registerBlockType () funzione, che è fondamentale per creare blocchi in Gutenberg.
Per aggiungere JavaScript e CSS richiesti dai nostri blocchi, possiamo utilizzare due nuovi hook di WordPress forniti da Gutenberg:
Accentsconagua
enqueue_block_editor_assetsenqueue_block_assetsQuesti sono disponibili solo se il plugin Gutenberg è attivo e funzionano in modo simile agli hook standard di WordPress per gli script di accodamento. Tuttavia, sono destinati specificamente per lavorare con i blocchi di Gutenberg.
Il enqueue_block_editor_assets hook aggiunge solo script e stili all'editor di amministrazione. Ciò lo rende ideale per l'accodamento di JavaScript per la registrazione di blocchi e CSS per lo stile degli elementi dell'interfaccia utente per le impostazioni dei blocchi.
Per l'output a blocchi, però, vorrete che i blocchi facciano lo stesso nell'editor come fanno sul front-end per la maggior parte del tempo. utilizzando enqueue_block_assets rende questo facile come gli stili vengono automaticamente aggiunti sia all'editor che al front-end. Puoi anche utilizzare questo hook per caricare JavaScript, se necessario.
Ma ti starai chiedendo come accodare script e stili solo sulla parte anteriore. Non c'è un hook di WordPress per permetterti di farlo direttamente, ma puoi aggirare questo aggiungendo un'istruzione condizionale all'interno di enqueue_block_assets aggancia la funzione di callback.
add_action ('enqueue_block_assets', 'load_front_end scripts'); function load_front_end scripts () if (! is_admin () // accoda front end solo script e stili quiPer in effetti accodare script e stili utilizzando questi due nuovi hook, è possibile utilizzare lo standard wp_enqueue_style () e wp_enqueue_scripts () funziona come faresti normalmente.
Tuttavia, è necessario assicurarsi di utilizzare le dipendenze dello script corrette. Per gli script di accodamento sull'editor, è possibile utilizzare le seguenti dipendenze:
array ('wp-blocks', 'wp-i18n', 'wp-element', 'wp-components') array ('wp-edit-blocks') E quando si accodano gli stili sia per l'editor che per il front-end, è possibile utilizzare questa dipendenza:
array ('wp-blocks')Una cosa che vale la pena menzionare qui è che i file reali sono stati accodati dai nostri my-custom-block plugin sono i compilato versioni di JavaScript e CSS e non i file contenenti il codice sorgente JSX e Sass.
Questo è solo qualcosa da tenere a mente quando si accodano manualmente i file. Se si tenta di accodare il codice sorgente raw che include React, ES6 + o Sass, si verificheranno numerosi errori.
Questo è il motivo per cui è utile usare un toolkit come creare-Guten-block mentre elabora e accoda automaticamente gli script per te!
Per creare un nuovo blocco, è necessario registrarlo con Gutenberg chiamando registerBlockType () e passando il nome del blocco più un oggetto di configurazione. Questo oggetto ha alcune proprietà che richiedono una spiegazione adeguata.
Prima di tutto, però, diamo un'occhiata al nome del blocco. Questo è il primo parametro ed è una stringa composta da due parti, uno spazio dei nomi e il nome del blocco stesso, separati da un carattere di barra diretta.
Per esempio:
registerBlockType ('block-namespace / block-name', // configuration object);Se stai registrando diversi blocchi in un plug-in, puoi utilizzare lo stesso spazio dei nomi per organizzare tutti i tuoi blocchi. Lo spazio dei nomi deve essere unico per il tuo plug-in, tuttavia, il che aiuta a prevenire i conflitti di denominazione. Questo può accadere se un blocco con lo stesso nome è già stato registrato tramite un altro plugin.
Il secondo registerBlockType () parametro è un oggetto impostazioni e richiede un numero di proprietà da specificare:
titolo (stringa): visualizzato nell'editor come etichetta del blocco ricercabiledescrizione (stringa opzionale): descrive lo scopo di un bloccoicona (elemento Dashicon o JSX opzionale): icona associata a un bloccocategoria (stringa): dove il blocco appare nel Aggiungi blocchi dialogoparole chiave (array opzionale): fino a tre parole chiave utilizzate nelle ricerche di bloccoattributi (oggetto opzionale): gestisce i dati del blocco dinamicomodificare (funzione): una funzione che restituisce il markup da rendere nell'editorsalvare (funzione): una funzione che restituisce il markup da rendere sul front-enduseonce (opzionale booleano): limita il blocco da aggiungere più di una voltasupporti (oggetto opzionale): definisce le funzionalità supportate da blocchiSupponendo che stiamo usando JSX per lo sviluppo di blocchi, ecco un esempio registerBlockType () la chiamata potrebbe apparire come un blocco molto semplice:
registerBlockType ('my-unique-namespace / ultimate-block', title: __ ('Il miglior blocco mai', 'dominio'), icona: 'wordpress', categoria: 'comune', parole chiave: [__ ('esempio ',' dominio '), __ (' Gutenberg ',' dominio '), __ (' blocco ',' dominio ')], modifica: () => Benvenuto nell'Editor di Gutenberg!
, salva: () => Come sto guardando il front-end?
);Si noti come non abbiamo incluso una voce per il descrizione, attributi, useonce, e supporti proprietà? Qualsiasi campo facoltativo (e non pertinente al tuo blocco) può essere omesso in sicurezza. Ad esempio, poiché questo blocco non ha comportato alcun dato dinamico, non è necessario preoccuparsi di specificare alcun attributo.
Copriamo ora il registerBlockType () Proprietà dell'oggetto di configurazione in maggior dettaglio uno per uno.
Quando si inserisce o si cerca un blocco nell'editor, il titolo verrà visualizzato nell'elenco dei blocchi disponibili.
Viene anche visualizzato nella finestra di ispezione dei blocchi, insieme alla descrizione del blocco, se definita. Se l'ispettore del blocco non è attualmente visibile, puoi utilizzare l'icona a forma di ingranaggio nell'angolo in alto a destra dell'editor Gutenberg per attivare la visibilità.
Entrambi i campi titolo e descrizione dovrebbero idealmente essere racchiusi nelle funzioni i18n per consentire la traduzione in altre lingue.
Esistono cinque categorie di blocchi attualmente disponibili:
ComuneformattazionedisposizionewidgetsincorporareQuesti determinano la sezione categoria in cui il blocco è elencato all'interno del Aggiungi blocco finestra.
Il blocchi scheda contiene Blocchi comuni, formattazione, Elementi di layout, e widget categorie, mentre il incorpora la categoria ha una sua scheda.
Le categorie sono attualmente fissate in Gutenberg, ma questo potrebbe essere soggetto a modifiche in futuro. Ciò sarebbe utile, ad esempio, se stessimo sviluppando più blocchi in un singolo plugin e volessi che fossero tutti elencati in una categoria comune in modo che gli utenti potessero individuarli più facilmente.
Per impostazione predefinita, al blocco viene assegnato lo shield Dashicon, ma è possibile sovrascriverlo specificando un Dashicon personalizzato nel icona campo.
Ogni Dashicon ha il prefisso dashicons- seguito da una stringa unica. Ad esempio, l'icona dell'ingranaggio ha il nome dashicons-admin-generic. Per usarlo come icona di blocco, basta rimuovere il dashicons- prefisso per essere riconosciuto, ad es. icona: 'admin-generic'.
Tuttavia, non si è limitati a utilizzare Dashicons come proprietà dell'icona. La funzione accetta anche un elemento JSX, il che significa che è possibile utilizzare qualsiasi immagine o elemento SVG come icona del blocco.
Assicurati di mantenere le dimensioni dell'icona coerenti con altre icone di blocco, che per impostazione predefinita sono 20 x 20 pixel.
Scegli fino a tre parole chiave traducibili per far risaltare il tuo blocco quando gli utenti cercano un blocco. È meglio scegliere parole chiave strettamente correlate alla funzionalità del blocco per ottenere i migliori risultati.
parole chiave: [__ ('cerca', 'dominio'), __ ('per', 'dominio'), __ ('me', 'dominio'),]Potresti anche dichiarare la tua azienda e / o il nome del plug-in come parole chiave in modo che se hai più blocchi, gli utenti possono iniziare a digitare il nome della tua azienda e tutti i blocchi appariranno nei risultati di ricerca.
Sebbene l'aggiunta di parole chiave sia del tutto facoltativa, è un ottimo modo per rendere più semplice per gli utenti la ricerca dei blocchi.
Gli attributi aiutano nella gestione dei dati dinamici in un blocco. Questa proprietà è facoltativa in quanto non è necessaria per blocchi molto semplici che generano contenuto statico.
Tuttavia, se il blocco riguarda i dati che potrebbero cambiare (ad esempio il contenuto di un'area di testo modificabile) o è necessario memorizzare le impostazioni di blocco, utilizzare gli attributi è la strada da percorrere.
Gli attributi funzionano memorizzando i dati di blocchi dinamici nel contenuto del post salvato nel database o in post meta. In questo tutorial utilizzeremo solo attributi che memorizzano dati insieme al contenuto del post.
Per recuperare i dati degli attributi memorizzati nel contenuto del post, dobbiamo specificare dove si trova nel markup. Possiamo farlo specificando un selettore CSS che punta ai dati degli attributi.
Ad esempio, se il nostro blocco contiene un tag di ancoraggio, possiamo usarne uno titolo campo come il nostro attributo come segue:
attributes: linktitle: source: 'attribute', selector: 'a', attributo: 'title'
Qui, il nome dell'attributo è linktitle, che è una stringa arbitraria e può essere qualsiasi cosa tu voglia.
Ad esempio, potremmo usare questo attributo per memorizzare il titolo del collegamento è stato inserito tramite una casella di testo nelle impostazioni del blocco. Fare così improvvisamente rende dinamico il campo del titolo e consente di modificarne il valore nell'editor.
Quando il post viene salvato, il valore dell'attributo viene inserito nei collegamenti titolo campo. Allo stesso modo, quando viene caricato l'editor, il valore di titolo il tag viene recuperato dal contenuto e inserito nel file linktitle attributo.
Ci sono più modi che puoi usare fonte per determinare come il contenuto del blocco viene memorizzato o recuperato tramite attributi. Ad esempio, puoi usare il 'testo' fonte per estrarre il testo interno da un elemento di paragrafo.
attributi: paragraph: fonte: 'testo', selettore: 'p'
Puoi anche usare il bambini fonte per estrarre tutti i nodi figli di un elemento in una matrice e memorizzarla in un attributo.
attributi: editablecontent: fonte: 'children', selector: '.parent'
Questo seleziona l'elemento con la classe .genitore e memorizza tutti i nodi figli nel editablecontent attributo.
Se non si specifica una fonte, il valore dell'attributo viene salvato nei commenti HTML come parte del markup del post quando viene salvato nel database. Questi commenti vengono eliminati prima del rendering del post sul front-end.
Vedremo un esempio specifico di questo tipo di attributo quando entreremo nell'implementazione del nostro blocco immagine casuale più avanti in questo tutorial.
Gli attributi possono richiedere un po 'di tempo per abituarsi, quindi non preoccuparti se non li capisci completamente la prima volta. Consiglierei di dare un'occhiata alla sezione degli attributi del manuale di Gutenberg per maggiori dettagli ed esempi.
Il modificare la funzione controlla come il tuo blocco appare all'interno dell'interfaccia dell'editor. I dati dinamici vengono passati a ogni blocco come oggetti di scena, compresi eventuali attributi personalizzati che sono stati definiti.
È una pratica comune aggiungere className = props.className all'elemento principale del blocco per generare una classe CSS specifica per il tuo blocco. WordPress non aggiunge questo per te all'interno dell'editor, quindi deve essere aggiunto manualmente per ogni blocco se vuoi includerlo.
utilizzando props.className è una pratica standard ed è consigliata in quanto fornisce un modo per personalizzare gli stili CSS per ogni singolo blocco. Il formato della classe CSS generata è .wp-Stop dopo namespace - nome. Come potete vedere, questo è basato sullo spazio dei nomi / nome del blocco e lo rende ideale per essere usato come identificatore di blocco univoco.
La funzione di modifica richiede che venga restituito un markup valido tramite render () metodo, che viene poi utilizzato per il rendering del blocco all'interno dell'editor.
Simile al modificare funzione, salvare mostra una rappresentazione visiva del tuo blocco ma sul front-end. Riceve anche dati di blocco dinamici (se definiti) tramite oggetti di scena.
Una differenza principale è quella props.className non è disponibile all'interno salvare, ma questo non è un problema perché è inserito automaticamente da Gutenberg.
Il supporti la proprietà accetta un oggetto di valori booleani per determinare se il blocco supporta determinate funzionalità di base.
Le proprietà dell'oggetto disponibili che puoi impostare sono le seguenti.
ancora (default false): consente di collegarsi direttamente a un blocco specificocustomClassName (true): aggiunge un campo nell'ispettore del blocco per definire un'abitudine nome della classe per il blocco nome della classe (vero): aggiunge a nome della classe all'elemento radice del blocco basato sul nome del bloccohtml (true): consente di modificare direttamente il markup del bloccouseonce ProprietàQuesta è una proprietà utile che consente di limitare l'aggiunta di un blocco a più pagine. Un esempio di questo è il nucleo Di Più blocco, che non può essere aggiunto a una pagina se già presente.
Come puoi vedere, una volta il Di Più il blocco è stato aggiunto, l'icona del blocco è disattivata e non può essere selezionata. Il useonce la proprietà è impostata su falso per impostazione predefinita.
È giunto il momento di utilizzare le conoscenze finora acquisite per implementare un solido esempio operativo di un blocco che fa qualcosa di più interessante del semplice output di contenuto statico.
Creeremo un blocco per produrre un'immagine casuale ottenuta tramite una richiesta esterna al sito web PlaceIMG, che restituisce un'immagine casuale. Inoltre, sarete in grado di selezionare la categoria di immagini restituite tramite un controllo a discesa selezionato.
Per comodità, aggiungeremo il nostro nuovo blocco allo stesso my-custom-block plugin, piuttosto che creare un nuovo plug-in. Il codice per il blocco predefinito si trova all'interno del / Src / blocco cartella, quindi aggiungi un'altra cartella all'interno / src chiamato random-immagine e aggiungere tre nuovi file:
In alternativa, è possibile copiare il file / Src / blocco cartella e rinominarlo se non si desidera scrivere tutto a mano. Assicurati, tuttavia, di rinominare block.js a index.js all'interno della nuova cartella di blocco.
Stiamo usando index.js per il nome del file principale del blocco in quanto ciò ci consente di semplificare l'istruzione import all'interno blocks.js. Invece di dover includere il percorso e il nome file completo del blocco, possiamo semplicemente specificare il percorso della cartella di blocco e importare cercherà automaticamente un index.js file.
Aprire /src/blocks.js e aggiungi un riferimento al nostro nuovo blocco nella parte superiore del file, direttamente sotto l'istruzione import esistente.
importare './random-image';
Dentro /src/random-image/index.js, aggiungi il seguente codice per avviare il nostro nuovo blocco.
// Importa CSS. importare "./style.scss"; importare './editor.scss'; const __ = wp.i18n; const registerBlockType, query = wp.blocks; registerBlockType ('cgb / block-random-image', title: __ ('Immagine casuale'), icona: 'format-image', categoria: 'common', parole chiave: [__ ('random'), __ (' immagine ')], modifica: function (props) return ( Blocco immagine casuale (editor)
); , save: function (props) return ( Blocco immagine casuale (front-end)
); );Questo imposta il framework del nostro blocco ed è abbastanza simile al codice di blocco boilerplate generato dal creare-Guten-block kit di strumenti.
Iniziamo importando l'editor e i fogli di stile front-end, quindi estrarremo alcune funzioni di uso comune wp.i18n e wp.blocks in variabili locali.
Dentro registerBlockType (), i valori sono stati inseriti per il titolo, icona, categoria, e parole chiave proprietà, mentre il modificare e salvare le funzioni attualmente generano solo contenuto statico.
Aggiungi il blocco immagine casuale a una nuova pagina per vedere l'output generato finora.
Assicurati di continuare a guardare i file per le modifiche in modo che qualsiasi codice sorgente di blocco (JSX, ES6 +, Sass, ecc.) Venga trasposto in JavaScript e CSS validi. Se al momento non stai guardando i file per le modifiche, apri una finestra della riga di comando all'interno di my-custom-block plug-in cartella principale e invio inizio di npm.
Ci si potrebbe chiedere perché non abbiamo dovuto aggiungere alcun codice PHP per accodare ulteriori script di blocco. Gli script di blocco per il my-custom-block blocco sono accodati via init.php, ma non abbiamo bisogno di accodare gli script in modo specifico per il nostro nuovo blocco dato che questo è gestito da noi creare-Guten-block.
Finché importiamo il nostro file di blocco principale in src / blocks.js (come abbiamo fatto sopra), quindi non abbiamo bisogno di fare alcun lavoro aggiuntivo. Tutti i codici JSX, ES6 + e Sass verranno automaticamente compilati nei seguenti file:
Questi file contengono JavaScript e CSS per tutti i blocchi, quindi è necessario accodare solo un set di file, indipendentemente dal numero di blocchi creati!
Siamo ora pronti per aggiungere un po 'di interattività al nostro blocco, e possiamo farlo aggiungendo prima un attributo per memorizzare la categoria dell'immagine.
attributes: category: type: 'string', default: 'nature'
Questo crea un attributo chiamato categoria, che memorizza una stringa con un valore predefinito di 'natura'. Non abbiamo specificato una posizione nella markup per archiviare e recuperare il valore dell'attributo, quindi verranno utilizzati speciali commenti HTML. Questo è il comportamento predefinito se ometti una fonte di attributi.
Abbiamo bisogno di un modo per cambiare la categoria dell'immagine, cosa che possiamo fare tramite un controllo a discesa selezionato. Aggiorna il modificare funzione al seguente:
edit: function (props) const attributes: category, setAttributes = props; function setCategory (event) const selected = event.target.querySelector ('opzione: checked'); setAttributes (category: selected.value); event.preventDefault (); ritorno ( La categoria corrente è: categoria ); Ecco come sarà:
Questo è abbastanza diverso dalla precedente statica modificare funzione, quindi analizziamo le modifiche.
Per prima cosa abbiamo aggiunto un controllo a discesa di selezione con diverse scelte corrispondenti alle categorie di immagini disponibili sul sito di PlaceIMG.
Quando il valore a discesa cambia, il setCategory viene chiamata la funzione, che trova la categoria attualmente selezionata e quindi a sua volta chiama il setAttributes funzione. Questa è una funzione di base di Gutenberg e aggiorna correttamente il valore di un attributo. Si consiglia di aggiornare solo un attributo utilizzando questa funzione.
Ora, ogni volta che viene selezionata una nuova categoria, il valore dell'attributo si aggiorna e viene passato nuovamente modificare funzione, che aggiorna il messaggio di output.
Dobbiamo completare un ultimo passaggio per ottenere l'immagine casuale da visualizzare. Dobbiamo creare un componente semplice che includa la categoria corrente e produca un
La richiesta che dobbiamo fare a PlaceIMG è nella forma: https://placeimg.com/[width]/[height]/[category]
Manterremo la larghezza e l'altezza corrette per ora, quindi dobbiamo solo aggiungere la categoria corrente alla fine dell'URL della richiesta. Ad esempio, se la categoria fosse 'natura' quindi l'URL di richiesta completa sarebbe: https://placeimg.com/320/220/nature.
Aggiungere un RandomImage componente sopra registerBlockType ():
function RandomImage (category) const src = 'https://placeimg.com/320/220/' + categoria; ritorno;
Per usarlo, basta aggiungerlo all'interno della funzione di modifica e rimuovere il messaggio di output statico. Mentre ci siamo, facciamo lo stesso per la funzione di salvataggio.
Il pieno index.js il file dovrebbe ora assomigliare a questo:
// Importa CSS. importare "./style.scss"; importare './editor.scss'; const __ = wp.i18n; const registerBlockType, query = wp.blocks; function RandomImage (category) const src = 'https://placeimg.com/320/220/' + categoria; ritorno); , save: function (props) const attributes: category = oggetti di scena; ritorno (
Infine (per ora), aggiungi i seguenti stili a editor.scss per aggiungere un bordo colorato attorno all'immagine.
.wp-block-cgb-block-random-image select padding: 2px; margine: 7px 0 5px 2px; border-radius: 3px;
Avrai anche bisogno di alcuni stili in style.css.
.wp-block-cgb-block-random-image background: # f3e88e; colore: #fff; border: 2px solid # ead9a6; border-radius: 10px; imbottitura: 5px; larghezza: -webkit-fit-content; larghezza: -moz-fit-content; larghezza: contenuto adatto; img border-radius: inherit; border: 1px punteggiato # caac69; display: grid;
Ogni volta che la pagina viene aggiornata nell'editor o sul front-end, viene visualizzata una nuova immagine casuale.
Se visualizzi più volte la stessa immagine, puoi eseguire un aggiornamento rapido per impedire che l'immagine venga pubblicata dalla cache del browser.
In questo tutorial abbiamo coperto molto terreno. Se ce l'hai fatta fino in fondo allora concediti una meritata pacca sulla spalla! Lo sviluppo dei blocchi di Gutenberg può essere molto divertente, ma è decisamente difficile cogliere ogni concetto alla prima esposizione.
Lungo la strada, abbiamo imparato come accodare script e stili di blocco e coperto il registerBlockType () funzione in profondità.
Abbiamo seguito questo mettendo in pratica la teoria e creando un blocco personalizzato da zero per visualizzare un'immagine casuale da una categoria specifica utilizzando il servizio web PlaceIMG.
Nella prossima e ultima parte di questa serie di tutorial, aggiungeremo ulteriori funzionalità al nostro blocco di immagini casuali tramite il pannello delle impostazioni nell'ispettore di blocco.
Se hai seguito questo tutorial e vuoi semplicemente sperimentare il codice senza digitare tutto, sarai in grado di scaricare il finale my-custom-block plugin nel prossimo tutorial.
