Ajouter une barre latérale d’inspecteur personnalisé dans WordPress Gutenberg avec Post Meta

Dans ce didacticiel, nous verrons comment ajouter une barre latérale personnalisée à l’inspecteur (barre latérale droite) dans WordPress Gutenberg. À l’intérieur, nous allons implémenter un champ connecté à une méta post. Tout est implémenté avec Javascript, dans l’éditeur Gutenberg, et constitue une alternative à l’ajout de métaboxes de manière traditionnelle.

La tête haute!

Ceci est un tutoriel pour créer votre propre barre latérale personnalisée. Mais si vous souhaitez simplement ajouter des méta/paramètres à la barre latérale standard de l’inspecteur (onglet "Document"), j’ai un tutoriel pour cela :

Ce que nous allons créer

WordPress Gutenberg permet aux développeurs de créer des barres latérales personnalisées en créant un plugin dit Javascript. (À ne pas confondre avec les plugins WordPress traditionnels). En utilisant un plugin Javascript, nous pouvons créer une nouvelle barre latérale et également nous connecter au menu "Outils et options".

Nous ajouterons un nouvel élément de menu dans les "Outils" qui ouvrira notre barre latérale personnalisée. Le contenu de la barre latérale dépend entièrement de vous, mais je vais passer en revue quelques exemples, y compris comment connecter un champ méta post à l’intérieur.

Configuration de votre Javascript

Pour ce tutoriel, j’écrirai ES6/ESNext Javascript avec JSX, ce qui signifie que nous devons configurer un compilateur. Si vous souhaitez suivre et ne pas écrire de Javascript ES5, vous devrez configurer un environnement de développement qui compile votre Javascript au fur et à mesure. Si vous n’êtes pas familier avec cela, suivez mon article expliquant comment le configurer, puis revenez ici.

J’ai configuré mon webpack.config.jspour compiler mon fichier Javascript source dans le dossier /assets/js/sidebar-plugin.js. Ce fichier compilé est ce dont nous avons besoin pour mettre en file d’attente l’éditeur Gutenberg. Pendant que j’écris ce code, j’ai démarré le compilateur d’exécution qui recompile le Javascript à chaque fois que j’enregistre des modifications dans le code source (npm run start). Tout cela est expliqué en profondeur dans le tutoriel mentionné précédemment.

J’écris ceci dans un thème, mais cela fonctionne de la même manière dans un plugin. N’oubliez pas d’ajuster les chemins lors de l’ajout du script à l’éditeur.

Ajout du script à l’éditeur

Pour ajouter notre script à l’éditeur Gutenberg, nous devons écrire du PHP. Si vous êtes dans un thème, functions.phpc’est un bon endroit pour commencer, ou quelque part dans vos fichiers de plugin. Notez que nous devons ajouter le script compilé final, pas le code source. Dans mon exemple, le Javascript compilé se trouve dans le dossier /assets/js/sidebar-plugin.js.

Nous créons une fonction accrochée à enqueue_block_editor_assets. A l’intérieur on fait comme d’habitude [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)(). En tant que dépendances au script, nous en ajoutons deux ; wp-plugins, et wp-edit-post. Ces deux packages doivent être chargés avant notre script car nous utilisons leurs fonctions.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script('awp-sidebar-plugin', get_stylesheet_directory_uri(). '/assets/js/sidebar-plugin.js', ['wp-plugins', 'wp-edit-post']);
});

Parce que nous mettons le script en file d’attente dans le crochet enqueue_block_editor_assets, notre script ne sera chargé que lorsque l’éditeur Gutenberg est actif. Super! Maintenant tout est prêt pour écrire notre plugin Javascript.

Enregistrer un plugin Javascript

