Ti sei mai trovato nella situazione in cui desideri aggiungere le tue impostazioni personalizzate ai blocchi Gutenberg di WordPress? In questo post andremo nel dettaglio su come farlo. Troverai due codici di esempio di casi d’uso reali per l’aggiunta di impostazioni personalizzate ai blocchi di WordPress.

Tieni presente che poiché i blocchi di Gutenberg sono Javascript, la loro modifica richiede la scrittura del codice in Javascript. Proprio come il codice PHP di WordPress ha hook e filtri che consentono agli sviluppatori di temi o plugin di modificarne il codice, ci sono anche filtri nel codice Javascript di WordPress. Analogamente alla [add_filter](https://developer.wordpress.org/reference/functions/add_filter/)()funzione di PHP, abbiamo la funzione Javascript [addFilter](https://developer.wordpress.org/block-editor/packages/packages-hooks/#api-usage)().

Scriverò il codice nella sintassi Javascript ES6, che richiede un compilatore per trasformarlo. Puoi scrivere con la sintassi ES5 ma ti consiglio di usare ES6/ESNext. Ho un post che spiega come configurare un trasformatore per ES6/ESNext. Presumo anche che tu abbia una certa familiarità con React/JSX, forse una certa esperienza su come creare i tuoi blocchi Gutenberg personalizzati.

Cosa puoi filtrare sui blocchi di Gutenberg

Non c’è molta documentazione negli hook e nei filtri Gutenberg disponibili. Ma allo scopo di aggiungere impostazioni personalizzate e in qualche modo applicarle ai blocchi esistenti; questo è quello che ho trovato finora. Mi sono concentrato sull’aggiunta di impostazioni semplici, non su operazioni che richiedono modifiche drastiche dei componenti o comportamenti complessi.

Ci sono tre passaggi per aggiungere impostazioni personalizzate ai blocchi esistenti:

Aggiungiamo un filtro [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype)sull’array delle impostazioni del blocco esistente. Questo ci consente di aggiungere nuovi attributi attributesall’array, consentendoci così di salvare informazioni aggiuntive sul blocco. Dobbiamo salvare la nostra impostazione personalizzata da qualche parte.
Aggancia al componente del blocco edit(il componente responsabile del rendering del blocco nell’editor). In questo gancio possiamo agganciarci all’Inspector (la barra laterale) e aggiungere i nostri componenti. Possiamo aggiungere una nuova sezione/riquadro o agganciarci alla sezione "Avanzate" che è sempre presente in tutti i blocchi. Poi sta a noi renderizzare gli input delle impostazioni, come input di testo, caselle di controllo o quant’altro.
saveFiltra gli oggetti di scena del blocco. Possiamo regolare gli oggetti di scena per il salvataggio, che è responsabile sia del salvataggio del blocco che del rendering nel frontend (al di fuori dell’editor). Nel nostro caso vogliamo aggiungere una classe o uno stile inline.

Possiamo prendere di mira blocchi specifici o tutti. Abbiamo sempre accesso al tipo di blocco in cui ci troviamo.

Per dirlo in altre parole: aggiungiamo alcune impostazioni personalizzate in Inspector e le salviamo negli attributi personalizzati che abbiamo aggiunto al blocco. Possiamo quindi influenzare il nome della classe del blocco o lo stile inline (in alcuni casi), a seconda degli attributi salvati. Con i nomi delle classi personalizzate possiamo aggiungere facilmente CSS personalizzati che danno visivamente un effetto alle nostre impostazioni.

Cosa non possiamo fare (per ora?)

Sfortunatamente ci sono alcune cose a cui non possiamo accedere con i filtri sui blocchi esistenti. Per quanto riguarda l’aggiunta di semplici impostazioni personalizzate ai blocchi, queste sono cose comuni che non possiamo influenzare.

Nessun accesso allo stile in linea del blocco all’interno dell’editor

Nei casi in cui le impostazioni influiscono sul design di un blocco, è necessario aggiungere uno stile in linea sul nodo di wrapping del blocco. Solo il nome della classe non va bene. Ad esempio, se aggiungi un’impostazione di colore personalizzata e l’utente seleziona un colore personalizzato (da colorpicker), non puoi risolverlo aggiungendo una classe: hai bisogno di uno stile in linea.

Sfortunatamente sembra che i blocchi predefiniti di WordPress gestiscano lo stile inline nell’editor in modo completamente indipendente senza alcuna opzione di filtraggio o "aggancio". Mostrerò un modo per aggirare questo problema nell’ultimo esempio di seguito, ma non è l’ideale in tutti i casi.

Perché importa che il blocco appaia in modo diverso nell’editor rispetto al frontend, potresti chiedere? Il punto centrale di Gutenberg è implementare un modo visivo per modificare i contenuti in cui ciò che vediamo è effettivamente ciò che otteniamo. Vogliamo ottenere lo stesso aspetto visivo sia nell’editor che nel frontend.

Alcuni blocchi non includono il nome della classe nell’editor

Come accennato in precedenza, possiamo filtrare il nome della classe di wrapping del blocco poiché si tratta di un oggetto che viene passato a tutti i blocchi Gutenberg. Ma sfortunatamente ci sono alcuni blocchi che non applicano affatto la classe del blocco in edit. Un esempio è il blocco Cover. Ho giocato molto usando i blocchi Cover come "sezioni" per le prime pagine e continuo a riscontrare problemi perché il blocco Cover crea la propria classe all’interno edit. Salta completamente la classe "globale" del blocco (che è quella a cui abbiamo accesso tramite i filtri).

Ma almeno possiamo essere sicuri che i nomi delle classi filtrati vengono sempre applicati in save(frontend). Ciò avviene automaticamente al di fuori del codice specifico di ogni blocco.

Se sbaglio su qualcuno di quanto sopra, PER FAVORE fatemelo sapere nei commenti qui sotto! Sto imparando continuamente Gutenberg e allo stesso tempo anche Gutenberg si evolve. Spero che a un certo punto quanto sopra sarà possibile a un certo punto o che sia possibile, ma mi mancano solo alcune informazioni cruciali!

Detto questo, iniziamo a esaminare un po’ di codice.

Esempio 1: aggiungi un campo di attivazione/disattivazione per nascondere un blocco Cover su dispositivo mobile

Supponiamo di sviluppare un tema in cui i blocchi di copertina verranno utilizzati per le "sezioni" sulla prima pagina. E vogliamo fornire all’utente la possibilità di nascondere una determinata sezione dal cellulare. Per risolvere questo problema, possiamo aggiungere un campo di attivazione/disattivazione nella sezione "Avanzate" nell’Inspector del blocco Cover. Se il campo è attivato, il blocco Cover riceverà una classe personalizzata aggiuntiva che possiamo indirizzare con CSS e media query.

A proposito: questo è un caso in cui il problema del blocco Cover che non applica i nostri nomi di classe personalizzati nell’editor è effettivamente un vantaggio! Immagina se lo facesse; quindi sarebbe impossibile per l’utente modificare il blocco nell’editor se ha uno schermo piccolo!

Come accennato in precedenza, ci sono tre passaggi per i quali dobbiamo programmare. Abbiamo anche bisogno di aggiungere del PHP per accodare il nostro file Javascript all’editor. Facciamolo prima.

Aggiunta del nostro script all’editor

Agganciamo una funzione all’azione [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). All’interno della nostra funzione accodiamo uno script, proprio come faremmo normalmente in wp_enqueue_scriptshook.


add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});

