Créer un bloc Gutenberg personnalisé – Partie 3 : Accessoires et composants WordPress

L’ étape précédente de cette série de tutoriels a expliqué comment enregistrer un bloc personnalisé, à la fois en Javascript et en PHP. Dans cette étape, nous apprendrons à utiliser les composants de WordPress pour ajouter différents types de champs et de paramètres.

Afin d’utiliser les composants de WordPress dans notre bloc, nous devons d’abord connaître les accessoires.

Accessoires

Les accessoires sont une fonctionnalité majeure de React et constituent essentiellement un moyen de transmettre des variables ou des fonctions à d’autres composants. Si vous n’êtes pas familier avec les accessoires React, vous pouvez lire le tutoriel officiel de React à ce sujet.

WordPress fournit quelques accessoires pour les fonctions editet savedans registerBlockType(). À l’intérieur de ces accessoires, nous avons accès à des éléments critiques, tels que des attributs et une méthode pour mettre à jour nos attributs. Nous passerons en revue les attributs en détail à l’ étape suivante !

Jusqu’à présent, dans notre bloc, nous avons écrit la fonction pour editet savecomme ceci :

Vous devriez vous habituer à ajouter le paramètre propsà la fois à editet save, comme ceci :

Vous avez maintenant un accès complet à la variable propset à tout ce qu’elle contient depuis editet save. Si vous êtes curieux, vous pouvez ajouter un console.log(props);dans la editfonction avant l’ returninstruction. Vous devriez voir quels accessoires sont disponibles dans le débogueur de la console.

Utiliser les composants de WordPress

Comme mentionné précédemment, nous avons accès à une énorme bibliothèque de composants et de fonctions utiles à l’intérieur du package global wp. Vous trouverez des composants prêts à l’emploi pour tout type de composants liés aux entrées auxquels vous pouvez penser. Les exemples incluent les entrées de texte, les entrées de texte enrichi, les listes déroulantes, les bascules, les cases à cocher, les boutons de différents styles, le téléchargeur de médias et les sélecteurs de couleurs. Il existe également des fonctions et des composants pour des fonctionnalités plus avancées. Comme interroger WordPress pour le contenu (messages, catégories, etc.) avec des fonctions intégrées ou récupérer avec l’API REST.

Il est à la fois plus facile et recommandé d’utiliser les composants d’interface utilisateur de WordPress. Il s’agit de s’assurer que la conception et les fonctionnalités sont aussi rationalisées que possible pour ne pas confondre ou ennuyer les utilisateurs.

Mais malheureusement, au moment d’écrire ces lignes, la documentation de Gutenberg est très rare. J’ai trouvé le meilleur moyen d’en savoir plus sur ce qui existe dans le wppackage et sur le fonctionnement des composants en consultant leur repo officiel Gutenberg Github. Certains des packages (dossiers) ont un texte readme qui offre un peu de documentation. Jetez un œil au fichier readme pour un bouton ou la bascule par exemple.

Le référentiel Github doit correspondre à ce qui se trouve à l’intérieur du wppackage (selon la version que vous avez et la branche que vous regardez dans Github). Cela signifie que chaque dossier que vous voyez dans le packagesrépertoire racine de Github réside dans le wppackage global. Par exemple, rappelez-vous que la fonction que nous avons utilisée à l’étape précédente registerBlockType(), était à l’intérieur wp.blocksde, ce qui signifie que vous trouverez le code source de cette fonction exporté dans packages/blocks/.

Comme j’ai développé un certain nombre de blocs Gutenberg personnalisés et creusé un peu dans le référentiel Github, j’ai découvert qu’il existe quelques packages contenant les fonctionnalités les plus courantes utilisées pour créer des blocs personnalisés. Je vais les inclure ci-dessous.

Pour un aperçu plus complet des composants disponibles, je vous recommande de télécharger mon eBook gratuit couvrant les composants disponibles dans Gutenberg ! Il contient les composants les plus courants et les plus utiles avec une documentation sur les accessoires et des exemples de code :

Un aperçu rapide des packages les plus courants que vous utiliserez pour les blocs

Évidemment, il y en a beaucoup plus disponibles, mais ce qui suit est ce qui est le plus courant pour le développement de blocs. Nous en utiliserons la plupart, sinon la totalité, dans cette série de didacticiels. Chaque fois que vous souhaitez utiliser un composant, vous devez savoir dans quel package il se trouve.

composants wp

