Comment ajouter des champs méta de publication à la barre latérale du document Gutenberg
Dans cet article, nous verrons comment ajouter des paramètres méta de publication personnalisés à la barre latérale Gutenberg, dans l’onglet "Document", plutôt que de compter sur l’ajout de boîtes méta de la manière traditionnelle (et très honnêtement beaucoup plus manuelle).
Si vous avez travaillé avec WordPress un certain temps avant que Gutenberg ne soit une chose, vous êtes probablement familier avec l’ajout d’une méta de publication personnalisée avec [add_meta_box](https://developer.wordpress.org/reference/functions/add_meta_box/)(). Cette fonction vous permet d’ajouter une boîte méta avec votre contenu personnalisé soit en bas, soit sur le côté lors de l’édition d’un article. Cette méthode fonctionne toujours, également dans l’éditeur Gutenberg !
Cependant, il semble un peu décalé par rapport au reste du contenu de la barre latérale de Gutenberg. Et sans oublier, vous auriez besoin d’écrire manuellement le code d’entrée (case à cocher, entrées de texte, etc.) avec PHP et également d’écrire du code supplémentaire pour les enregistrer lorsque le message est mis à jour. Et si vous vouliez que vos paramètres post-méta soient dynamiques (disons que vous vouliez masquer un champ à moins qu’un autre champ ne soit activé), alors vous devriez mettre manuellement un script en file d’attente et oui, vous l’avez deviné, gérer manuellement la logique dynamique de cacher et de montrer. Tout cela est désormais obsolète et simplifié grâce au nouvel éditeur Gutenberg basé sur Javascript. On peut assez facilement faire quelque chose comme ça :
Le processus
Le processus est le suivant :
- Nous enregistrons chaque clé méta de publication personnalisée que nous voulons ajouter en PHP à l’aide de
[register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/)(), et la définissons comme disponible dans l’API WP REST. Il s’agit d’une étape nécessaire pour rendre la méta de publication disponible dans l’éditeur Gutenberg. - Nous créons un fichier Javascript et le mettons en file d’attente spécifiquement pour l’éditeur (uniquement).
- Dans le fichier Javascript, nous enregistrons un plugin en
[registerPlugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-plugins/#registerPlugin)()lui disant de rendre notre composant. - À l’intérieur de ce composant, nous pouvons produire tout ce dont nous avons besoin. Nous pouvons utiliser les composants intégrés de WordPress pour rendre facilement différents types de paramètres. Et en utilisant le package de données WordPress, nous pouvons récupérer et mettre à jour les méta-valeurs de publication immédiatement au fur et à mesure qu’elles sont modifiées.
Allons droit au but, en commençant par la partie PHP ; enregistrement de la post méta.
Enregistrement de post-méta
Pour chaque méta post que vous souhaitez ajouter à la barre latérale de Gutenberg, vous devrez vous inscrire en utilisant [register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/)(). Cela est nécessaire pour les rendre disponibles via l’API WP REST (que Gutenberg utilise) et donc disponibles dans notre Javascript.
Dans le fichier de votre thème functions.phpou dans un autre fichier PHP actif, ajoutez une fonction accrochée au crochet ‘ init‘. Dans la fonction, vous répétez a register_post_meta()pour chaque méta de publication personnalisée que vous souhaitez ajouter. La fonction prend trois arguments ; Le premier paramètre est le type de publication pour lequel vous souhaitez enregistrer la méta (défini comme chaîne vide pour tous les types de publication). Le deuxième paramètre est le nom de la clé méta pour votre méta. Et le troisième est un tableau de paramètres. C’est ici que nous définissons que cette méta doit être accessible dans l’API WP REST en définissant ‘ show_in_rest‘ sur true.
Par exemple, disons que je veux ajouter une bascule marche/arrêt et une entrée de texte dans la barre latérale de l’éditeur. Cela signifie que j’appelle register_post_meta()respectivement un booléen et un type de valeur de chaîne. Je souhaite également limiter ces post meta au type de publication ‘post’ uniquement. Cela ressemblerait à quelque chose comme :
Maintenant, j’ai une clé méta post _my_custom_boolet _my_custom_textprête et disponible dans Gutenberg. Je vous recommande de les renommer en quelque chose qui a du sens pour vous.
Enregistrement de notre plugin Javascript
Pour notre prochaine étape, nous allons ajouter un fichier Javascript et nous assurer de le mettre en file d’attente à l’aide de PHP.
Gardez à l’esprit que j’écris le code Javascript dans la syntaxe ES6. Cela signifie que j’ai mis en place une configuration webpack/Babel pour compiler mon fichier dans un fichier Javascript lisible séparé pour le navigateur.
J’ai un guide sur la façon de configurer cela si vous n’êtes pas sûr de la façon dont cela fonctionne:
Nous devons nous assurer que WordPress charge notre script dans l’éditeur. Pour ce faire, nous accrochons une fonction à enqueue_block_editor_assetset appelons[wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)() :
add_action( 'enqueue_block_editor_assets', function() {
wp_enqueue_script(
'awp-custom-meta-plugin',
get_template_directory_uri(). '/assets/js/gutenberg/plugin-awp-custom-postmeta.js',
[ 'wp-edit-post' ],
false,
false
);
} );Je suppose que vous savez comment mettre des scripts en file d’attente et que vous pouvez remplacer les valeurs par les vôtres. Comme deuxième paramètre, je fournis le chemin vers le fichier de construction (pas le fichier source). Pour m’assurer que notre script n’est pas chargé trop tôt, j’ai défini ‘ wp-edit-post‘ comme dépendance. C’est le package dont nous avons besoin pour gérer la post-méta.
Passons maintenant à la partie Javascript.
Nous devons d’abord appeler [registerPlugin](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-plugins/#registerPlugin)()et transmettre notre composant pour rendre le panneau dans la barre latérale du document Gutenberg. Cette fonction est disponible dans le wp.pluginspackage, je la déstructure donc en haut. J’aime garder mes fichiers bien rangés, alors je crée un autre fichier ; "awp-custom-postmeta-fields.js" pour contenir le composant rendu et l’importer.
Écrire notre composant
Commençons par créer un composant de base qui ne fait rien d’autre que de s’asseoir là au bon endroit, donc nous l’éliminons d’abord. Afin de rendre un composant dans la barre latérale Document de Gutenberg, nous utilisons le [PluginDocumentSettingPanel](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-document-setting-panel/)composant. Nous pouvons définir des attributs tels que a title, iconet className. Et tout ce qu’il y a à l’intérieur sera rendu dans la barre latérale du document. Pour l’instant, je ne fais que sortir du texte "Bonjour là-bas".
Avec le code ci-dessus (compilé), on obtient ceci :
Impressionnant. Cependant, nous voulons ajouter quelques entrées. Mais afin de connecter ces entrées avec notre post méta personnalisé, nous devons composer notre composant avec les composants d’ordre supérieur withSelect(pour récupérer les post méta valeurs) et withDispatch(pour mettre à jour les post méta valeurs). Cela peut sembler un peu complexe si vous n’avez jamais travaillé avec des composants d’ordre supérieur auparavant, mais une fois que vous avez compris, c’est assez simple.
Nous devons d’abord changer notre exportdéclaration. Plutôt que de simplement renvoyer notre composant seul, nous devons le composer avec withSelectet withDispatch, tous deux dans le wp.datapackage.
À l’ intérieur withSelect(), nous avons accès à la select()fonction puissante. En utilisant select(), nous pouvons récupérer les méta-valeurs de la publication actuelle. Nous pouvons également récupérer le type de publication actuel, si nous le souhaitons. Comme je l’ai mentionné plus tôt lors de l’enregistrement des métas de publication, nous pouvons limiter les métas de publication à un type de publication spécifique. Si nous récupérons le type de publication de la publication actuelle, nous pouvons dans notre composant nous assurer de ne rendre notre code que si nous sommes au bon type de publication. Plus sur cela plus tard.
Dans withDispatch()nous pouvons définir des fonctions que nous pouvons exécuter dans notre composant. Nous créons une fonction qui servira dispatch()à mettre à jour la post meta.
Changeons la exportdéclaration en ceci:
Nous devons également les déstructurer à partir des packages suivants en haut du fichier :
const { compose } = wp.compose;
const { withSelect, withDispatch } = wp.data;Avec cela, notre AWP_Custom_Plugincomposant a accès à trois nouveaux accessoires ; postMetaqui contient toutes les méta-valeurs de publication de la publication actuelle ; postTypequi contient le type de publication de la publication actuelle ; et enfin la fonction setPostMeta()que nous avons créée dans withDispatch()laquelle mettra à jour la méta du message.
Ainsi, dans notre définition de composant, nous pouvons déstructurer ces trois nouveaux accessoires ;
Et maintenant, nous pouvons ajouter quelques entrées à notre rendu, en nous assurant qu’elles affichent la valeur actuelle et qu’elles mettent à jour la méta post dans l’événement on change. J’ai enregistré un booléen et une chaîne, donc à titre d’exemple, je vais ajouter un ToggleControlpour une bascule et un simple TextControlpour une entrée de texte.
Si vous n’êtes pas sûr des composants intégrés dans WordPress, j’ai un livre électronique entièrement gratuit qui couvre à peu près la plupart des composants disponibles dans Gutenberg, y compris les accessoires que nous pouvons définir pour chacun.
Voici un exemple de ce à quoi notre composant pourrait ressembler :
À la ligne #9-10et #16-17nous trouvons les parties critiques. Nous définissons la valeur actuelle des entrées sur postMeta.<your meta key here>et dans leur événement onChange, nous exécutons la fonction setPostMeta( { <your meta key here>: ... } )sur la nouvelle valeur mise à jour.
Enfin un mot sur la façon de limiter votre composant à un type de publication spécifique. Dans notre withSelect(), nous passons le type de publication du message actuel dans le prop postType. Tout ce que nous avons à faire dans notre composant est de comparer cette valeur à un type de publication et de renvoyer null si elle ne correspond pas :
Et c’est tout! Notre code devrait maintenant fonctionner. Le résultat final devrait être quelque chose comme :
Code final
Enregistrement de la post-méta et mise en file d’attente du fichier Javascript :
Les deux fichiers Javascript :