Ricorda di modificare il percorso in cui si trova il tuo script! Nota: se stai scrivendo in ES6 con webpack compilando il tuo Javascript, ricorda di impostare il percorso per la build del tuo script, non il sorgente.

Mi piace aggiungere ‘ wp-edit-post‘ come dipendenza allo script per assicurarmi che venga caricato abbastanza tardi.

Questo è tutto il PHP che dobbiamo fare. Il resto è scritto nel nostro file Javascript.

Aggiungi un attributo personalizzato

Il primo filtro che useremo è l’oggetto delle impostazioni di blocks.registerBlockTypequali filtri .registerBlockType

Ma prima, un po’ sull’aggiunta di filtri in Javascript. Dal momento che non ho trovato alcuna buona documentazione per questo, lo spiegherò un po ‘qui. La funzione addFiltersi trova nello spazio dei wp.hooksnomi e accetta quattro argomenti.

addFilter('hookName', 'namespace', 'functionName', 'priority');

Il primo parametro, ‘hookName’, è il nome del filtro a cui vogliamo agganciarci. Questo è l’equivalente del primo parametro quando si utilizza PHP add_filter(). Il secondo parametro, ‘namespace’, è uno spazio dei nomi personalizzato per il codice. Questo è solo per evitare la collisione dei nomi. Puoi praticamente impostare tutto ciò che vuoi qui, ma non usare lo spazio dei nomi di WordPress ("wp"). Usa una forma abbreviata del tuo nome o del nome del progetto. Il terzo parametro, ‘functionName’, è la funzione agganciata, che è la stessa del add_filter()secondo argomento di PHP. E infine il quarto parametro, ‘priorità’, è facoltativo. Ancora una volta, questo è lo stesso del add_filter()terzo argomento di PHP.

