Vous êtes-vous déjà retrouvé dans la situation où vous souhaitez ajouter vos paramètres personnalisés aux blocs Gutenberg de WordPress? Dans cet article, nous allons détailler comment procéder. Vous trouverez deux exemples de code de cas d’utilisation réels d’ajout de paramètres personnalisés aux blocs de WordPress.

Gardez à l’esprit que parce que les blocs Gutenberg sont en Javascript, leur modification nécessite que vous écriviez le code en Javascript. Tout comme le code PHP de WordPress a des crochets et des filtres qui permettent aux développeurs de thèmes ou de plugins de modifier son code, il existe également des filtres dans le code Javascript de WordPress. Comme pour la [add_filter](https://developer.wordpress.org/reference/functions/add_filter/)()fonction PHP, nous avons la fonction Javascript [addFilter](https://developer.wordpress.org/block-editor/packages/packages-hooks/#api-usage)().

J’écrirai le code dans la syntaxe Javascript ES6, qui nécessite un compilateur pour le transformer. Vous pouvez écrire dans la syntaxe ES5 mais je vous recommande d’opter pour ES6/ESNext. J’ai un article qui explique comment configurer un transformateur pour ES6/ESNext. Je suppose également que vous avez une certaine familiarité avec React/JSX, peut-être une certaine expérience dans la création de vos propres blocs Gutenberg personnalisés.

Ce que vous pouvez filtrer sur les blocs Gutenberg

Il n’y a pas beaucoup de documentation sur les crochets et les filtres Gutenberg disponibles. Mais dans le but d’ajouter des paramètres personnalisés et de les appliquer d’une manière ou d’une autre sur des blocs existants ; c’est ce que j’ai trouvé jusqu’à présent. Je me suis concentré sur l’ajout de paramètres simples, et non sur des opérations qui nécessitent des changements drastiques de composants ou un comportement complexe.

Il y a trois étapes pour ajouter des paramètres personnalisés aux blocs existants :

Nous ajoutons un filtre sur le [registerBlockType](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/#registerblocktype)tableau de paramètres du bloc existant. Cela nous permet d’ajouter de nouveaux attributs au attributestableau, nous permettant ainsi d’enregistrer des informations supplémentaires sur le bloc. Nous devons enregistrer notre paramètre personnalisé quelque part.
Accrochez-vous au composant du bloc edit(le composant responsable du rendu du bloc dans l’éditeur). Dans ce crochet, nous pouvons nous accrocher à l’inspecteur (la barre latérale) et ajouter nos propres composants. Nous pouvons soit ajouter une nouvelle section/un nouveau panneau, soit nous accrocher à la section "Avancé" qui est toujours présente dans tous les blocs. Ensuite, c’est à nous de rendre les entrées de paramètres, telles que les entrées de texte, les cases à cocher ou autres.
saveFiltrez les accessoires du bloc. Nous pouvons ajuster les accessoires pour la sauvegarde, qui est responsable à la fois de la sauvegarde du bloc et de son rendu en frontend (en dehors de l’éditeur). Dans notre cas, nous voulons ajouter une classe ou un style en ligne.

Nous pouvons cibler un ou plusieurs blocs spécifiques ou tout cibler. Nous avons toujours accès au type de bloc auquel nous nous trouvons.

Pour le dire en d’autres termes : nous ajoutons des paramètres personnalisés dans l’inspecteur et les enregistrons dans les attributs personnalisés que nous avons ajoutés au bloc. Nous pouvons ensuite influencer le nom de la classe du bloc ou le style en ligne (dans certains cas), en fonction des attributs enregistrés. Avec les noms de classe personnalisés, nous pouvons facilement ajouter un CSS personnalisé qui donne visuellement un effet à nos paramètres.

Ce qu’on ne peut pas faire (pour l’instant ?)

Malheureusement, il y a certaines choses auxquelles nous ne pouvons pas accéder avec des filtres sur des blocs existants. En ce qui concerne l’ajout de paramètres personnalisés simples aux blocs, ce sont des choses courantes que nous ne pouvons pas affecter.

Pas d’accès au style en ligne du bloc dans l’éditeur

Dans certains cas de paramètres affectant la conception d’un bloc, nous devons ajouter un style en ligne sur le nœud d’habillage du bloc. Juste le nom de la classe ne suffira pas. Par exemple, si vous ajoutez un paramètre de couleur personnalisé et que l’utilisateur sélectionne une couleur personnalisée (à partir du sélecteur de couleurs), vous ne pouvez pas résoudre ce problème en ajoutant une classe – vous avez besoin d’un style en ligne.

Malheureusement, il semble que les blocs par défaut de WordPress gèrent le style en ligne dans l’éditeur de manière totalement indépendante, sans possibilité de filtrage ou de «connexion ». Je vais montrer un moyen de contourner cela dans le dernier exemple ci-dessous, mais ce n’est pas idéal dans tous les cas.

Pourquoi se soucier que le bloc ait un aspect différent dans l’éditeur par rapport à l’interface, vous pouvez demander ? L’intérêt de Gutenberg est de mettre en œuvre une manière visuelle d’éditer le contenu où ce que nous voyons est réellement ce que nous obtenons. Nous voulons obtenir le même aspect visuel à la fois dans l’éditeur et dans l’interface.

Certains blocs n’incluent pas le nom de la classe dans l’éditeur

Comme mentionné ci-dessus, nous pouvons filtrer le nom de la classe d’emballage du bloc car il s’agit d’un prop qui est transmis à tous les blocs Gutenberg. Mais malheureusement, certains blocs n’appliquent pas du tout la classe du bloc dans edit. Un exemple est le bloc Cover. J’ai beaucoup joué en utilisant les blocs Cover comme "sections" pour les pages d’accueil, et je continue à rencontrer des problèmes car le bloc Cover construit sa propre classe à l’intérieur de edit. Il ignore complètement la classe "globale" du bloc (qui est celle à laquelle nous avons accès via des filtres).

Mais au moins, nous pouvons être sûrs que les noms de classe filtrés sont toujours appliqués dans save(frontend). Cela se produit automatiquement en dehors du code spécifique de chaque bloc.

Si je me trompe sur l’un des points ci-dessus, S’IL VOUS PLAÎT, faites-le moi savoir dans les commentaires ci-dessous! J’apprends continuellement Gutenberg, et en même temps Gutenberg évolue également. J’espère qu’à un moment donné ce qui précède sera possible à un moment donné ou que c’est possible, mais il me manque juste des informations cruciales !

Avec cela à l’écart, commençons à examiner du code.

Exemple 1 : Ajouter un champ bascule pour masquer un bloc Couverture sur mobile

Supposons que nous développions un thème où les blocs de couverture seront utilisés pour les "sections" sur la page d’accueil. Et nous voulons offrir à l’utilisateur la possibilité de masquer une certaine section du mobile. Pour résoudre ce problème, nous pouvons ajouter un champ de basculement dans la section "Avancé" de l’inspecteur du bloc Cover. Si le champ est activé, le bloc Couverture obtiendra une classe personnalisée supplémentaire que nous pouvons cibler avec des requêtes CSS et multimédia.

Au fait : il s’agit d’un cas où le problème du bloc Cover qui n’applique pas nos noms de classe personnalisés dans l’éditeur est en fait un avantage ! Imaginez si c’était le cas; alors il serait impossible pour l’utilisateur d’éditer le bloc dans l’éditeur s’il a un petit écran !

Comme mentionné précédemment, il y a trois étapes pour lesquelles nous devons coder. Nous devons également ajouter du PHP pour mettre en file d’attente notre fichier Javascript dans l’éditeur. Faisons cela d’abord.

Ajout de notre script à l’éditeur

Nous accrochons une fonction à l’action [enqueue_block_editor_assets](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/). Dans notre fonction, nous mettons un script en file d’attente, comme nous le ferions habituellement dans 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']);
});

