Comment ajouter des styles de blocs personnalisés aux blocs WordPress Gutenberg

Une fonctionnalité un peu moins connue de Gutenberg est la possibilité de configurer différents styles pour les blocs. Vous pouvez enregistrer autant de styles différents sur n’importe quel type de bloc afin de donner au même bloc des designs différents. Les styles possibles pour les blocs sont affichés sous forme de section dans la partie droite de l’éditeur. Chaque style obtient son propre aperçu. Si vous gérez correctement les styles, le passage d’un style à l’autre devrait immédiatement mettre à jour la conception dans l’éditeur ainsi que dans l’interface.

La documentation de WordPress pour cette fonctionnalité n’est actuellement pas aussi complète et informative qu’elle pourrait l’être. Ainsi, dans cet article, nous examinerons en détail comment vous pouvez ajouter vos styles de bloc personnalisés et comment vous devez gérer le style pour eux.

La façon dont cette fonctionnalité fonctionne est que chaque fois que Gutenberg détecte qu’un type de bloc a enregistré au moins un style, la boîte "Styles" apparaîtra automatiquement dans la partie droite de l’éditeur. À l’intérieur, l’éditeur peut choisir entre le style par défaut ou n’importe quel style. style de bloc qui a été ajouté.

Dans les versions antérieures (au moins avant WordPress 5.3), l’enregistrement d’un style personnalisé vous obligeait également à enregistrer le style par défaut (« aucun style »). Heureusement, cela a été corrigé dans les versions les plus récentes de WordPress. Il ne vous reste plus qu’à enregistrer vos styles personnalisés et WordPress ajoutera automatiquement le style par défaut.

Vous pouvez enregistrer des styles de blocs personnalisés de deux manières ; avec PHP ou avec Javascript. Nous allons jeter un œil aux deux. Mais d’abord quelques a-ha concernant la gestion de vos styles.

Une note sur les styles de mise en file d’attente pour Gutenberg

Il peut y avoir une certaine confusion sur comment et où ajouter vos styles (fichiers CSS) ; à l’éditeur uniquement, à l’interface ou à une feuille de style pour les deux. L’un des principaux objectifs de l’éditeur Gutenberg est de s’assurer que vous pouvez correctement prévisualiser le contenu de votre publication dans l’éditeur. Il est donc recommandé de vous assurer que vos styles personnalisés sont appliqués dans l’éditeur ainsi que dans l’interface.

La façon dont vous gérez cela dépend vraiment de votre projet et de la configuration de la feuille de style existante. Si vous développez un thème complet, vous incluez probablement déjà le style de bloc dans votre feuille de style frontale. Vous pouvez envisager d’ajouter une feuille de style distincte que vous mettrez en file d’attente pour l’éditeur uniquement. Mais cela peut être difficile à maintenir si vous ajoutez beaucoup de styles différents. Vous devrez mettre à jour vos styles à deux endroits et vous assurer que leurs résultats sont les mêmes. La solution pour cela serait de conserver une feuille de style que vous mettez en file d’attente pour l’éditeur et l’interface. Mais alors votre frontend devrait charger au moins deux feuilles de style distinctes et ce n’est peut-être pas idéal.

Une autre solution consiste à utiliser, par exemple, SCSS ou LESS et à configurer @importsde telle manière que vous n’ayez besoin d’écrire vos styles de bloc qu’une seule fois, et cela s’applique à la fois à l’éditeur et à l’interface. Comme vous le verrez ci-dessous lorsque vous utilisez PHP pour enregistrer des styles de bloc personnalisés, vous avez encore une autre option ; pour ajouter des styles en ligne. Ces styles seront appliqués à la fois dans l’éditeur et dans l’interface. En frontend, ils seront ajoutés par WordPress en tant qu’inline personnalisé <style type="text/css">...</style>dans l’en-tête.

Quelle que soit la façon dont vous choisissez de le résoudre, sachez qu’il existe quelques nouveaux crochets pour les styles de registre (et les scripts) pour Gutenberg. Si vous souhaitez mettre en file d’attente une feuille de style pour le frontend et l’éditeur, utilisez le hook enqueue_block_assets. Si vous souhaitez ajouter une feuille de style uniquement pour l’éditeur, mettez-la en file d’attente dans le hook enqueue_block_editor_assets.

Comment appliquer un style sur les styles de blocs personnalisés

Les styles de bloc personnalisés seront ajoutés en tant que classe d’un certain modèle sur la balise HTML la plus externe du bloc.

La classe CSS pour les styles de bloc est ajoutée sous la forme de " is-style-<stylename>". Si vous nommez par exemple votre style " outline", le bloc obtiendra la classe " is-style-outline".

Cependant, vous constaterez peut-être que l’éditeur Gutenberg remplacera dans certains cas votre style. Je recommande de préfixer le style de votre éditeur avec le sélecteur editor-styles-wrapperpour vous assurer que vos styles «gagnent ». Gardez à l’esprit que cette classe n’existe pas en frontend, donc pour être sûr, vous devrez peut-être ajouter deux sélecteurs, comme ceci (si vous utilisez la même feuille de style pour l’éditeur et le frontend):

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

Ajouter des styles de blocs personnalisés avec PHP