Vous trouverez la plupart des composants d’entrée de l’interface utilisateur dans wp.components. Les exemples sont différentes entrées de texte, sélection, cases à cocher, boutons radio, composants déplaçables, boutons, sélecteur de couleurs, sélecteur de date, etc. Vous trouverez également des composants d’interface utilisateur que vous pouvez utiliser pour la barre d’outils de bloc et le contenu de la barre latérale des paramètres (appelée InspectorControls) dans l’éditeur.

Consultez les dossiers dans le référentiel Github.

wp.blockEditor et wp.editor

Dans ces deux packages, vous trouverez des composants utiles pour le texte enrichi, la gestion des images / téléchargeurs de médias et des composants pour ajouter des barres d’outils ou des panneaux d’inspecteur personnalisés (barre latérale).

À la fin de cette série, nous verrons comment créer des blocs dynamiques dans lesquels nous utiliserons PHP pour rendre la sortie du bloc, et pour cela nous utiliserons un composant de wp.editor.

Si je comprends bien, la plupart des composants ont commencé au wp.editordébut de Gutenberg, mais surtout après WordPress 5.3, beaucoup d’entre eux ont été déplacés vers wp.blockEditor. Si vous utilisez un composant dans wp.editorlequel WordPress envisage de s’installer wp.blockEditor, il n’échouera pas pour le moment, mais dans le débogueur de la console, vous recevrez des avertissements indiquant qu’il est obsolète et que vous devez basculer vers celui -ci wp.blockEditordès que vous le pouvez. Et de manière réversible, si vous suivez cette série avec une ancienne version de WordPress pour une raison quelconque, vous pourriez rencontrer des erreurs lors de l’appel de composants qui n’ont pas wp.blockEditorencore été déplacés.

wp.element

À l’ intérieur wp.element, vous trouverez des composants qui correspondent aux composants React. Par exemple Component(qui correspond à React.Component) et Fragment( React.Fragment). Nous les utiliserons lorsque nous commencerons à diviser notre code en composants distincts.

wp.i18n

Comme son nom l’indique, le wp.i18npackage contient des fonctions de gestion de la traduction. Il contient les mêmes fonctions de traduction que nous connaissons en PHP ; par exemple __()et _e(). Nous verrons cela en détail dans <<<>>>> lorsque nous apprendrons comment traduire notre bloc.

wp.data

Le wp.datapackage permet d’interroger WordPress pour obtenir des données en dehors de l’éditeur. Il existe des composants pour envoyer des messages, withSelectet selectque nous utiliserons plus tard dans cette série pour interroger les messages à l’intérieur de notre bloc.

wp.composer

Le package précédent et wp.composesont destinés à la construction de blocs plus avancés. Dans ce package, nous trouverons des composants et des fonctions pour créer des composants dits d’ordre supérieur. Les composants d’ordre supérieur sont une technique de modèle dans React pour réutiliser les composants et la logique, et nous l’utiliserons en combinaison avec wp.datapour interroger les publications.

Assez parlé – comment utilisez-vous certains de ces composants dans la pratique ?

Comme mentionné précédemment; pour utiliser les composants de WordPress, vous devez savoir où ils se trouvent. J’espère que mon aperçu ci-dessus, combiné au référentiel Github, vous donnera une idée de l’endroit où les obtenir.

N’oubliez pas que vous pouvez toujours ajouter des balises HTML normales, telles que div, span, titres, etc. N’oubliez pas de suivre les directives de React dans les attributs. Par exemple class, est un mot-clé réservé dans React (pour créer des composants basés sur des classes), donc si vous voulez ajouter une classe à un élément HTML, vous devez utiliser className.

Remarque : lors du développement, n’oubliez pas d’initier npm run startla compilation de votre code.

Comme exemple simple, essayons quelques composants pour voir à quoi ils ressemblent. Nous les déstructurons de leurs packages correspondants et les utilisons dans notre editfonction.

Cela aura par exemple pour résultat que notre bloc ressemblera à ceci dans l’éditeur.

Vous remarquerez que vous obtiendrez des messages d’erreur dans la console lorsque vous les saisirez, et qu’il n’enregistrera pas ce que vous saisissez lors de la mise à jour de la publication (et de l’actualisation). C’est parce qu’il nous manque des accessoires sur les composants qui sont la connexion aux attributs, où toutes nos données de bloc sont stockées. Les accessoires sont chargés de transmettre les valeurs enregistrées et les fonctions chargées de mettre à jour nos attributs lorsque quelque chose est modifié dans nos entrées. C’est ce que nous ferons à l’étape suivante, où nous commencerons enfin à écrire du code pour de vrai.