Dans cette partie, nous allons écrire du Javascript pour enregistrer et configurer notre bloc personnalisé. À la fin, nous enregistrerons le script avec PHP et créerons le code PHP nécessaire pour que WordPress le reconnaisse comme un nouveau bloc.
Tout d’abord, une note rapide sur la façon d’accéder aux fonctions et composants de WordPress Gutenberg.
wpLe package global et la déstructuration
Lorsque nous sommes dans un fichier Javascript mis en file d’attente dans l’éditeur Gutenberg, nous avons accès à un objet/package global : wp. Il s’agit d’un objet Javascript très varié et il contient tout un tas de composants et de fonctions utiles que nous utiliserons pour créer des blocs. Lors de l’écriture de Javascript pour des blocs personnalisés, vous vous référerez à wpbeaucoup de choses.
Par conséquent, il est courant, à la fois en Javascript moderne et en React, de déstructurer ce que nous voulons en utiliser. Fondamentalement, cela signifie simplement que nous définissons des variables locales à partir de parties d’une structure plus grande. Par exemple, la première fonction que nous utiliserons est registerBlockType()celle qui existe dans wp.blocks. Nous pourrions invoquer la fonction comme suit :
wp.blocks.registerBlockType();Mais c’est plus facile de le déstructurer comme ça :
const { registerBlockType } = wp.blocks;
registerBlockType();Vous pouvez maintenant vous référer directement à la fonction sans la préfixer avec sa structure. Cela devient beaucoup plus utile lorsque nous nous référons à des fonctions ou à des composants que nous répéterons souvent.
Nous ferons une restructuration dans cette série, et au fur et à mesure que nous avancerons dans le didacticiel, nous verrons à quel point notre code devient plus lisible et plus court.
Enregistrer un nouveau bloc
La fonction d’enregistrement d’un nouveau bloc personnalisé est registerBlockType()disponible dans le wp.blockspackage. Il accepte deux paramètres ; d’abord une chaîne avec l’espace de noms et le nom du bloc, et ensuite un objet avec la configuration complète du bloc.
Gutenberg s’attend à ce que tous les blocs aient un espace de noms et un nom, définis avec une barre oblique entre eux. L’espace de noms sert à garantir que le nom de votre bloc n’entrera pas en conflit avec d’autres blocs susceptibles d’utiliser le même nom. Tous les blocs de WordPress utilisent l’espace de noms core. Par exemple, le bloc de paragraphe standard dans WordPress porte le nom core/paragraph. Si vous choisissez un autre espace de noms, vous pouvez également créer un bloc nommé paragraphe sans causer de problèmes.
Décidez d’un espace de noms de version slug qui vous est propre. J’utiliserai l’espace de noms awp(version courte de A White Pixel) dans cette série.
Ouvrez le fichier source que nous avons créé à la dernière étape ; src/block-awhitepixel-myfirstblock.js, chez un éditeur. Nous appellerons d’abord registerBlockTypedepuis destructured wp.blocks, avec le nom awp/firstblock. Ajustez votre nom et votre espace de noms au fur et à mesure.
const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
// Your block configuration and code here
});Dans le deuxième paramètre, l’objet de configuration de bloc, nous devons définir quelques propriétés pour qu’il soit enregistré avec succès. N’oubliez pas que la configuration du bloc est un objet, ce qui signifie que vous devez tout écrire sous forme de paires clé + valeur, séparées par une virgule. Il y a pas mal de propriétés de configuration possibles, alors passons en revue celles-ci et nous verrons le code final à la fin.
Obligatoire : titre
La première propriété requise est title. C’est le nom tel qu’il apparaîtra lorsque vous sélectionnerez un bloc. Définissez cette propriété comme n’importe quel nom que vous souhaitez dans une chaîne.
Nous ajouterons ce qui suit comme titre :
title: 'My first block',PS: Nous reviendrons sur la façon dont nous écrivons toutes les chaînes de notre bloc pour nous assurer qu’elles peuvent être traduites dans la partie 8. Mais pour l’instant, nous allons rester simples et simplement écrire des chaînes.
Obligatoire : catégorie
La propriété categorydéfinit où dans quelle catégorie de bloc votre bloc apparaîtra lorsque vous sélectionnez des blocs à insérer dans l’éditeur. Les valeurs possibles sont common, formatting, layout, widgets, embed.
Mettons-le dans common, la première catégorie de bloc.
category: 'common',Facultatif : icône
Si vous avez utilisé Gutenberg, vous avez probablement remarqué que tous les blocs ont des icônes. Vous pouvez ajouter une icône à votre bloc avec une chaîne qui fait référence à l’un des Dashicons de WordPress, ou vous pouvez fournir un svgélément personnalisé.
Je vais juste choisir l’un des dashicons de WordPress, le smiley – mais vous pouvez choisir celui que vous voulez. Notez que vous ignorez l’inclusion de "dashicons-" dans votre nom de classe d’icônes.
icon: 'smiley',Facultatif : description
Vous pouvez fournir une description qui sera affichée dans la barre latérale Paramètres (sur le côté droit) lorsque le bloc est actif.
Je vais juste ajouter un texte rapide à titre d’exemple :
description: 'Learning in progress',Facultatif : mots clés
Gutenberg prend en charge une fonctionnalité de recherche lors du choix des types de blocs. Vous pouvez fournir un tableau de correspondances possibles dans la propriété keywords. Sans keywordsvous ne trouveriez votre bloc qu’en recherchant son nom.
J’ajouterai exampleet test, afin que nous puissions facilement trouver notre bloc personnalisé lorsque nous commençons à taper l’un de ces mots-clés.
keywords: ['example', 'test'],Facultatif : attributs
La propriété attributesest une propriété très importante que nous reviendrons assez souvent dans cette série de tutoriels. C’est là que vous stockez vos données structurées et les informations saisies par l’utilisateur pour votre bloc. Vous pouvez l’imaginer sous forme de variables. Nous ne l’ajouterons pas pour l’instant, mais nous y reviendrons certainement très bientôt.
(En quelque sorte) obligatoire : modifier et facultatif : enregistrer
Dans editet saveles propriétés sont en fait l’endroit où vous ajouterez tout votre code pour la sortie de l’éditeur et le rendu frontal. Ces deux propriétés attendent une fonction qui doit renvoyer une sortie.
La propriété editdécrit la structure de votre bloc dans l’éditeur. La savepropriété gère essentiellement deux choses; la sortie de votre bloc en frontend, mais aussi la structure de la façon dont votre bloc est enregistré dans la base de données. Vous travaillerez principalement dans editcar c’est là que vous ajoutez des entrées pour entrer ou choisir des choses et mettre à jour les données du bloc. La savefonction ne doit en aucun cas mettre à jour ou modifier les données, elle doit simplement sortir.
Gutenberg doit pouvoir reconstruire votre bloc avec tous ses paramètres dans l’éditeur à partir de ce qui est sorti dans la savefonction (et les attributs). Si Gutenberg ouvre un message où la sortie du bloc précédemment enregistré diffère (même légèrement) de ce qui est défini dans l’enregistrement, votre bloc deviendra invalide.
Je peux vous garantir que vous rencontrerez souvent cela lors du développement de blocs personnalisés. Lorsque cela se produit, vous devez supprimer le bloc (des points dans la barre d’outils) et le rajouter. Je recommande également d’actualiser le navigateur (F5 ou CTRL+R).
WordPress a une page de documentation dédiée aux fonctions d’édition et d’enregistrement du bloc si vous souhaitez en savoir plus.
En ce qui concerne notre premier bloc, produisons quelque chose de basique. Nous renverrons la même chose pour editet save; un «:)» entouré de <div>. L’icône du bloc est un smiley après tout.
Autres propriétés
Il existe des propriétés plus facultatives pour registerBlockType; parent, supports, transforms, exampleet styles. Nous allons les ignorer pour le moment, car la plupart sont destinés à la construction de blocs plus avancés ou personnalisés. Si vous souhaitez en savoir plus à ce sujet, consultez la documentation de WordPress.
Code de bloc de registre final
Notre code ressemble maintenant à ceci.
Avec cela, nous en avons assez pour que notre bloc soit enregistré avec succès en tant que bloc personnalisé. Voyons cela en pratique dans l’éditeur Gutenberg.
Avez-vous pensé à compiler votre Javascript ? À l’étape précédente, nous avons appris que nous ne pouvions pas charger ce fichier Javascript dans Gutenberg ; nous avons besoin de la version compilée. Vous développez généralement avec npm run startune exécution en arrière-plan, ou vous pouvez simplement exécuter npm run buildune fois maintenant. Cela devrait compiler notre source Javascript et le placer là où vous l’avez défini pour qu’il soit placé et nommé dans votre fichier webpack.config.js.
La partie PHP de l’enregistrement d’un bloc
Pour chaque bloc, vous devez enregistrer le fichier Javascript et c’est exactement la même chose que vous enregistreriez n’importe quel autre script dans WordPress – en utilisant [wp_register_script](https://developer.wordpress.org/reference/functions/wp_register_script/)(). Notez que nous enregistrons le script, pas le mettons en file d’attente. En effet, nous devons également appeler une fonction PHP pour enregistrer chaque bloc personnalisé, et cette fonction est responsable de la mise en file d’attente du script lorsque cela est nécessaire.
Je préfère conserver le code lié à Gutenberg dans un fichier séparé dans mes thèmes. Mais vous pouvez, et nous le ferons dans ce tutoriel, simplement écrire tout le code PHP directement à l’intérieur du thème functions.phppour des raisons de simplicité.
Je recommande d’utiliser le initcrochet pour votre fonction, et non enqueue_block_assets. Nous pouvons mettre à la fois l’enregistrement du script et l’enregistrement du bloc ensemble.
La fonction PHP que nous utiliserons pour enregistrer un nouveau bloc est [register_block_type](https://developer.wordpress.org/reference/functions/register_block_type/)(). De même que Javascript, registerBlockType()il accepte deux paramètres ; l’espace de noms et le nom du bloc, et un tableau avec des arguments. Assurez-vous de fournir exactement le même espace de noms et le même nom en PHP qu’en Javascript.
Dans le deuxième argument, il y a quelques arguments possibles (dont nous reviendrons sur certains plus tard dans cette série). Mais le plus important est celui editor_scriptoù vous fournissez le handle (premier paramètre de wp_register_script()) du script enregistré.
Et c’est tout!
Notre bloc dans l’éditeur Gutenberg
Maintenant, lorsque vous actualisez votre éditeur dans un article, vous devriez trouver notre bloc – soit en ouvrant la catégorie Commun, soit en recherchant l’un des mots clés ou le nom que vous avez fourni.
Notre bloc rend un simple ":)" à la fois dans l’éditeur et dans le frontend. Pour l’instant, vous ne pouvez rien modifier dans le bloc, mais c’est ce que nous apprendrons dans les prochaines étapes !