Il processo per i filtri in Javascript è lo stesso di PHP. Definiamo una funzione che deve restituire la variabile filtrata. A volte la variabile è una stringa, un oggetto o un componente. All’interno della funzione modifichiamo la variabile come meglio crediamo.

Nel nostro caso vogliamo aggiungere un nuovo attributo attributeall’oggetto del blocco. Chiameremo il nuovo attributo hideOnMobilee imposteremo il suo tipo su boolean. Questo è fatto in questo modo:


function addCoverAttribute(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/cover') {
            settings.attributes = Object.assign(settings.attributes, {
                hideOnMobile: {
                    type: 'boolean',
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/cover-custom-attribute',
    addCoverAttribute
);

In linea #3ci assicuriamo di indirizzare solo i blocchi di tipo ‘ core/cover‘. Il secondo argomento da blocks.registerBlockTypefiltrare è abbastanza convenientemente il nome del blocco. Quindi aggiungiamo un nuovo oggetto oggetto settings.attributesall’oggetto. Infine ci assicuriamo di restituire la variabile filtrata, settings.

A questo punto visivamente nulla è cambiato in Gutenberg. Ma tutti i blocchi Cover ora hanno un attributo aggiuntivo che possiamo usare per memorizzare le nostre impostazioni.

Aggiungi impostazione a Impostazioni (pannello Avanzate)

Il secondo filtro viene chiamato editor.BlockEdite filtra il componente del blocco edit. Questo filtro riceve il componente del blocco originale BlockEdite restituisce un nuovo componente avvolto. Dobbiamo usare wp.compose.createHigherOrderComponentper restituire il componente avvolto.

All’interno del nostro componente ci assicuriamo di eseguire il rendering del componente avvolto BlockEdit, a prescindere. Ma se il blocco è di tipo Cover ci agganciamo anche al componente InspectorAdvancedControls(che è il pannello “Avanzate" in Inspector) e aggiungiamo un ToggleControl. Scriviamo ToggleControlper mostrare il valore e aggiornare l’attributo personalizzato che abbiamo aggiunto in precedenza, hideOnMobile.

Non dimenticare di restituire sempre l’originale BlockEdit, cosa che facciamo in linea #9. Alla riga #10 controlliamo se il tipo di blocco è Cover e renderizziamo il InspectorAdvancedControlscomponente. All’interno qui aggiungiamo un ToggleControl, che è un controllo di input che viene visualizzato come alternanza tra true o false. Impostiamo un’etichetta e colleghiamo il suo valore hideOnMobileall’attributo. Se hai già aggiunto impostazioni a Inspector, questo dovrebbe essere abbastanza semplice per te.

Con il codice sopra, ora dovremmo ottenerlo all’interno del pannello "Avanzate" in Inspector sui blocchi di copertina:

L’input aggiornerà ora il nostro attributo personalizzato hideOnMobile. L’ultimo passaggio consiste nel fare qualcosa che dipende dal valore di questo attributo. A partire da ora, l’attributo è salvato, ma in realtà non influisce su nulla.

Aggiungi una classe personalizzata

Il passaggio finale consiste nell’aggiungere una classe personalizzata alla classe del blocco. Lo facciamo con il filtro blocks.getSaveContent.extraProps. Questo filtro influisce sugli oggetti di scena del componente del blocco save. Uno di questi è il prop className, che sarà sempre applicato al frontend. Aggiungiamo semplicemente la nostra classe personalizzata dopo di essa se l’attributo era true, quindi la restituiamo. Ho deciso di aggiungere una classe ‘ hide-on-mobile‘ ‘, ma puoi chiamarla come preferisci.

Questo codice è abbastanza autoesplicativo. Alla riga #4controlliamo se l’attributo hideOnMobileesiste ed è true. In tal caso, aggiungiamo una classe personalizzata alla classNamestringa.

Con tutti e tre i filtri precedenti, ora dovremmo ottenere una classe personalizzata "hide-on-mobile" applicata al nostro blocco Cover ogni volta che l’impostazione è attivata.

Non resta che aggiungere un po’ di CSS al foglio di stile del frontend del tuo tema. Qualcosa come questo;


.wp-block-cover.hide-on-mobile { display: none; }
@media (min-width: 480px) {
    .wp-block-cover.hide-on-mobile { display: block; }
}

Esempio 2: aggiungi il pannello Impostazioni con l’impostazione del colore di sfondo personalizzata per il blocco spaziatore

Per il secondo caso d’uso, vogliamo aggiungere impostazioni di colore personalizzate al blocco Spacer. Per impostazione predefinita, il blocco Spacer non ha altre impostazioni oltre alla sua altezza. Supponiamo di voler aggiungere un colore di sfondo che colori l’intera altezza del blocco Spacer. Ciò consente all’utente di aggiungere "strisce" vuote e colorate all’interno del proprio contenuto. In questo caso vogliamo aggiungere le impostazioni del colore nel proprio pannello separato in Inspector, come al solito comportamento previsto per le impostazioni del colore.

Nota: la gestione dei colori è un po’ più complicata in quanto è necessario utilizzare un (altro) componente di ordine superiore withColors. Poiché abbiamo già bisogno di implementare un componente di ordine superiore nel editor.BlockEditabbiamo bisogno di composepiù componenti. Inoltre, dobbiamo aggiungere due attributi per ciascuna impostazione del colore. Uno conterrà lo slug della tavolozza dei colori e l’altro conterrà il codice colore esadecimale, solo se l’utente ha optato per un colore personalizzato (utilizzato il colorpicker). Questo è un comportamento comune quando si lavora con withColors. Ho un <a href="https://wordpress.mediadoma.com/it/come-aggiungere-le-impostazioni-del-colore-al-tuo-blocco-gutenberg-personalizzato/" title="post che spiega l'aggiunta delle impostazioni del colore e withColorsin dettaglio” >post che spiega l’aggiunta delle impostazioni del colore e withColorsin dettaglio se ti confondi.

In secondo luogo, in questo caso ci imbatteremo nel problema spiegato sopra; dove non possiamo aggiungere lo stile inline appropriato all’editor. La soluzione che ho scelto in questo caso è racchiudere il blocco Spacer all’interno di diva nell’editor e applicare le classi e lo stile inline appropriati al wrapping div. Ciò rende il colore selezionato visibile nell’editor quando il blocco è deselezionato. Dopo aver selezionato il blocco, tuttavia, WordPress aggiunge il proprio sfondo grigio chiaro personalizzato al blocco, coprendo il nostro colore di sfondo personalizzato. Un CSS all’editor risolverà questo problema. Spiegherò di più alla fine.

I passaggi sono gli stessi dell’esempio sopra. Prima accodiamo il nostro script all’editor in PHP. Quindi in Javascript filtriamo l’ attributesoggetto, il editcomponente Spacer e infine il savecomponente Spacer.

Aggiunta del nostro script all’editor


add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-gutenberg-filters', get_template_directory_uri(). '/assets/js/gutenberg-filters.js', ['wp-edit-post']);
});

Ricorda di modificare il percorso del tuo script. Mi piace aggiungere ‘ wp-edit-post‘ come dipendenza allo script per assicurarmi che venga caricato abbastanza tardi.

Questo è tutto il PHP che dobbiamo fare. Il resto è scritto nel nostro file Javascript.

Aggiungi attributi personalizzati

Come nell’esempio sopra, aggiungiamo un filtro blocks.registerBlockTypeper aggiungere elementi oggetto aggiuntivi all’oggetto del blocco attributes.

Quando lavoriamo con withColorsdobbiamo aggiungere due attributi per ogni colore. Il nome del nostro attributo del colore di sfondo è backgroundColor, il che significa che il secondo attributo deve essere nominato customBackgroundColor. Tutto questo è spiegato nel mio post sulla gestione delle impostazioni del colore in Gutenberg. Entrambi devono essere di tipo string e applicati solo a blocchi di tipo Spacer.


function addSpacerAttributes(settings, name) {
    if (typeof settings.attributes !== 'undefined') {
        if (name == 'core/spacer') {
            settings.attributes = Object.assign(settings.attributes, {
                backgroundColor: {
                    type: 'string',
                },
                customBackgroundColor: {
                    type: 'string'
                }
            });
        }
    }
    return settings;
}
 
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'awp/spacer-background-attribute',
    addSpacerAttributes
);

Aggiungi il pannello ColorSettings a Impostazioni

Il secondo passaggio consiste nell’aggiungere un pannello delle impostazioni del colore all’Inspector per il blocco Spacer filtrando editor.BlockEdit.

Dobbiamo usare composeper combinare il componente di ordine superiore restituito da questo filtro e withColors. In altre parole, avvolgiamo semplicemente il componente restituito in withColors. Come parametro withColorsforniamo il nostro attributo backgroundColor.

All’interno del componente avvolto ci assicuriamo di restituire sempre BlockEdit(linea #9e #39per blocchi Spacer). Per il blocco di tipo Spacer ci agganciamo anche InspectorControlsper aggiungere un PanelColorSettingscolore per la nostra scelta. Questa è la procedura standard per aggiungere le impostazioni del colore.

In linea #17 - 34generiamo manualmente la classe e/o lo stile inline necessari. Quindi in linea #38aggiungiamo un div avvolgente BlockEditcon quelle classi e stili inline.

Il risultato è un nuovo pannello delle impostazioni del colore in Inspector per i blocchi Spacer, completamente funzionante.

La scelta di un colore della tavolozza o di un colore personalizzato sarà effettivamente influenzata nel div di wrapping all’interno dell’editor. Ma puoi vederlo solo quando deselezioni il blocco Spacer!

Ciò accade perché WordPress applica il proprio stile quando si seleziona un blocco distanziatore. Lo sistemeremo alla fine, prima dobbiamo solo applicare la stessa classe e/o stile inline anche nel frontend.

Aggiungi classe personalizzata e stile in linea per salvare

Infine, dobbiamo filtrare blocks.getSaveContent.extraPropse applicare la classe necessaria e/o lo stile in linea per il frontend. Anche in questo caso è molto simile a quello che abbiamo fatto nell’esempio 1 sopra. Se è stato scelto un colore della tavolozza, è necessario aggiungere un nome di classe che segua gli standard di WordPress per le impostazioni del colore (" has-<PALETTESLUG>-background-color"). Se è stato scelto un colore personalizzato, è necessario aggiungere uno stile in linea con il colore esadecimale.

Nota: se hai bisogno di gestire molto i nomi delle classi, ti consiglio di importare la classnameslibreria. Questo è molto utilizzato in Gutenberg perché semplifica notevolmente l’impostazione dei nomi di classe corretti. Il codice seguente presuppone che tu non l’abbia fatto e compone il nome della classe manualmente.


function applySpacerBackground(props, blockType, attributes) {
    if (blockType.name == 'core/spacer') {
        const { backgroundColor, customBackgroundColor } = attributes;
 
        // For improved class name handling, use classnames library. Or do it manually like..
        let className = (props.className != undefined)? props.className: '';
        if (backgroundColor != undefined) {
            className += ' has-' + backgroundColor + '-background-color';
        }
        props.className = className;
        if (customBackgroundColor != undefined) {
            Object.assign(props, { style: { ...props.style, backgroundColor: customBackgroundColor }});
        }
    }
    return props;
}
 
wp.hooks.addFilter(
    'blocks.getSaveContent.extraProps',
    'awp/spacer-apply-class',
    applySpacerBackground
);

Con il codice sopra, il frontend ora renderà perfettamente i blocchi Spacer con la nostra scelta di colori personalizzata!

La correzione finale (opzionale) consiste nell’aggiungere alcuni CSS all’editor. Dovrai aggiungere CSS in linea o un foglio di stile dell’editor. Ad esempio, potresti accodare un foglio di stile nello stesso hook PHP che abbiamo usato per accodare il nostro file Javascript. Non entrerò nei dettagli su come farlo; ma il CSS di cui avrai bisogno è qualcosa come il seguente. Tutto ciò che fa è impostare lo Spacer background-colorsul colore ereditato (ereditarirà dal nostro div wrapping) quando il blocco è selezionato:


.block-library-spacer__resize-container.is-selected { 
    background-color: inherit; 
}

PS: Tieni presente che questo è soggetto a modifiche in futuro. Gutenberg è ancora in forte evoluzione.

Conclusione

In questo post abbiamo appreso due metodi per implementare impostazioni personalizzate nei blocchi Gutenberg di WordPress esistenti. È del tutto possibile per impostazioni semplici che forse richiedono solo una classe o uno stile in linea. Abbiamo esaminato gli avvertimenti, che spero verranno corretti nelle versioni successive di Gutenberg!

Fonte di registrazione: awhitepixel.com