N’oubliez pas d’ajuster le chemin d’accès à l’endroit où se trouve votre script ! Remarque: Si vous écrivez dans ES6 avec webpack compilant votre Javascript, n’oubliez pas de définir le chemin vers la construction de votre script, pas la source.

J’aime ajouter ‘ wp-edit-post‘ comme dépendance au script pour m’assurer qu’il se charge suffisamment tard.

C’est tout le PHP que nous devons faire. Le reste est écrit dans notre fichier Javascript.

Ajouter un attribut personnalisé

Le premier filtre que nous utiliserons est l’objet de paramètres des blocks.registerBlockTypefiltres .registerBlockType

Mais d’abord, un peu sur l’ajout de filtres en Javascript. Comme je n’ai pas trouvé de bonne documentation pour cela, je vais l’expliquer un peu ici. La fonction addFilterest dans l’ espace de wp.hooksnoms et accepte quatre arguments.

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

Le premier paramètre, ‘hookName’, est le nom du filtre auquel nous voulons nous accrocher. C’est l’équivalent du premier paramètre lors de l’utilisation de PHP add_filter(). Le deuxième paramètre, ‘namespace’, est un nom d’espace de noms personnalisé pour votre code. C’est juste pour éviter la collision de noms. Vous pouvez à peu près définir tout ce que vous voulez ici, mais n’utilisez pas l’espace de noms de WordPress (‘wp’). Utilisez une forme abrégée de votre nom ou du nom du projet. Le troisième paramètre, ‘functionName’, est la fonction hookée – qui est la même que le add_filter()deuxième argument de PHP. Et enfin le quatrième paramètre, ‘priorité’, est facultatif. Encore une fois, c’est la même chose que le add_filter()troisième argument de PHP.

