Comment ajouter un bouton à l'éditeur Gutenberg en utilisant @wordpress/scripts

Il y a presque un an et demi, Antonio a écrit ce billet de blog expliquant l'une des difficultés rencontrées lors de l'adaptation de nos plugins au nouvel éditeur de blocs WordPress. Le résultat de son tutoriel ressemblait à ceci :

Heureusement ou malheureusement, Gutenberg a beaucoup changé en cette année et demie. La pile de développement s'est développée et améliorée et les développeurs de plugins et de thèmes ont dû adopter et adapter les nouvelles technologies. Et ceux d'entre nous qui écrivent également sur notre expérience et partagent ce que nous apprenons sont maintenant "forcés" de mettre à jour nos tutoriels afin que vous puissiez vous tenir au courant. Mais nous en sommes ravis !

Il y a quelques semaines, Ivan, l'un de nos lecteurs, nous a laissé un commentaire dans le tutoriel d'Antonio demandant de l'aide. Apparemment, il n'a pas pu implémenter le plugin d'Antonio. Et, pour être honnête, cela ne me surprend pas, car les choses ont beaucoup changé ces derniers temps. Alors, pour aider Ivan et vous tous qui nous lisez et souhaitez continuer à vous renseigner sur WordPress, recréons le tutoriel sur la façon d'ajouter un bouton à l'éditeur de blocs Gutenberg en profitant de tous les nouveaux outils que WordPress nous offre !

Créer un plugin

La première chose que nous devons faire est de créer un plugin WordPress. C'est assez simple. Fondamentalement, tout ce que nous avons à faire est de créer un dossier dans wp-content/plugins avec le nom que nous voulons donner à notre plugin (par exemple, gutenberg-button ) et, à l'intérieur, de créer un fichier avec le même nom et un .php extension .php . Tapez ensuite le code suivant dans votre fichier de plugin :

Maintenant, regardons de plus près ce que fait l'extrait précédent :

• Nous ouvrons d'abord une <?php . Pas de surprise ici.
• Ensuite, dans ce fichier principal, nous ajoutons un commentaire multi-lignes. Le commentaire comprend plusieurs lignes avec des couples "Clé / Valeur". Par exemple, nous voyons comment nous spécifions le nom du plugin ( Plugin Name ), sa version ( Version ) ou le nom de l'auteur ( Author ). Toutes ces informations seront alors visibles dans la section Plugins de WordPress.
• Enfin, nous ajoutons du code passe-partout :
  • nous spécifions un espace de namespace (nous avons parlé des espaces de noms ici),
  • nous nous assurons que, si le fichier s'exécute, il est exécuté dans le cadre de WordPress, et
  • nous définissons quelques constantes sur le plugin (ce qui sera utile plus tard).

Une fois que nous avons fait tout cela, si nous allons sur l'écran Plugins de notre WordPress, nous verrons que le bouton Gutenberg est là :

on l'active et… voila ! Bien sûr, ça ne fera rien, mais c'est déjà là.

Développement de plug-ins JavaScript

De nos jours, les développeurs WordPress doivent maîtriser JavaScript. C'est l'une des conséquences du fait que Gutenberg soit dans le noyau, je suppose. Et ce tutoriel ne fait pas exception.

Préparation de l'environnement