Pour ajouter un type de bloc personnalisé à l’aide de PHP, nous utilisons la fonction [register_block_style](https://developer.wordpress.org/reference/functions/register_block_style/)(). La documentation manque malheureusement d’informations sur le crochet que nous devrions utiliser, mais j’ai eu de la chance avec le crochet init.

Vous devez connaître le nom de l’espace de noms Gutenberg de votre type de bloc afin d’y ajouter un style personnalisé. Tous les blocs standards de WordPress ont l’espace de noms " core" suivi d’un /et d’une version slug de leur nom. Par exemple, le nom de Gutenberg pour le bloc de paragraphe standard est core/paragraph.

L’enregistrement d’un style de bloc personnalisé se fait dans sa forme la plus simple comme ceci :

Le code ci-dessus ajoute un style de bloc personnalisé au type de bloc Titre, ce qui entraînerait la classe is-style-colored-bottom-bordersur tout titre ayant choisi ce style.

Cette fonction vous propose deux méthodes pour ajouter votre CSS (si vous ne l’avez pas ajouté d’une autre manière) ; soit en fournissant un CSS en ligne sous forme de chaîne, soit en fournissant un descripteur de feuille de style enregistré que WordPress mettra en file d’attente pour vous si nécessaire.

Si vous souhaitez ajouter un style en ligne (rappelez-vous, cela affectera à la fois l’éditeur et le frontend), ajoutez l’élément ‘ inline_style‘ à l’appel de fonction et écrivez le CSS complet sous forme de chaîne comme valeur :

Si vous préférez que la fonction mette en file d’attente une feuille de style, fournissez son handle à l’élément ‘ style_handle‘.

Ajustez l’emplacement de votre feuille de style en fonction de votre projet. La feuille de style sera appliquée à la fois à l’éditeur et à l’interface, mais cette fois l’interface fera une demande distincte pour inclure cette feuille de style. Cette méthode n’est pas recommandée si vous ajoutez plusieurs styles de blocs. Le frontend sera considérablement ralenti en demandant tout un tas de feuilles de style distinctes.

Ajout de styles de blocs personnalisés avec Javascript

Si vous préférez ajouter vos styles de bloc en utilisant Javascript, c’est aussi simple qu’avec PHP.

Vous devrez mettre en file d’attente un fichier Javascript sur le crochet de l’éditeur uniquement : enqueue_block_editor_assets. Votre script n’aura probablement pas besoin de dépendances, mais je préfère ajouter au moins ‘ wp-blocks‘ comme dépendance.

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

Ajustez le nom et l’emplacement du fichier en fonction de votre projet.

Dans votre fichier Javascript, vous utilisez la fonction registerBlockStyle()dans l’ wp.blocksobjet pour enregistrer des styles de bloc personnalisés. Ajouter le même style de bloc que nous avons fait en PHP ci-dessus ressemblerait à :

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

Et c’est tout! Très facile.

Désenregistrer les styles de bloc

Tout comme vous pouvez enregistrer un style de bloc, un style de bloc peut également être désenregistré. Peut-être souhaitez-vous supprimer certains des styles de blocs par défaut de WordPress? Comme pour l’enregistrement des styles de bloc, vous pouvez également désenregistrer les styles de bloc avec PHP ou Javascript. Mais le choix entre ces deux méthodes n’est plus un choix de préférence.

Vous ne pouvez pas désenregistrer un bloc avec PHP s’il a été enregistré avec Javascript, et vice versa. Vous devez donc déterminer comment le style que vous souhaitez supprimer a été enregistré et le faire correspondre avec PHP ou Javascript. Je crois que tous les styles de blocs de WordPress sont ajoutés avec Javascript (ne me citez pas là-dessus !). Donc, si vous souhaitez en supprimer certains, vous devrez suivre la route Javascript.

Désenregistrer un style de bloc avec PHP se fait en appelant la fonction unregister_block_style(), en fournissant le type de bloc et le nom du style que vous souhaitez supprimer. Par exemple, la désinscription du style ajouté ci-dessus dans cet article (en supposant qu’il a été enregistré avec PHP) ressemblerait à ceci :

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

La désinscription d’un style de bloc avec Javascript se fait de la même manière avec la fonction unregisterBlockStyle()dans l’ wp.blocksobjet. Cependant, avec Javascript, il y a une question de savoir quel script doit s’exécuter en premier, et vous pouvez rencontrer des problèmes lorsque votre script est exécuté avant l’enregistrement. Pour résoudre ce problème, nous utilisons l’équivalent de Gutenberg au "document prêt" de jQuery (jQuery(document).ready(function() { ... });), et ajoutons également une autre dépendance à votre script.

Commençons par ajouter une nouvelle dépendance de script sur votre fichier Javascript mis en file d’attente vers ‘ 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']
    );
});

Et à l’intérieur de votre fichier Javascript, encapsulez votre appel de fonction de désinscription dans wp.domReady(function() { ... }), comme ceci :

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

Comme le montre le code ci-dessus, avec Javascript, nous sommes maintenant en mesure de supprimer le style "Large" de WordPress sur le bloc Quote. Si vous essayez de faire la même chose avec PHP, cela ne fonctionnera pas.

Remarque sur la désinscription des styles de bloc

Vous remarquerez peut-être que même si vous avez réussi à supprimer tous les styles de bloc personnalisés sur un bloc, la case "Styles" de l’éditeur ne disparaîtra pas. Il reste en place avec seulement le choix "Par défaut" à l’intérieur. Si vous souhaitez supprimer complètement la case "Styles" pour ne pas confondre les éditeurs, vous pouvez simplement désenregistrer le style par défaut également (par exemple wp.blocks.unregisterBlockStyle('core/quote', 'large')). Cela supprimera complètement la case "Styles" de l’éditeur Gutenberg.