Le processus pour les filtres en Javascript est le même qu’en PHP. Nous définissons une fonction qui doit renvoyer la variable filtrée. Parfois, la variable est une chaîne, un objet ou un composant. À l’intérieur de la fonction, nous modifions la variable comme bon nous semble.

Dans notre cas, nous voulons ajouter un nouvel attribut à l’ attributeobjet du bloc. Nous appellerons le nouvel attribut hideOnMobileet définirons son type sur boolean. Cela se fait comme ceci :


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
);

À la ligne, #3nous nous assurons de cibler uniquement les blocs de type ‘ core/cover‘. Le deuxième argument à blocks.registerBlockTypefiltrer est assez commodément le nom du bloc. Nous ajoutons ensuite un nouvel objet à l’ settings.attributesobjet. Enfin, nous nous assurons de renvoyer la variable filtrée, settings.

À ce stade, visuellement, rien n’a changé à Gutenberg. Mais tous les blocs de couverture ont maintenant un attribut supplémentaire que nous pouvons utiliser pour stocker notre réglage.

Ajouter un paramètre à l’inspecteur (panneau Avancé)

Le deuxième filtre est appelé editor.BlockEditet filtre le composant du bloc edit. Ce filtre reçoit le composant du bloc d’origine BlockEditet renvoie un nouveau composant enveloppé. Nous devons utiliser wp.compose.createHigherOrderComponentpour retourner le composant enveloppé.

À l’intérieur de notre composant, nous nous assurons de rendre le composant enveloppé BlockEdit, peu importe. Mais si le bloc est de type Cover, nous nous accrochons également au composant InspectorAdvancedControls(qui est le panneau "Avancé" dans Inspector) et ajoutons un fichier ToggleControl. Nous écrivons le ToggleControlpour afficher la valeur de et mettons à jour l’attribut personnalisé que nous avons ajouté précédemment, hideOnMobile.

N’oubliez pas de toujours retourner l’original BlockEdit, ce que nous faisons à line #9. À la ligne 10, nous vérifions si le type de bloc est Cover et rendons le InspectorAdvancedControlscomposant. À l’ intérieur, nous ajoutons un ToggleControl, qui est un contrôle d’entrée qui s’affiche sous la forme d’une bascule entre vrai ou faux. Nous définissons une étiquette et connectons sa valeur à l’ hideOnMobileattribut. Si vous avez déjà ajouté des paramètres à Inspector, cela devrait être assez simple pour vous.

Avec le code ci-dessus, nous devrions maintenant obtenir ceci dans le panneau "Avancé" de l’inspecteur sur les blocs de couverture :

L’entrée va maintenant mettre à jour notre attribut personnalisé hideOnMobile. La dernière étape consiste à faire quelque chose en fonction de la valeur de cet attribut. À l’heure actuelle, l’attribut est enregistré, mais n’affecte en fait rien.

Ajouter une classe personnalisée