Si nous voulons ajouter un nouveau bouton à l'interface de Gutenberg, nous devons coder cette fonctionnalité en JavaScript. Préparons donc l'environnement de développement JavaScript dans notre plugin. Pour ce faire, exécutez simplement la commande suivante à partir de votre ligne de commande (assurez-vous d'être dans wp-content/plugins/gutenberg-button lorsque vous le faites) :

 npm init

et suivez les instructions :

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

Le résultat de ce processus est un fichier package.json . Comme vous le verrez dans quelques instants, ce fichier vous sera extrêmement utile à l'avenir.

Comme je l'ai déjà révélé dans le titre de cet article, nous utiliserons @wordpress/scripts pour créer notre plugin. Ajoutons-le donc en tant que dépendance en exécutant la commande suivante :

 npm install --save-dev @wordpress/scripts

Cette commande téléchargera un tas de dépendances à l'intérieur de notre plugin (sous node_modules ) et modifiera notre package.json afin qu'il soit clair que @wordpress/scripts est maintenant une dépendance de développement.

Si vous jetez un œil à la documentation de ce package, vous verrez qu'il comprend beaucoup de scripts pour construire, valider la syntaxe, formater le code, etc :

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

éditons donc notre fichier package.json afin que la section "scripts" contienne toutes les commandes recommandées.

Comment vérifier que tout fonctionne…

Créons un dossier src à la racine de votre projet et ajoutons-y un fichier index.js . Ce sera le fichier JavaScript principal de notre plugin et contiendra tout votre code (vous pouvez ensuite organiser le code comme bon vous semble, tant que le fichier principal est src/index.js ).

Essayons si les choses fonctionnent comme prévu en ajoutant l'instruction suivante index.js :

 console.log( 'Hi!' );

et la construction du projet à l'aide npm run build . Cela transpilera votre code en quelque chose qu'un navigateur peut exécuter (ce n'était pas vraiment nécessaire pour le moment, mais ce sera dans quelques minutes) et générera un nouveau script dans un dossier de build .

Tout ce que nous avons à faire maintenant est de dire à WordPress que ce script existe pour qu'il puisse le charger. Pour cela, ouvrez simplement le fichier principal de votre plugin ( gutenberg-button.php ) et ajoutez les lignes suivantes à la fin :

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Si vous faites attention, vous verrez que nous disons simplement à WordPress de mettre en file d'attente notre nouveau script /build/index.js en tant que ressource d'éditeur de blocs. De cette façon, lorsqu'un utilisateur accède à l'éditeur de blocs, notre script fera partie des actifs que l'éditeur inclura.

Alors vérifions cela. Accédez à votre tableau de bord WordPress, modifiez un article et regardez la console JavaScript de votre navigateur. Si tout s'est passé comme prévu, vous devriez voir "Salut !" écrit sur la console :

Répliquer notre tutoriel pour ajouter un bouton à Gutenberg

Bon, maintenant que nous avons vu que nous pouvons écrire du code JavaScript et que npm run build dans quelque chose que nos navigateurs comprendront, il est temps de reproduire le didacticiel d'Antonio. Et ceci, cher lecteur, est extrêmement simple.

Ouvrez le fichier src/index.js et remplacez l'instruction console.log précédente par la suivante :

Comme vous pouvez le voir, c'est presque le même code qu'Antonio a écrit il y a quelques mois. La principale différence est le fait que nous n'utilisons plus la variable globale wp pour accéder aux fonctions et composants de Gutenberg ; à la place, nous nous appuyons maintenant sur les instructions d' import . Mais à part ça, c'est à peu près pareil.

Une fois que vous avez écrit le code, il suffit d' npm run build et c'est tout ! Vous avez maintenant le bouton dans Gutenberg :

Assurons-nous que cela fonctionne en sélectionnant du texte et en cliquant sur le bouton :

et voilà, on voit à nouveau le texte réapparaître dans la console !

Une dernière remarque sur les dépendances…

Si vous regardez à l'intérieur du dossier de build , vous verrez que @wordpress/scripts a non seulement créé un fichier index.js , mais a un fichier index.asset.php . Ce fichier définit un petit objet avec deux propriétés :

• une liste des dépendances (à savoir, les scripts WordPress) requises par notre plugin
• une version de construction

Nous pouvons (et devrions) utiliser ces deux propriétés lors de la mise en file d'attente de notre script dans WordPress si nous voulons nous assurer que le script fonctionnera correctement. Pour ce faire, revenez simplement à gutenberg-button.php et modifiez-le comme indiqué ci-dessous :

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

Chargez simplement l'objet dans index.asset.php en utilisant une instruction include et remplacez la liste des dépendances que nous avions ( [] ) par les dépendances réelles et utilisez le numéro de build comme version du plugin.

conclusion

Créer des plugins WordPress vraiment utiles est délicat. Vous devez bien comprendre le fonctionnement de JavaScript et être familiarisé avec toutes les ressources dont dispose WordPress. Mais grâce au package @wordpress/scripts , préparer l'environnement de développement JavaScript et créer un plugin JavaScript pouvant s'exécuter dans WordPress est plus facile que jamais.

J'espère que vous avez aimé le post d'aujourd'hui. Et, comme toujours, si vous êtes bloqué à un moment donné ou si vous avez des questions, veuillez laisser un commentaire et nous vous aiderons.

Oh et, au fait, voici un lien vers le projet, prêt à être téléchargé et testé si vous le souhaitez. Clonez simplement le projet, npm install toutes les dépendances, npm run build -le et essayez-le!

Image sélectionnée par Ashim D'Silva sur Unsplash.