La première étape consiste à enregistrer un plugin. Nous faisons cela avec la [registerPlugin](https://github.com/WordPress/gutenberg/tree/master/packages/plugins#registerPlugin)fonction dans wp.plugins à l’intérieur du wp.pluginspackage.

En tant que paramètre du registerPlugin, nous fournissons un nom (assurez-vous qu’il est unique) et un objet avec des paramètres. Au minimum, vous devez fournir un composant pour la propriété de rendu. Vous pouvez également éventuellement ajouter une icône à partir des dashicons de WordPress. Gardez à l’esprit que si vous ne spécifiez pas d’icône, il reviendra à l’icône du plugin. À des fins de démonstration, j’utilise l’ 'carrot'icône .

En ce qui concerne le composant, nous commençons par définir un composant de base qui renvoie un simple div contenant du texte aléatoire. Et avant tout le code nous déstructurons les fonctions des packages que nous voulons utiliser.

Si rien ne se passe (pas même des erreurs) lorsque vous actualisez Gutenberg, nous sommes tous prêts à partir. Nous ne voyons pas notre composant car nous n’avons pas indiqué à WordPress où le rendre. La prochaine étape consiste à s’accrocher au menu de la barre latérale personnalisée et aux composants du menu des outils pour rendre nos éléments.

Enregistrer une barre latérale personnalisée

Mais d’abord une explication sur la façon dont Gutenberg gère les barres latérales personnalisées et pourquoi nous devons faire ce que nous ferons. Lorsque nous enregistrons avec succès une barre latérale personnalisée, une chose se produit automatiquement au départ. Gutenberg ajoutera un raccourci à notre barre latérale dans la barre d’outils supérieure, à côté du menu Outils. Cela se produit parce que notre barre latérale est automatiquement "épinglée".

Le problème d’ajouter simplement une barre latérale personnalisée est que n’importe quel utilisateur peut "détacher" ce raccourci. Quand ils font cela, il n’y a plus de point d’accès pour ouvrir à nouveau la barre latérale ! C’est pourquoi nous devons également ajouter un élément de menu au menu Outils.

L’enregistrement d’une barre latérale personnalisée se fait avec le composant PluginSidebardu wp.editPostpackage. L’ajout d’un élément de menu au menu Outils se fait avec le composant bien nommé PluginSidebarMoreMenuItem(également dans le wp.editPostpackage).

Pour le PluginSidebarcomposant, nous devons fournir des accessoires. Vous devez fournir au minimum nameet title. L’accessoire titleest explicite, c’est le nom qui apparaîtra en haut de la barre latérale. Dans l’accessoire name, fournissez une limace unique. Lorsque vous ajoutez l’élément de menu, vous devez vous référer à ce slug.

L’ajout d’un PluginSidebarMoreMenuItemcomposant (menu outils) nécessite au minimum un accessoire ; target. Ici, vous fournissez le même nom que celui que vous avez donné dans la nameprop de la barre latérale. Comme contenu du composant, vous écrivez le texte qui sera affiché comme élément de menu. Habituellement, ce serait le même que celui de la barre latérale title.

Étant donné que React nécessite un seul nœud d’emballage autour du retour du composant, nous encapsulons tout dans un Fragmentcomposant (à partir du wp.elementpackage). J’emballe également mes chaînes à __()partir du wp.i18npaquet pour permettre la traduction.

Avec le code ci-dessus, nous obtiendrons les deux (très probablement trois) choses suivantes. Vous obtiendrez un raccourci d’icône de carotte dans la barre d’outils (si vous ne l’avez pas encore retiré). Cliquer dessus ouvrira la barre latérale. Vous aurez également un nouvel élément de menu dans la barre latérale du menu Outils, sous le titre "Plugins".

Ajouter du contenu à la barre latérale

Le contenu réel de la barre latérale dépend entièrement de vous. Vous avez juste besoin d’ajouter du HTML ou des composants à l’intérieur du PluginSidebarcomposant avec ce que vous voulez (à la place du texte "Hello there.").

Vous remarquerez peut-être que le contenu de la barre latérale manque de rembourrage. Ceci est intentionnel car l’idée est que vous allez créer des panneaux à l’intérieur de cette barre latérale. Les panneaux sont les sections pliables de la barre latérale normale de Gutenberg. Ce sont des composants que vous pouvez très facilement ajouter dans votre barre latérale personnalisée. Vous pouvez ajouter autant de panneaux que vous le souhaitez et ils sont parfaits pour regrouper différentes choses.

Ajout de panneaux dans notre barre latérale

Voyons rapidement comment nous pouvons ajouter des panneaux à notre barre latérale. Si vous avez créé vos propres types de blocs personnalisés, vous connaissez peut-être ces composants. Nous utilisons PanelBodyet éventuellement PanelRowà partir du wp.componentspackage.

Pour un PanelBodycomposant vous fournissez au minimum le prop title. Vous pouvez éventuellement fournir true ou false à la initialOpenprop pour décider si le panneau doit être développé par défaut ou non. Comme le contenu à l’intérieur du composant est tout à l’intérieur du panneau.

À l’ intérieur d’un PanelBody, vous pouvez éventuellement utiliser des PanelRowcomposants. Ils ne sont pas vraiment nécessaires mais peuvent vous aider à obtenir un bon style pour le contenu de votre panneau.

Par exemple, ajoutons deux panneaux à notre barre latérale personnalisée.

Avec ce code, notre barre latérale personnalisée commence vraiment à ressembler à Gutenberg !

Ajout de champs post-méta à la barre latérale personnalisée

Maintenant, nous entrons vraiment dans le vif du sujet des éléments utiles pour une barre latérale personnalisée ; ajouter des paramètres et stocker leurs valeurs. Mais nous devons d’abord comprendre comment.

Il est très facile d’ajouter des champs de paramètres (entrées, cases à cocher, champs de basculement, etc.) dans la barre latérale en utilisant les composants prêts à l’emploi des packages WordPress. Cependant, nous devons considérer comment stocker les valeurs. L’option évidente est de les stocker en tant que post méta. Mais connecter un paramètre à un champ post-méta nécessite du code supplémentaire. Plus précisément, nous devons utiliser des composants dits d’ordre supérieur afin de récupérer et de mettre à jour la méta post dans Javascript. Nous devons également enregistrer chaque méta de publication à l’aide de PHP et les rendre disponibles pour l’API REST.

Pour terminer ce didacticiel, je vais vous montrer comment ajouter une méta post avec une clé awp_my_custom_metaqui doit être stockée comme vraie ou fausse. Dans la barre latérale, il sera affiché sous la forme d’un champ bascule (un composant vrai/faux).

Enregistrer la post-méta pour l’API REST

La première étape pour ajouter des post-méta dans notre fichier Javascript consiste à les enregistrer et à les définir comme accessibles dans l’API REST. Pour ce faire, nous revenons à nouveau à PHP.

À l’intérieur d’une fonction accrochée à l’ initaction, nous utilisons la [register_meta](https://developer.wordpress.org/reference/functions/register_meta/)()fonction. En tant que paramètres, nous devons définir le type d’objet comme ‘ post‘ car nous l’utilisons comme post meta (cela n’exclut pas, par exemple, le type de publication de page). Nous fournissons la clé méta, puis un tableau d’arguments. La chose critique à ajouter dans le tableau d’arguments est de définir ‘ show_in_rest‘ sur true. Post meta est couramment utilisé comme ‘ single‘ (pensez à la façon dont vous utilisez get_post_meta()). Nous définissons également le type. Quant à notre cas, nous l’avons défini sur ‘ boolean‘.

Avec ce code, le awp_my_custom_metachamp méta ‘ ‘ post est accessible depuis Gutenberg. Vous devez répéter la register_meta()méta pour chaque publication que vous souhaitez ajouter dans votre barre latérale.

Revenons maintenant à notre Javascript.

Ajouter un paramètre à notre barre latérale

Commençons par la partie la plus facile : ajouter l’entrée à notre barre latérale. Plus tard, nous ajouterons plus de code pour connecter réellement le champ de configuration à la publication de méta. En raison de la façon dont nous devons procéder, nous définissons un nouveau composant distinct pour notre environnement. Ainsi, à l’intérieur du panneau auquel vous souhaitez ajouter vos paramètres, appelez simplement ce nouveau composant.

Appelons le composant CustomSidebarMetaComponent(vous pourriez l’appeler quelque chose de pertinent pour votre projet). À l’intérieur de ce composant, nous voulons rendre un champ bascule. Pour ce faire, nous utilisons le ToggleControlcomposant du wp.componentspackage. En tant qu’accessoires du ToggleControl, nous fournissons une étiquette appropriée dans l’ titleaccessoire. Un ToggleControl a également besoin des accessoires onChangepour mettre à jour la valeur et checkedpour la valeur actuelle. Nous allons omettre ces deux pour l’instant jusqu’à la prochaine étape.

Avec le code ci-dessus, vous devriez obtenir un champ bascule dans la barre latérale. Il n’est pas coché et rien ne se passe lorsque vous cliquez dessus. C’est la prochaine étape: le connecter à notre post meta.

Accéder à la méta post avec withSelect et withDispatch

Afin d’accéder et de mettre à jour une méta-valeur de publication, nous devons utiliser des composants d’ordre supérieur (HOC) pour accéder à la version des magasins WordPress (similaire à Redux). WordPress nous fournit quelques HOC utiles avec des fonctions que nous pouvons utiliser dans le wp.datapackage.

Le composant d’ordre supérieur [withSelect](https://developer.wordpress.org/block-editor/packages/packages-data/#withSelect)fournit à notre composant des accessoires qui sont, dans notre cas, extraits de la post méta. Nous l’utilisons pour obtenir la valeur de notre post meta. À l’ intérieur withSelect, nous pouvons utiliser select('core/editor').getEditedPostAttribute('meta')pour récupérer la méta du message actuel.

D’autre part, [withDispatch](https://developer.wordpress.org/block-editor/packages/packages-data/#withDispatch)est un composant d’ordre supérieur qui peut effectuer des actions. Dans notre cas, nous souhaitons mettre à jour la méta de la publication lorsque le paramètre de champ correspondant est modifié dans notre barre latérale. À l’intérieur de ce composant, nous utilisons dispatch('core/editor').editPost()pour informer WordPress d’envoyer une action. À l’intérieur de l’objet que nous fournissons, nous disons à WordPress que c’est la méta que nous voulons mettre à jour.

Enfin, nous devons combiner withSelectet withDispatchavec notre composant qui gère le post méta champ (CustomSidebarMetaComponent). Pour ce faire, nous utilisons WordPress’ composedu wp.composepackage. L’idée est que withSelectet withDispatchfournit à notre CustomSidebarMetaComponentcomposant des accessoires. withSelectfournit la valeur de la post meta en tant que prop, et withDispatchfournit une fonction que nous pouvons appeler pour mettre à jour la valeur en tant que prop. Nous définissons ces accessoires sur notre ToggleField checkedet onChange, en conséquence.

C’est beaucoup d’explications. Regardons le code réel :

Commençons par le début. Qui est en bas. À la ligne, #36nous changeons le composant que nous rendons dans notre barre latérale pour le composant que nous avons créé avec compose(à la ligne #15). Le CustomSidebarMetacomposant combinera les composants withSelectet withDispatchet renverra le CustomSidebarMetaComponent.

Le CustomSidebarMetaComponentaura accès à l’ customPostMetaValueaccessoire de withSelect, et à l’ setCustomPostMetaaccessoire de withDispatchCes deux nous nous utilisons pour les accessoires checkedet dans le .onChange``ToggleField

Notez qu’en ligne, #5nous ajoutons des propsparamètres aux composants pour rendre les accessoires accessibles dans le composant.

Conclusion et derniers mots

J’espère que ce tutoriel vous a été utile. C’est ce que j’ai réussi à comprendre sur le sujet au cours de nombreux essais et erreurs. Il n’y a pratiquement aucune documentation sur ce sujet pour le moment. J’ai toujours du mal avec cela, en particulier lorsqu’il s’agit de gérer efficacement plusieurs post-méta. Si je parviens à apprendre quelques bonnes astuces, je mettrai à jour ce tutoriel à coup sûr!

Espérons qu’en suivant ce didacticiel, vous devriez avoir un code qui ajoute avec succès une nouvelle barre latérale personnalisée à l’éditeur WordPress Gutenberg, et, espérons-le, avec du contenu et des paramètres significatifs. Voici le code final pour la barre latérale personnalisée avec le champ post meta.