Come aggiungere stili di blocco personalizzati ai blocchi Gutenberg di WordPress

Una caratteristica un po’ meno conosciuta in Gutenberg è la possibilità di impostare stili diversi per i blocchi. Puoi registrare tanti stili diversi su qualsiasi tipo di blocco per dare allo stesso blocco design diversi. Gli stili possibili per i blocchi vengono visualizzati come una sezione nella parte destra dell’editor. Ogni stile ha la sua anteprima. Se stai gestendo correttamente gli stili, il passaggio da uno stile all’altro dovrebbe aggiornare immediatamente il design all’interno dell’editor e nel frontend.

La documentazione di WordPress per questa funzione non è attualmente così completa e informativa come potrebbe essere. Quindi in questo post daremo uno sguardo dettagliato a come aggiungere i tuoi stili di blocco personalizzati e come dovresti gestire lo stile per loro.

Il modo in cui funziona questa funzione è che ogni volta che Gutenberg rileva che un tipo di blocco è stato registrato come minimo uno stile, la casella "Stili" apparirà automaticamente nella parte destra dell’editor. Al suo interno l’editor può scegliere tra lo stile predefinito o qualsiasi stile di blocco che è stato aggiunto.

Nelle versioni precedenti (almeno prima di WordPress 5.3) la registrazione di uno stile personalizzato richiedeva di registrare anche lo stile predefinito ("nessuno stile"). Fortunatamente questo è stato risolto nelle versioni più recenti di WordPress, quindi ora devi solo registrare i tuoi stili personalizzati e WordPress aggiungerà automaticamente lo stile predefinito.

Puoi registrare stili di blocco personalizzati in due modi; con PHP o con Javascript. Daremo un’occhiata a entrambi. Ma prima alcuni a-ha per quanto riguarda la gestione dei tuoi stili.

Una nota sugli stili di accodamento per Gutenberg

Potrebbe esserci una certa confusione su come e dove aggiungere i tuoi stili (file CSS); solo all’editor, al frontend o un foglio di stile per entrambi. Uno degli scopi principali dell’editor Gutenberg è assicurarsi di poter visualizzare in anteprima correttamente l’aspetto del contenuto del tuo post, all’interno dell’editor. Quindi ti consigliamo di assicurarti che i tuoi stili personalizzati vengano applicati nell’editor e nel frontend.

Il modo in cui lo gestisci dipende davvero dal tuo progetto e dalla configurazione del foglio di stile esistente. Se stai sviluppando un tema completo, probabilmente includi già lo stile dei blocchi nel foglio di stile del frontend. Potresti considerare di aggiungere un foglio di stile separato che accoderai solo per l’editor. Ma questo potrebbe essere difficile da mantenere se aggiungi molti stili diversi. Dovresti aggiornare i tuoi stili in due punti e assicurarti che i risultati siano gli stessi. La soluzione sarebbe quella di mantenere un foglio di stile da accodare sia per l’editor che per il frontend. Ma poi il tuo frontend dovrebbe caricare almeno due fogli di stile separati e questo potrebbe non essere l’ideale.

Un’altra soluzione è usare ad esempio SCSS o LESS e impostare @importsin modo tale che sia necessario scrivere gli stili di blocco solo una volta, e viene applicato sia all’editor che al frontend. Come vedrai di seguito quando usi PHP per registrare stili di blocco personalizzati, hai ancora un’altra opzione; per aggiungere stili in linea. Questi stili verranno applicati sia nell’editor che nel frontend. Nel frontend verranno aggiunti da WordPress come inline personalizzati <style type="text/css">...</style>all’interno dell’intestazione.

Comunque tu scelga di risolverlo, sappi che ci sono un paio di nuovi hook per gli stili di registro (e gli script) per Gutenberg. Se vuoi accodare un foglio di stile sia per il frontend che per l’editor, usa l’hook enqueue_block_assets. Se vuoi aggiungere un foglio di stile solo per l’editor, accodalo all’interno dell’hook enqueue_block_editor_assets.

Come applicare lo stile agli stili di blocco personalizzati

Gli stili di blocco personalizzati verranno aggiunti come classe di un determinato modello sul tag HTML più esterno per il blocco.

La classe CSS per gli stili di blocco viene aggiunta sotto forma di ” is-style-<stylename>“. Se ad esempio dai un nome al tuo stile ” outline“, il blocco otterrà la classe ” is-style-outline“.

Tuttavia, potresti riscontrare che l’editor di Gutenberg in alcuni casi sovrascriverà il tuo stile. Ti consiglio di anteporre lo stile del tuo editor al selettore editor-styles-wrapperper assicurarti che i tuoi stili "vincano". Tieni presente che questa classe non esiste nel frontend, quindi per sicurezza potresti dover aggiungere due selettori, in questo modo (se stai utilizzando lo stesso foglio di stile sia per l’editor che per il frontend):

.is-style-colored-bottom-border, 
.editor-styles-wrapper .is-style-colored-bottom-border { 
    border-bottom: 2px solid purple;
}

Aggiunta di stili di blocco personalizzati con PHP