La dernière étape consiste à ajouter une classe personnalisée à la classe du bloc. Nous faisons cela avec le filtre blocks.getSaveContent.extraProps. Ce filtre affecte les accessoires du composant du bloc save. L’un d’eux est le prop className, qui sera toujours appliqué au frontend. Nous ajoutons simplement notre classe personnalisée après si l’attribut était true, puis nous le renvoyons. J’ai décidé d’ajouter une classe ‘ hide-on-mobile‘, mais vous pouvez l’appeler comme vous le souhaitez.

Ce code est assez explicite. À la ligne, #4nous vérifions si l’attribut hideOnMobileexiste et est true. Si tel est le cas, nous ajoutons une classe personnalisée à la classNamechaîne.

Avec les trois filtres ci-dessus, nous devrions maintenant obtenir une classe personnalisée "hide-on-mobile" appliquée à notre bloc Cover chaque fois que le paramètre est activé.

Il ne reste plus qu’à ajouter du CSS à la feuille de style frontale de votre thème. Quelque chose comme ça;


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

Exemple 2 : Ajouter un panneau Inspecteur avec un paramètre de couleur d’arrière-plan personnalisé pour le bloc Spacer

Pour le deuxième cas d’utilisation, nous voulons ajouter des paramètres de couleur personnalisés au bloc Spacer. Par défaut, le bloc Spacer n’a pas d’autres paramètres que sa hauteur. Supposons que nous voulions ajouter une couleur d’arrière-plan qui colorie toute la hauteur du bloc Spacer. Cela permet à l’utilisateur d’ajouter des "bandes" vides et colorées à l’intérieur de son contenu. Dans ce cas, nous souhaitons ajouter les paramètres de couleur dans son propre panneau séparé dans l’inspecteur, conformément au comportement habituel attendu pour les paramètres de couleur.

Remarque : La gestion des couleurs est un peu plus compliquée car nous devons utiliser un (autre) composant d’ordre supérieur withColors. Parce que nous devons déjà implémenter un composant d’ordre supérieur dans le editor.BlockEditnous avons besoin de composeplusieurs composants. De plus, nous devons ajouter deux attributs pour chaque paramètre de couleur. L’un contiendra le slug de la palette de couleurs et l’autre contiendra le code de couleur hexadécimal – uniquement si l’utilisateur a opté pour une couleur personnalisée (utilisé le sélecteur de couleurs). C’est un comportement courant lorsque vous travaillez avec withColors. J’ai un <a href="https://wordpress.mediadoma.com/fr/comment-ajouter-des-parametres-de-couleur-a-votre-bloc-gutenberg-personnalise/" title="article qui explique l'ajout de paramètres de couleur et withColorsen détail” >article qui explique l’ajout de paramètres de couleur et withColorsen détail si vous êtes confus.

Deuxièmement, nous allons dans ce cas rencontrer le problème expliqué ci-dessus; où nous ne pouvons pas ajouter le style en ligne approprié à l’éditeur. La solution pour laquelle j’ai opté dans ce cas est d’envelopper le bloc Spacer à l’intérieur d’un divdans l’éditeur et d’appliquer les classes et le style en ligne appropriés au wraping div. Cela rend la couleur sélectionnée visible dans l’éditeur lorsque le bloc est désélectionné. Cependant, lors de la sélection du bloc, WordPress ajoute son propre arrière-plan gris clair personnalisé au bloc, couvrant notre couleur d’arrière-plan personnalisée. Un CSS à l’éditeur résoudra ce problème. J’expliquerai plus à la fin.

Les étapes sont les mêmes que dans l’exemple ci-dessus. Nous mettons d’abord notre script en file d’attente dans l’éditeur en PHP. Ensuite en Javascript on filtre l’ attributesobjet, le editcomposant du Spacer et enfin le savecomposant du Spacer.

Ajout de notre script à l’éditeur


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']);
});

N’oubliez pas d’ajuster le chemin d’accès à votre script. J’aime ajouter ‘ wp-edit-post‘ comme dépendance au script pour m’assurer qu’il se charge suffisamment tard.

C’est tout le PHP que nous devons faire. Le reste est écrit dans notre fichier Javascript.

Ajouter des attributs personnalisés

Comme dans l’exemple ci-dessus, nous ajoutons un filtre sur blocks.registerBlockTypeafin d’ajouter des éléments d’objet supplémentaires à l’objet du bloc attributes.