Per aggiungere un tipo di blocco personalizzato usando PHP utilizziamo la funzione [register_block_style](https://developer.wordpress.org/reference/functions/register_block_style/)(). La documentazione purtroppo è priva di informazioni in quale hook dovremmo usare, ma ho avuto fortuna con l’hook init.

Devi conoscere il nome dello spazio dei nomi Gutenberg del tuo tipo di blocco per aggiungere uno stile personalizzato su di esso. Tutti i blocchi standard di WordPress hanno lo spazio dei nomi ” core" seguito da a /e una versione slug del loro nome. Ad esempio, il nome di Gutenberg per il blocco di paragrafo standard è core/paragraph.

La registrazione di uno stile di blocco personalizzato viene eseguita nella sua forma più semplice in questo modo:

Il codice precedente aggiunge uno stile di blocco personalizzato al tipo di blocco Intestazione, che risulterebbe nella classe is-style-colored-bottom-bordersu qualsiasi Intestazione che ha scelto questo stile.

Questa funzione ti fornisce due metodi per aggiungere il tuo CSS (se non lo hai aggiunto in altro modo); sia fornendo CSS in linea come stringa, sia fornendo un handle di foglio di stile registrato che WordPress metterà in coda per te se necessario.

Se desideri aggiungere uno stile in linea (ricorda, ciò influenzerà sia l’editor che il frontend), aggiungi l’elemento ‘ inline_style‘ alla chiamata di funzione e scrivi il CSS completo come stringa come valore:

Se preferisci fare in modo che la funzione accoda un foglio di stile, fornisci il suo handle all’elemento ‘ style_handle‘.

Regola la posizione del tuo foglio di stile per adattarlo al tuo progetto. Il foglio di stile verrà applicato sia all’editor che al frontend, ma questa volta il frontend farà una richiesta separata per includere questo foglio di stile. Questo metodo non è consigliato se si aggiungono più stili di blocco. Il frontend sarà notevolmente rallentato richiedendo un intero gruppo di fogli di stile separati.

Aggiunta di stili di blocco personalizzati con Javascript

Se preferisci aggiungere i tuoi stili di blocco usando Javascript, questo è facile come con PHP.

Avrai bisogno di accodare un file Javascript sull’editor solo hook: enqueue_block_editor_assets. Il tuo script probabilmente non avrà bisogno di dipendenze, ma preferisco aggiungere almeno ‘ wp-blocks‘ come dipendenza.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks']
    );
});

Regola il nome del file e la posizione per adattarli al tuo progetto.

Nel tuo file Javascript usi la funzione registerBlockStyle()all’interno wp.blocksdell’oggetto per registrare stili di blocco personalizzati. L’aggiunta dello stesso stile di blocco che abbiamo fatto in PHP sopra sarebbe simile a:

wp.blocks.registerBlockStyle('core/heading', {
    name: 'colored-bottom-border',
    label: 'Colored bottom border'
});

E questo è tutto! Vai tranquillo.

Annullamento della registrazione degli stili di blocco

Proprio come puoi registrare uno stile di blocco, anche uno stile di blocco può essere annullato. Forse vuoi rimuovere alcuni degli stili di blocco predefiniti di WordPress? Come per la registrazione di stili di blocco, puoi anche annullare la registrazione di stili di blocco con PHP o Javascript. Ma la scelta tra questi due metodi non è più una scelta di preferenza.

Non puoi annullare la registrazione di un blocco con PHP se è stato registrato con Javascript e viceversa. Quindi devi capire come è stato registrato lo stile che desideri rimuovere e abbinarlo con PHP o Javascript. Credo che tutti gli stili di blocco di WordPress siano aggiunti con Javascript (non citarmi su questo!). Quindi, se vuoi rimuoverne alcuni, dovrai seguire il percorso Javascript.

L’annullamento della registrazione di uno stile di blocco con PHP viene eseguito chiamando la funzione unregister_block_style(), fornendo il tipo di blocco e il nome di stile che si desidera rimuovere. Ad esempio, annullare la registrazione dello stile aggiunto sopra in questo post (supponendo che sia stato registrato con PHP) sarebbe simile a questo:

add_action('init', function() {
    unregister_block_style('core/heading', 'colored-bottom-border');
});

L’annullamento della registrazione di uno stile di blocco con Javascript viene eseguito in modo simile con la funzione unregisterBlockStyle()all’interno wp.blocksdell’oggetto. Tuttavia, con Javascript c’è una questione di quale script deve essere eseguito per primo e potresti riscontrare problemi quando lo script viene eseguito prima della registrazione. Per risolvere questo problema utilizziamo l’equivalente di Gutenberg di "document ready" (jQuery(document).ready(function() { ... });) di jQuery e aggiungiamo anche un’altra dipendenza al tuo script.

Iniziamo aggiungendo una nuova dipendenza di script sul tuo file Javascript che si accoda a ‘ wp-edit-post‘:

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks', 'wp-edit-post']
    );
});

E all’interno del tuo file Javascript, avvolgi la tua chiamata di funzione unregister all’interno wp.domReady(function() { ... }), in questo modo:

wp.domReady(function() {
    wp.blocks.unregisterBlockStyle('core/quote', 'large');
});

Come mostra il codice sopra, con Javascript ora siamo in grado di rimuovere lo stile "Grande" di WordPress sul blocco Preventivo. Se provassi a fare lo stesso con PHP, non funzionerebbe.

Una nota a margine sull’annullamento della registrazione degli stili di blocco

Potresti notare che anche se hai rimosso con successo qualsiasi stile di blocco personalizzato su un blocco, la casella "Stili" nell’editor non scomparirà. Rimane con solo la scelta "Predefinito" al suo interno. Se vuoi rimuovere completamente la casella "Stili" per non confondere gli editor, puoi semplicemente annullare la registrazione dello stile predefinito (es wp.blocks.unregisterBlockStyle('core/quote', 'large'). ). Questo rimuoverà completamente la casella "Stili" dall’editor di Gutenberg.