Lorsque vous travaillez avec, withColorsnous devons ajouter deux attributs pour chaque couleur. Le nom de notre attribut de couleur d’arrière-plan est backgroundColor, ce qui signifie que le deuxième attribut doit être nommé customBackgroundColor. Tout cela est expliqué dans mon article sur la gestion des paramètres de couleur dans Gutenberg. Les deux doivent être de type string et appliqués uniquement aux blocs de type 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
);

Ajouter le panneau ColorSettings à l’inspecteur

La deuxième étape consiste à ajouter un panneau de paramètres de couleur à l’inspecteur pour le bloc Spacer en filtrant editor.BlockEdit.

Nous devons utiliser composepour combiner le composant d’ordre supérieur renvoyé par ce filtre et withColors. En d’autres termes, nous encapsulons simplement le composant renvoyé dans withColors. En paramètre, withColorsnous fournissons notre attribut backgroundColor.

À l’intérieur du composant enveloppé, nous nous assurons de toujours revenir BlockEdit(ligne #9et #39pour les blocs Spacer). Pour les blocs de type Spacer, nous nous accrochons également InspectorControlspour ajouter un PanelColorSettingspour notre choix de couleur. Il s’agit de la procédure standard d’ajout de paramètres de couleur.

À la ligne, #17 - 34nous générons manuellement la classe nécessaire et/ou le style en ligne. Ensuite, à la ligne, #38nous ajoutons un div enveloppant BlockEditavec ces classes et ces styles en ligne.

Le résultat est un nouveau panneau de paramètres de couleur dans l’inspecteur pour les blocs Spacer, entièrement fonctionnel.

Le choix d’une couleur de palette ou d’une couleur personnalisée sera en effet affecté dans la div d’habillage à l’intérieur de l’éditeur. Mais vous ne pouvez le voir que lorsque vous désélectionnez le bloc Spacer !

Cela se produit parce que WordPress applique son propre style lors de la sélection d’un bloc d’espacement. Nous le corrigerons à la fin, nous avons d’abord juste besoin d’appliquer la même classe et/ou le même style en ligne dans le frontend.

Ajoutez une classe personnalisée et un style en ligne pour enregistrer

Enfin, nous devons filtrer blocks.getSaveContent.extraPropset appliquer la classe nécessaire et/ou le style en ligne pour le frontend. Encore une fois, cela est très similaire à ce que nous avons fait dans l’exemple 1 ci-dessus. Si une couleur de palette a été choisie, nous devons ajouter un nom de classe qui suit les normes de WordPress pour les paramètres de couleur (" has-<PALETTESLUG>-background-color"). Si une couleur personnalisée a été choisie, nous devons ajouter un style en ligne avec la couleur hexadécimale.

Remarque : Si vous devez beaucoup gérer les noms de classe, je vous recommande d’importer la classnamesbibliothèque. Ceci est fortement utilisé dans Gutenberg car cela simplifie considérablement la définition des noms de classe appropriés. Le code ci-dessous suppose que vous ne l’avez pas fait et compose le nom de la classe manuellement.


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
);

Avec le code ci-dessus, l’interface rendra désormais parfaitement les blocs Spacer avec notre choix de couleur personnalisé !

Le correctif final (facultatif) consiste à ajouter du CSS à l’éditeur. Vous devrez soit ajouter du CSS en ligne, soit une feuille de style d’éditeur. Par exemple, vous pouvez mettre en file d’attente une feuille de style dans le même crochet PHP que nous avons utilisé pour mettre en file d’attente notre fichier Javascript. Je n’entrerai pas dans les détails sur la façon de procéder; mais le CSS dont vous aurez besoin est quelque chose comme ci-dessous. Tout ce qu’il fait est de définir l’espaceur background-colorsur la couleur héritée (il héritera de notre div d’emballage) lorsque le bloc est sélectionné :


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

PS: Gardez à l’esprit que cela est susceptible de changer à l’avenir. Gutenberg est toujours en pleine évolution.

Conclusion

Dans cet article, nous avons appris deux méthodes pour implémenter des paramètres personnalisés dans les blocs WordPress Gutenberg existants. C’est tout à fait possible pour des paramètres simples qui ne nécessitent peut-être qu’une classe ou un style en ligne. Nous avons examiné les mises en garde, qui, je l’espère, seront corrigées dans les versions ultérieures de Gutenberg !

Source d’enregistrement: awhitepixel.com