Construire des blocs Gutenberg personnalisés : le didacticiel de développement de blocs définitif

De nombreuses personnes se plaignent des obstacles rencontrés pour commencer à créer des blocs et des applications Gutenberg. La courbe d'apprentissage est abrupte, principalement en raison de la difficulté d'installation et de configuration de l'environnement de développement. De plus, une solide connaissance de JavaScript, Node.js, React et Redux sont des ingrédients indispensables pour cette recette assez complexe.

Le manuel officiel de l'éditeur de blocs WordPress fournit aux développeurs une énorme quantité d'informations, mais vous pouvez vous retrouver perdu dans cette mer de détails.

Et il convient de mentionner ce que Matias Ventura, architecte principal du projet Gutenberg, a rapporté dans son entretien avec WP Tavern :

Bien qu'il y ait des gens qui peuvent l'apprendre rapidement, c'est toujours un gros obstacle pour les gens. Je pense qu'il y a plusieurs couches à cela; la documentation pourrait être d'un ordre de grandeur meilleur à la fois dans l'organisation et la présentation. J'espère que nous pourrons faire beaucoup plus là-bas.

Dans cet esprit, nous avons décidé de fournir un tutoriel étape par étape visant à aider nos lecteurs à démarrer avec le développement de blocs Gutenberg.

A l'air intéressant? Plongeons-nous !

Prérequis pour le développement de blocs Gutenberg

Pour ce didacticiel, les seules compétences requises sont une bonne connaissance du développement de plugins WordPress et au moins une compréhension de base de HTML, CSS, JavaScript et React.

S'agira-t-il d'un projet ambitieux ? Vous pariez que ce sera le cas !

Il n'a pas été facile de trouver le bon compromis entre exhaustivité et simplicité ou de décider quels sujets inclure et lesquels omettre.

Espérons que les lecteurs intermédiaires et avancés nous pardonneront de ne pas avoir approfondi certains concepts tels que l'état React, le magasin Redux, les composants de haut niveau, etc. Ces sujets nécessitent plus d'espace et d'attention et sont probablement trop avancés pour commencer le développement de blocs (sauf si vous êtes un développeur React).

Pour la même raison, nous ne couvrirons pas certains des sujets les plus avancés liés au développement de blocs Gutenberg, tels que les blocs dynamiques et les boîtes méta.

Avec les connaissances que vous acquerrez à la fin de cet article, vous pourrez commencer à vous amuser et à être productif tout de suite.

Une fois que vous aurez commencé à construire des blocs, vous serez prêt à améliorer vos compétences et à construire vous-même des blocs Gutenberg encore plus avancés.

Qu'est-ce qu'un bloc Gutenberg ?

Depuis sa première sortie en décembre 2018, l'éditeur de blocs a été grandement amélioré à tous égards : des API plus puissantes, une interface utilisateur plus avancée, une convivialité améliorée, une tonne de nouveaux blocs, les premières implémentations de l'édition complète du site, et bien plus encore. .

En bref, même si Gutenberg est encore en plein développement, il a parcouru un long chemin - et aujourd'hui, l'éditeur de blocs est un candidat à part entière en tant que constructeur de pages et de sites fiable et fonctionnel.

Du point de vue d'un développeur, Gutenberg est une application à page unique (SPA) basée sur React qui permet aux utilisateurs de WordPress de créer, modifier et supprimer du contenu dans WordPress. Cependant, cela ne doit pas vous faire penser à une version améliorée de l'éditeur de contenu traditionnel.

Nous voulons clarifier ceci :

Dans Gutenberg, le contenu est divisé en blocs, qui sont des « briques » que les utilisateurs peuvent utiliser pour créer des publications et des pages ou leurs sites Web entiers.

Mais qu'est-ce qu'un bloc techniquement ?

Nous aimons la définition de WordPress :

"Bloc" est le terme abstrait utilisé pour décrire les unités de balisage qui, composées ensemble, forment le contenu ou la mise en page d'une page Web. L'idée combine les concepts de ce que nous réalisons aujourd'hui dans WordPress avec des codes abrégés, du HTML personnalisé et intègre la découverte dans une API et une expérience utilisateur cohérentes.

Les titres, les paragraphes, les colonnes, les images, les galeries et tous les éléments qui composent l'interface de l'éditeur, des panneaux de la barre latérale aux commandes de la barre d'outils de bloc, sont des composants React.

Alors, que sont les composants React ? W3Schools fournit la définition suivante :

Les composants sont des morceaux de code indépendants et réutilisables. Elles ont le même objectif que les fonctions JavaScript, mais fonctionnent de manière isolée et renvoient du HTML via une fonction render() .

Bien que l'expérience d'édition offerte par Gutenberg soit nouvelle par rapport à l'éditeur WordPress classique, la façon dont WordPress stocke vos éléments de contenu dans la base de données ne change pas du tout. C'est parce que Gutenberg est une application qui fonctionne dans WordPress mais ne change pas la façon dont le CMS fonctionne en son cœur.

Les publications (et cela inclut les publications, les pages et les types de publication personnalisés) créées avec Gutenberg sont toujours stockées dans la table wp_posts , exactement comme avec l'éditeur classique.

Mais dans un article créé avec Gutenberg, vous trouverez des informations supplémentaires dans le tableau qui représentent une différence fondamentale entre les articles créés via l'éditeur classique et Gutenberg.

Ces informations ressemblent à des commentaires HTML et ont une fonction spécifique : délimiter des blocs :

Les délimiteurs de bloc indiquent à WordPress quel bloc doit être affiché à l'écran. Ils fournissent également des valeurs pour les propriétés de bloc dans un objet JSON. Ces accessoires dictent la façon dont le bloc doit être rendu à l'écran :

Configuration de votre environnement de développement WordPress

La mise en place d'un environnement de développement JavaScript moderne nécessite une solide connaissance des technologies avancées telles que Webpack, React et JSX, Babel, ESLint, etc.

Intimidé ? Ne soyez pas! La communauté WordPress est déjà venue à la rescousse en fournissant des outils puissants qui vous permettent d'éviter un processus de configuration manuelle compliqué.

Pour faire simple, nous n'aborderons pas le transpiling dans cet article (que nous vous conseillons néanmoins de vous familiariser une fois que vous aurez appris les bases du développement de blocs). Au lieu de cela, nous présenterons deux outils alternatifs que vous pouvez utiliser pour configurer rapidement et facilement un environnement de développement JavaScript moderne en quelques minutes. A vous de choisir celui qui vous convient le mieux pour votre projet.

La configuration d'un environnement de développement JavaScript pour créer des blocs Gutenberg est un processus en trois étapes :

1. Installer Node.js et npm
2. Configurer l'environnement de développement
3. Configurer le plugin de bloc

Commençons.

1. Installez Node.js et npm

Avant d'installer votre environnement de développement et d'enregistrer votre premier bloc, vous devrez installer Node.js et le gestionnaire de packages Node (npm).

Vous pouvez installer Node.js et npm de plusieurs manières différentes. Mais d'abord, vous voudrez peut-être vérifier si le logiciel est déjà installé sur votre machine.

Pour cela, lancez le terminal et exécutez la commande suivante :

 node -v

Si le résultat est command not found , Node.js n'est pas installé sur votre ordinateur et vous pouvez poursuivre l'installation.

Pour cet article, nous avons choisi l'option d'installation la plus simple, à savoir le programme d'installation de nœud. Il vous suffit de télécharger la version correspondant à votre système d'exploitation et de lancer l'assistant d'installation :

Une fois que vous avez installé Node.js, exécutez à nouveau la commande node -v dans votre terminal. Vous pouvez également exécuter la commande npm -v pour confirmer que le package npm est disponible.

Vous êtes maintenant équipé des outils suivants :

• L'exécuteur de package npx Node.js (voir la documentation). Cela vous permet d'exécuter une commande npm sans l'installer au préalable.
• Le gestionnaire de packages npm Node.js (voir docs). Ceci est utilisé pour installer des dépendances et exécuter des scripts.

L'étape suivante consiste à installer l'environnement de développement.

2. Configurez votre environnement de développement

Une fois que vous avez les dernières versions de Node.js et npm sur votre machine locale, vous aurez besoin d'un environnement de développement pour WordPress.

Vous pouvez soit utiliser un environnement de développement local comme DevKinsta, soit utiliser l'outil WordPress officiel. Jetons un coup d'œil aux deux options.

Option 1 : Environnement de développement local (DevKinsta)

En quelques clics, vous pouvez installer WordPress localement à l'aide de DevKinsta, notre outil de développement WordPress local moderne. Ou vous pouvez opter pour un autre outil de développement local, tel que MAMP ou XAMPP :

Option 2 : wp-env

Vous pouvez également opter pour l'outil officiel wp-env , qui fournit un environnement de développement WordPress local que vous pouvez lancer directement depuis la ligne de commande. Noah Alen le définit ainsi :

Les environnements WordPress locaux sont désormais aussi simples que d'exécuter une seule commande. wp-env est un outil de configuration zéro pour les environnements WordPress locaux indolores. Il fournit des décisions sur les options afin que les utilisateurs puissent rapidement lancer WordPress sans perdre de temps. En effet, l'objectif est de rendre ces environnements facilement accessibles à tous, que vous soyez développeur, concepteur, gestionnaire ou n'importe qui d'autre.

Si vous décidez de l'essayer, l'installation wp-env nécessite un minimum d'effort. Suivez simplement ces étapes :

Étape 1 : Confirmer l'installation de Docker et de Node.js

Pour répondre aux exigences techniques, vous devez d'abord installer Docker et Node.js sur votre ordinateur. En effet, wp-env crée une instance Docker exécutant un site Web WordPress. Toute modification apportée au code est immédiatement reflétée dans l'instance WordPress.

Étape 2 : Installez @wordpress/env à partir de la ligne de commande

Avec Docker et Node.js exécutés sur votre ordinateur, vous pouvez continuer et installer l'environnement de développement WordPress.

Vous pouvez installer wp-env globalement ou localement. Pour le faire globalement, vous devrez exécuter la commande suivante à partir du répertoire des plugins (plus d'informations à ce sujet dans la boîte de notification "Important" ci-dessous) :

 npm install -g @wordpress/env

Décomposons cela :

• npm install installe le package.
• -g ajouté à la commande installe globalement le package spécifié.
• @wordpress/env est le package que vous allez installer.

Pour confirmer que wp-env a été installé avec succès, exécutez la commande suivante :

 wp-env --version

Vous devriez voir la version actuelle wp-env , ce qui signifie que vous pouvez maintenant lancer l'environnement en utilisant la commande suivante depuis le dossier de votre plugin :

 wp-env start

Vous pouvez accéder au tableau de bord WordPress en utilisant l'adresse suivante :

• http://localhost:8888/wp-admin/

Les informations d'identification par défaut sont les suivantes :

• Nom d'utilisateur : admin
• Mot de passe : mot de password

Configurez votre plugin de bloc

Maintenant, vous avez besoin d'un plugin de bloc de démarrage sur lequel construire. Mais au lieu de créer manuellement un plug-in de bloc de développement avec tous les fichiers et dossiers nécessaires, vous pouvez simplement exécuter un outil de développement fournissant tous les fichiers et configurations dont vous avez besoin pour démarrer le développement de blocs.

Encore une fois, vous avez le choix entre plusieurs options. Jetons un coup d'œil à chacun.

Option 1 : Configurer un plugin de bloc avec @wordpress/create-block

@wordpress/create-block est l'outil de configuration zéro officiel pour créer des blocs Gutenberg :

Créer un bloc est un moyen officiellement pris en charge de créer des blocs pour enregistrer un bloc pour un plugin WordPress. Il offre une configuration de construction moderne sans configuration. Il génère du code PHP, JS, CSS et tout ce dont vous avez besoin pour démarrer le projet.

Il est largement inspiré de create-react-app. Félicitations à @gaearon, à toute l'équipe Facebook et à la communauté React.

Une fois que votre environnement local est opérationnel, vous pouvez configurer un bloc de démarrage en exécutant simplement la npx @wordpress/create-block , et il fournira tous les fichiers et dossiers dont vous avez besoin pour créer l'échafaudage du plug-in et enregistrer un nouveau bloc .

Faisons un test pour voir comment cela fonctionne.

Depuis votre outil de ligne de commande, accédez au répertoire /wp-content/plugins/ et exécutez la commande suivante :

 npx @wordpress/create-block my-first-block

Lorsqu'on vous demande de confirmer, entrez y pour continuer :

Le processus prend quelques instants. Une fois terminé, vous devriez obtenir la réponse suivante :

Et c'est tout!

Lancez maintenant votre environnement de développement WordPress et accédez à l'écran Plugins du tableau de bord WordPress. Un nouveau plugin nommé "My First Block" aurait dû être ajouté à votre liste de plugins :

Activez le plugin si nécessaire, créez un nouveau billet de blog, faites défiler l'outil d'insertion de bloc jusqu'à la section Widgets et sélectionnez votre nouveau bloc :

Retournez maintenant au terminal et changez le répertoire courant en my-first-block :

 cd my-first-block

Exécutez ensuite la commande suivante :

 npm start

Cela vous permet d'exécuter le plugin en mode développement. Pour créer le code de production, vous devez utiliser la commande suivante :

 npm run build

Option 2 : Configurer un plugin de bloc avec create-guten-block

create-guten-block est un outil de développement tiers pour créer des blocs Gutenberg :

create-guten-block est une boîte à outils de développement sans configuration (#0CJS) pour développer des blocs WordPress Gutenberg en quelques minutes sans configurer React, webpack, ES6/7/8/Next, ESLint, Babel, etc.

Tout comme l'outil officiel create-block , create-guten-block est basé sur create-react-app et peut vous aider à générer votre premier plugin de bloc sans tracas.

La boîte à outils fournit tout ce dont vous avez besoin pour créer un plugin WordPress moderne, notamment :

• Prise en charge de la syntaxe React, JSX et ES6.
• processus de développement/production de webpack derrière la scène.
• Extras de langage au-delà de ES6 comme l'opérateur de propagation d'objet.
• CSS préfixé automatiquement, vous n'avez donc pas besoin de -webkit ou d'autres préfixes.
• Un script de construction pour regrouper JS, CSS et des images pour la production avec des cartes source.
• Mises à jour sans tracas pour les outils ci-dessus avec une seule dépendance cgb-scripts.

Notez la mise en garde suivante :

Le compromis est que ces outils sont préconfigurés pour fonctionner d'une manière spécifique. Si votre projet a besoin de plus de personnalisation, vous pouvez "éjecter" et le personnaliser, mais vous devrez alors conserver cette configuration.

Une fois que vous disposez d'un site Web WordPress local, lancez votre outil de ligne de commande, accédez au dossier /wp-content/plugins de votre installation et exécutez la commande suivante :

 npx create-guten-block my-first-block

Vous devrez attendre une minute ou deux pendant que la structure du projet est créée et que les dépendances sont téléchargées :

Lorsque le processus est terminé, vous devriez voir l'écran suivant :

Cette image suivante montre la structure du projet avec le terminal exécuté dans Visual Studio Code :

Revenez maintenant à votre tableau de bord WordPress. Un nouvel élément devrait être listé dans l'écran Plugins — c'est le plugin my-first-block :

Activez le plugin et revenez au terminal. Changez le répertoire actuel en my-first-block , puis exécutez npm start :

 cd my-first-block npm start

Vous devriez obtenir la réponse suivante :

Encore une fois, cela vous permet d'exécuter le plugin en mode développement. Pour créer le code de production, vous devez utiliser :

 npm run build

Activez le plugin et créez un nouvel article ou une nouvelle page, puis parcourez vos blocs et sélectionnez votre tout nouveau bloc Gutenberg :

Pour un aperçu plus approfondi ou en cas d'erreurs, reportez-vous à la documentation fournie par Ahmad Awais.

Présentation de l'échafaudage du bloc de démarrage

Quel que soit l'un des deux outils de développement - create-block ou create-guten-block - pour lequel vous optez, vous disposez maintenant d'un échafaudage de blocs que vous pouvez utiliser comme point de départ pour créer un plugin de bloc.

Mais qu'est-ce exactement qu'un échafaudage en bloc ?

L'échafaudage de blocs est un terme abrégé qui décrit la structure de répertoires de support dont vous avez besoin pour que WordPress reconnaisse un bloc. En règle générale, ce répertoire comprend des fichiers tels que index.php , index.js , style.css et autres, qui à leur tour contiennent des appels tels que register_block_type .

Nous avons opté pour l'outil de développement officiel Create Block , tel qu'il est utilisé dans le manuel de l'éditeur de blocs. Mais même si vous décidez d'utiliser un outil tiers comme create-guten-block , votre expérience ne sera pas trop différente.

Cela dit, approfondissons l'outil create-block .

Un examen plus approfondi de l'outil de développement de création de blocs

Comme nous l'avons mentionné ci-dessus, Create Block est l'outil de ligne de commande officiel pour créer des blocs Gutenberg. L'exécution @wordpress/create-block dans votre terminal génère les fichiers et le code PHP, JS et SCSS nécessaires pour enregistrer un nouveau type de bloc :

 npx @wordpress/create-block [options] [slug]

• [slug] (optionnel) — utilisé pour assigner le bloc slug et installer le plugin
• [options] (optionnel) — options disponibles

Par défaut, un modèle ESNext est attribué. Cela signifie que vous obtiendrez la prochaine version de JavaScript, avec l'ajout de la syntaxe JSX.

Si vous omettez le nom du bloc, la commande s'exécute en mode interactif, vous permettant de personnaliser plusieurs options avant de générer les fichiers :

 npx @wordpress/create-block

L'image ci-dessous montre la structure de fichier d'un plugin de bloc créé avec l'outil officiel Créer un bloc :

Cela dit, passons en revue les principaux fichiers et dossiers de notre nouveau plugin de bloc.

Le fichier de plug-in

Avec le fichier de plugin principal, vous enregistrez le bloc sur le serveur :

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * Requires PHP: 7.0 * Version: 0.1.0 * Author: The WordPress Contributors * License: GPL-2.0-or-later * License URI: https://www.gnu.org/licenses/gpl-2.0.html * Text Domain: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

La fonction register_block_type enregistre un type de bloc sur le serveur à l'aide des métadonnées stockées dans le fichier block.json .

La fonction prend deux paramètres :

• Le nom du type de bloc, y compris l'espace de noms, ou un chemin d'accès au dossier où se trouve le fichier block.json , ou un objet WP_Block_Type complet
• Un tableau d'arguments de type bloc

Dans le code ci-dessus, l'argument du type de bloc est fourni par la constante magique __DIR__ . Cela signifie que le fichier block.json réside dans le même dossier que le fichier du plugin.

Le fichier package.json

Le fichier package.json définit les propriétés et les scripts JavaScript de votre projet. C'est ici que vous pouvez installer les dépendances de votre projet.

Pour mieux comprendre à quoi sert ce fichier, ouvrez-le avec votre éditeur de code préféré :

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

La propriété scripts est un dictionnaire contenant des commandes exécutées à différents moments du cycle de vie d'un package à l'aide de npm run [cmd] .

Dans cet article, nous utiliserons les commandes suivantes :

• npm run build — créer une version de production (compressée)
• npm run start - créer une version de développement (non compressée)

dependencies et devDependencies sont deux objets mappant un nom de package à une version. dependencies sont nécessaires en production, tandis que les devDependences ne sont nécessaires que pour le développement local (en savoir plus).

La seule dépendance de développement par défaut est le package @wordpress/scripts , qui est défini comme "une collection de scripts réutilisables adaptés au développement WordPress".

Le fichier block.json

À partir de WordPress 5.8, le fichier de métadonnées block.json est le moyen canonique d'enregistrer les types de blocs.

Avoir un fichier block.json offre plusieurs avantages, notamment des performances améliorées et une meilleure visibilité sur le répertoire des plugins WordPress :

Du point de vue des performances, lorsque les thèmes prennent en charge les ressources de chargement paresseux, les blocs enregistrés avec block.json verront leur mise en file d'attente optimisée dès le départ. Les ressources CSS et JavaScript frontales répertoriées dans les propriétés de style ou de script ne seront mises en file d'attente que lorsque le bloc sera présent sur la page, ce qui réduira la taille des pages.

L'exécution de la commande @wordpress/create-block génère le fichier block.json suivant :

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Voici la liste complète des propriétés par défaut :

• apiVersion — la version de l'API utilisée par le bloc (la version actuelle est 2)
• name — un identifiant unique pour un bloc incluant un espace de noms
• version — la version actuelle d'un bloc
• title — un titre d'affichage pour un bloc
• category — une catégorie de bloc
• icon — un slug Dashicon ou une icône SVG personnalisée
• description — une courte description visible dans l'inspecteur de blocs
• prend en supports - un ensemble d'options pour contrôler les fonctionnalités utilisées dans l'éditeur
• textdomain — le plugin text-domain
• editorScript — définition du script de l'éditeur
• editorStyle — définition du style de l'éditeur
• style — fournit des styles alternatifs pour un bloc

En plus des propriétés listées ci-dessus, vous pouvez (et le ferez probablement) définir un objet d' attributes fournissant des informations sur les données stockées par votre bloc. Dans votre block.json , vous pouvez définir n'importe quel nombre d'attributs dans des paires clé/valeur , où la clé est le nom de l'attribut et la valeur est la définition de l'attribut.

Examinez l'exemple suivant de définitions d'attribut :

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

Nous approfondirons le fichier block.json plus loin dans l'article, mais vous pouvez également consulter le manuel de l'éditeur de blocs pour obtenir des informations plus détaillées sur les métadonnées et les attributs block.json .

Le dossier src

Le dossier src est l'endroit où le développement se produit. Dans ce dossier, vous trouverez les fichiers suivants :

• index.js
• edit.js
• save.js
• éditeur.scss
• style.scss

index.js

Le fichier index.js est votre point de départ. Ici, vous allez importer des dépendances et enregistrer le type de bloc sur le client :

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

La première instruction importe la fonction registerBlockType du package @wordpress/blocks . Les instructions d'importation suivantes importent la feuille de style avec les fonctions d' Edit et d' save .

La fonction registerBlockType enregistre le composant sur le client. La fonction prend deux paramètres : un nom de bloc namespace/block-name (le même que celui enregistré sur le serveur) et un objet de configuration de bloc.

La fonction Edit fournit l'interface de bloc telle qu'elle est rendue dans l'éditeur de blocs, tandis que la fonction save fournit la structure qui sera sérialisée et enregistrée dans la base de données (en savoir plus).

edit.js

edit.js est l'endroit où vous allez créer l'interface d'administration du bloc :

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Tout d'abord, il importe la fonction __ du package @wordpress/i18n (ce package contient une version JavaScript des fonctions de traduction), le hook useBlockProps React et le fichier editor.scss .

Ensuite, il exporte le composant React (en savoir plus sur les instructions d'importation et d'exportation).

save.js

Le fichier save.js est l'endroit où nous construisons la structure de bloc à enregistrer dans la base de données :

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

editor.scss et style.scss

Outre les scripts, deux fichiers SASS résident dans les dossiers src . Le fichier editor.scss contient les styles appliqués au bloc dans le contexte de l'éditeur, tandis que le fichier style.scss contient les styles du bloc à afficher dans le frontend. Nous approfondirons ces fichiers dans la deuxième partie de ce guide.

Les dossiers node_modules et build

Le dossier node_modules contient les modules de nœud et leurs dépendances. Nous n'approfondirons pas les packages de nœuds car cela dépasse le cadre de cet article, mais vous pouvez en savoir plus dans cet article sur l'endroit où npm installe les packages.

Le dossier de build contient les fichiers JS et CSS résultant du processus de construction. Vous pouvez approfondir le processus de construction dans la syntaxe ESNext et les guides de configuration de la construction JavaScript.

Le projet : Construire votre premier bloc Gutenberg

Il est temps de se salir les mains. Cette section vous apprendra comment créer un plugin fournissant un bloc CTA nommé Affiliate Block.

Le bloc sera composé de deux colonnes, avec une image à gauche et un paragraphe de texte à droite. Un bouton avec un lien personnalisable sera placé sous le texte :

Ceci n'est qu'un exemple simple, mais il nous permet de couvrir les bases du développement de blocs de Gutenberg. Une fois que vous avez une compréhension claire des bases, vous pouvez continuer et créer des blocs Gutenberg de plus en plus complexes à l'aide du manuel de l'éditeur de blocs et de toute autre des vastes ressources disponibles.

En supposant que vous ayez la dernière version de WordPress en cours d'exécution sur votre environnement de développement local, voici ce que vous allez apprendre à partir de maintenant :

• Comment configurer le plugin Starter Block
• block.json au travail
• Utilisation des composants intégrés : le composant RichText
• Ajout de contrôles à la barre d'outils de bloc
• Personnalisation de la barre latérale des paramètres de bloc
• Ajouter et personnaliser un lien externe
• Ajout de plusieurs styles de bloc
• Imbriquer des blocs avec le composant InnerBlocks
• Améliorations supplémentaires

À vos marques… prêts… partez !

Comment configurer le plugin Starter Block

Lancez votre outil de ligne de commande et accédez au dossier /wp-content/plugins :

Maintenant, exécutez la commande suivante :

 npx @wordpress/create-block

Cette commande génère les fichiers PHP, SCSS et JS pour enregistrer un bloc en mode interactif, vous permettant d'ajouter facilement les données nécessaires à votre bloc. Pour notre exemple, nous utiliserons les détails suivants :

• Bloquer le slug : mon-bloc-affilié
• Espace de noms interne : my-affiliate-plugin
• Titre d'affichage du bloc : Bloc affilié
• Courte description du bloc : Un exemple de bloc pour les lecteurs Kinsta
• Dashicon : l'argent
• Nom de la catégorie : conception
• Auteur du plugin : votre nom
• Licence : –
• Lien vers le texte de la licence : –
• Version actuelle du plugin : 0.1.0

L'installation du plugin et de toutes les dépendances prend quelques minutes. Une fois le processus terminé, vous verrez la réponse suivante :

Maintenant, exécutez la commande suivante depuis le dossier /wp-content/plugins :

 cd my-affiliate-block

Enfin, depuis le dossier de votre plugin ( my-affiliate-block dans notre exemple), vous pouvez commencer le développement avec :

 npm start

Ouvrez maintenant l'écran Plugins pour trouver et activer le plugin Affiliate Block :

Créez un nouveau message, ouvrez le bloc d'insertion et faites défiler jusqu'à la catégorie Design . Cliquez pour ajouter le bloc d'affiliation :

block.json au travail

Comme nous l'avons mentionné précédemment, l'enregistrement du bloc côté serveur a lieu dans le fichier principal .php . Cependant, nous ne définirons pas les paramètres dans le fichier .php . Au lieu de cela, nous utiliserons le fichier block.json .

Alors, ouvrez à nouveau block.json et examinez de plus près les paramètres par défaut :

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

Scénarios et styles

editorScript , editorStyle et style fournissent les chemins relatifs aux scripts et styles frontaux et principaux.

Vous n'avez pas besoin d'enregistrer manuellement les scripts et les styles définis ici car ceux-ci sont automatiquement enregistrés et mis en file d'attente par WordPress. Pour le prouver, lancez l'inspecteur du navigateur et ouvrez l'onglet Réseau :

Comme vous pouvez le voir sur l'image ci-dessus, notre script index.js résidant dans le dossier build a été régulièrement mis en file d'attente sans avoir à ajouter de code PHP .

Enregistrez-vous pour recevoir le bulletin d'informations

Vous voulez savoir comment nous avons augmenté notre trafic de plus de 1000 % ?

Rejoignez plus de 20 000 autres personnes qui reçoivent notre newsletter hebdomadaire avec des conseils WordPress d'initiés !

Abonnez-vous maintenant

Étiquettes de l'interface utilisateur

Les propriétés title et description fournissent les libellés nécessaires pour identifier le bloc dans l'éditeur :

Mots clés

Comme nous l'avons mentionné précédemment, vous pouvez configurer avec précision les paramètres de votre bloc à l'aide de propriétés et d'attributs. Par exemple, vous pouvez ajouter un ou plusieurs keywords pour aider les utilisateurs à rechercher des blocs :

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

Localisation

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

Ce code génère un bloc statique avec du texte simple et non modifiable. Mais on peut changer les choses facilement :

Pour rendre le texte modifiable, vous devrez remplacer la <p> actuelle par un composant qui rend le contenu d'entrée modifiable. Pour cela, Gutenberg fournit le composant RichText intégré.

L'ajout d'un composant intégré à votre bloc est un processus en 5 étapes :

1. Importer les composants requis à partir d'un package WordPress
2. Incluez les éléments correspondants dans votre code JSX
3. Définissez les attributs nécessaires dans le fichier block.json
4. Définir les gestionnaires d'événements
5. Enregistrer des données

Étape 1 : Importer les composants requis à partir d'un package WordPress

Ouvrez maintenant le fichier edit.js et modifiez l'instruction import suivante :

 import { useBlockProps } from '@wordpress/block-editor';

…pour:

 import { useBlockProps, RichText } from '@wordpress/block-editor';

De cette façon, vous importez la fonction useBlockProps et le composant RichText du package @wordpress/block-editor .

utiliserBlockProps

Le hook useBlockProps React marque l'élément wrapper du bloc :

Lorsque vous utilisez l'API version 2, vous devez utiliser le nouveau hook useBlockProps dans la fonction d' edit du bloc pour marquer l'élément wrapper du bloc. Le crochet insérera les attributs et les gestionnaires d'événements nécessaires pour activer le comportement de bloc. Tous les attributs que vous souhaitez transmettre à l'élément de bloc doivent être transmis via useBlockProps et la valeur renvoyée doit être répartie sur l'élément.

Pour faire simple, useBlockProps attribue automatiquement des attributs et des classes à l'élément wrapper (l'élément p dans notre exemple) :

Si vous supprimez useBlockProps de l'élément wrapper, vous aurez une simple chaîne de texte sans accès à la fonctionnalité et au style du bloc :

Comme nous l'expliquerons plus tard, vous pouvez également passer à useBlockProps un objet de propriétés pour personnaliser la sortie.

Texte riche

Le composant RichText fournit une entrée modifiable par le contenu, permettant aux utilisateurs de modifier et de formater le contenu.

Vous trouverez le composant documenté sur GitHub à gutenberg/packages/block-editor/src/components/rich-text/README.md.

Étape 2 : Inclure les éléments correspondants dans votre code JSX

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

Commentons le code ligne par ligne :

• tagName — le nom de la balise de l'élément HTML modifiable
• onChange — fonction appelée lorsque le contenu de l'élément change
• allowedFormats — un tableau de formats autorisés. Par défaut, tous les formats sont autorisés
• value — la chaîne HTML à rendre modifiable
• placeholder - texte d'espace réservé à afficher lorsque l'élément est vide

Étape 3 : Définir les attributs nécessaires dans le fichier block.json

Les attributs fournissent des informations sur les données stockées par un bloc, telles que le contenu riche, la couleur d'arrière-plan, les URL, etc.

Vous pouvez définir un nombre arbitraire d'attributs dans un objet d' attributes dans des paires clé/valeur, où la clé est le nom de l'attribut et la valeur est la définition de l'attribut.

Ouvrez maintenant le fichier block.json et ajoutez les attributes suivants :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

L'attribut content permet de stocker le texte saisi par l'utilisateur dans le champ éditable :

• type indique le type de données stockées par l'attribut. Le type est obligatoire sauf si vous définissez une propriété enum .
• source définit comment la valeur de l'attribut est extraite du contenu de la publication. Dans notre exemple, il s'agit du contenu HTML. Notez que si vous ne fournissez pas de propriété source, les données sont stockées dans le délimiteur de bloc (en savoir plus).
• selector est une balise HTML ou tout autre sélecteur, tel qu'un nom de classe ou un attribut id.

Nous allons passer à la fonction Edit un objet de propriétés. Revenez donc au fichier edit.js et apportez la modification suivante :

 export default function Edit( { attributes, setAttributes } ) { ... }

Étape 4 : Définir les gestionnaires d'événements

L'élément RichText a un attribut onChange , fournissant une fonction à appeler lorsque le contenu de l'élément change.

Définissons cette fonction et voyons l'ensemble du script edit.js :

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

Maintenant, enregistrez le fichier et exécutez npm run start dans la fenêtre de votre terminal. Ensuite, revenez à votre tableau de bord WordPress, créez un nouvel article ou une nouvelle page et ajoutez votre bloc Affilié :

Ajoutez du texte et passez en mode Code. Voici à quoi votre code devrait ressembler :

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Si vous enregistrez maintenant la page et vérifiez le résultat de l'interface, vous risquez d'être un peu déçu car vos modifications n'affectent pas le site. C'est parce que vous devez modifier le fichier save.js pour stocker les entrées de l'utilisateur dans la base de données lorsque la publication est enregistrée.

Étape 5 : Enregistrer les données

Ouvrez maintenant le fichier save.js et modifiez le script comme suit :

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

C'est ce que nous faisons ici :

• Importez le composant RichText à partir du package de l' block-editor .
• Passez plusieurs propriétés via un argument d'objet à la fonction save (dans cet exemple, nous ne transmettons que la propriété attributes )
• Renvoie le contenu du composant RichText

Vous pouvez en savoir plus sur le composant RichText dans le manuel de l'éditeur de blocs et trouver la liste complète des accessoires sur Github.

Allons maintenant un peu plus loin. Dans la section suivante, vous apprendrez à ajouter des contrôles à la barre d'outils des blocs.

Ajout de contrôles à la barre d'outils de bloc

La barre d'outils du bloc contient un ensemble de commandes permettant aux utilisateurs de manipuler des parties du contenu du bloc. Pour chaque contrôle de la barre d'outils, vous trouverez un composant :

Par exemple, vous pouvez ajouter un contrôle d'alignement du texte pour votre bloc. Tout ce que vous avez à faire est d'importer deux composants du package @wordpress/block-editor .

Nous suivrons les mêmes étapes que dans l'exemple précédent :

1. Importer les composants requis à partir des packages WordPress
2. Inclure les éléments correspondants dans votre code JSX
3. Définir les attributs nécessaires dans le fichier block.json
4. Définir les gestionnaires d'événements
5. Enregistrer des données

Étape 1 : Importer les composants BlockControls et AlignmentControl depuis @wordpress/block-editor

Pour ajouter un contrôle d'alignement à la barre d'outils du bloc, vous avez besoin de deux composants :

• BlockControls une barre d'outils dynamique de contrôles (non documentée).
• AlignmentControl rend un menu déroulant qui affiche les options d'alignement pour le bloc sélectionné (en savoir plus)

Ouvrez le fichier edit.js et modifiez l'instruction d' import comme indiqué ci-dessous :

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

Étape 2 : Ajouter des éléments BlockControls et AlignmentControl

Accédez à la fonction Edit et insérez l'élément <BlockControls /> au même niveau que <RichText /> . Ajoutez ensuite et <AlignmentControl /> dans <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Dans le code ci-dessus, <> et </> sont la syntaxe courte pour déclarer les fragments React, qui nous permettent de renvoyer plusieurs éléments dans React.

Dans cet exemple, AlignmentControl a deux attributs :

• value fournit la valeur actuelle de l'élément
• onChange fournit un gestionnaire d'événements à exécuter lorsque la valeur change

Nous avons également défini des attributs supplémentaires pour l'élément RichText (consultez la liste complète des attributs avec des exemples)

Étape 3 : Définir l'attribut align dans block.json

Allez maintenant dans le fichier block.json et ajoutez l'attribut align :

 "align": { "type": "string", "default": "none" }

Revenez au terminal, arrêtez le processus en cours avec ^C et redémarrez le script avec npm run start . Retournez ensuite dans l'éditeur de blocs, actualisez la page et sélectionnez le bloc. Vous devriez voir la barre d'outils du bloc avec un contrôle d'alignement :

Maintenant, si vous essayez de formater le contenu du bloc à l'aide des nouvelles commandes d'alignement, vous verrez que rien ne se passe. C'est parce que nous n'avons pas encore défini le gestionnaire d'événements.

Étape 4 : Définir les gestionnaires d'événements

Définissez maintenant onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

Si newAlign est undefined , alors nous définissons newAlign sur none . Sinon, nous utilisons newAlign .

Notre script edit.js devrait être complet (pour l'instant) :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

Vous pouvez maintenant revenir à l'éditeur et aligner le contenu du bloc.

Nous devons modifier la fonction de sauvegarde pour stocker le contenu et les attributs du bloc dans la base de données.

Étape 5 : Enregistrer les données

Ouvrez save.js et modifiez la fonction de save comme suit :

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

Enfin, pour rendre le code plus lisible, vous pouvez extraire les propriétés individuelles de l'objet attribute à l'aide de la syntaxe d'affectation déstructurante :

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

Enregistrez le fichier, relancez le processus et revenez dans l'éditeur en mode Editeur de code. Le code devrait ressembler à ceci :

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

Et c'est tout! Vous venez d'ajouter un contrôle d'alignement à la barre d'outils du bloc

Vous pouvez en savoir plus sur les commandes de la barre d'outils de bloc dans le manuel de l'éditeur de blocs.

Personnalisation de la barre latérale des paramètres de bloc

Vous pouvez également ajouter des contrôles à la barre latérale des paramètres du bloc (ou même créer une nouvelle barre latérale pour votre application).

L'API fournit un composant InspectorControls pour cela.

Le manuel de l'éditeur de blocs explique comment utiliser la barre latérale des paramètres :

La barre latérale des paramètres est utilisée pour afficher les paramètres moins souvent utilisés ou les paramètres qui nécessitent plus d'espace à l'écran. La barre latérale Paramètres ne doit être utilisée que pour les paramètres au niveau du bloc .

Si vous avez des paramètres qui n'affectent que le contenu sélectionné à l'intérieur d'un bloc (exemple : le paramètre "gras" pour le texte sélectionné à l'intérieur d'un paragraphe) : ne le placez pas dans la barre latérale des paramètres. La barre latérale des paramètres s'affiche même lors de la modification d'un bloc en mode HTML. Elle ne doit donc contenir que des paramètres au niveau du bloc.

De nouveau:

1. Importer les composants requis à partir des packages WordPress
2. Inclure les éléments correspondants dans votre code JSX
3. Définir les attributs nécessaires dans le fichier block.json
4. Définir les gestionnaires d'événements
5. Enregistrer des données

Étape 1. Importer les composants InspectorControls et PanelColorSettings depuis @wordpress/block-editor

Vous pouvez ajouter plusieurs contrôles pour permettre aux utilisateurs de personnaliser des aspects spécifiques du bloc. Par exemple, vous pouvez fournir un panneau de contrôle des couleurs. Pour ce faire, vous devrez importer les composants InspectorControls et PanelColorSettings depuis le module block-editor :

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

Étape 2 : Inclure les éléments correspondants dans votre code JSX

Vous pouvez maintenant ajouter les éléments correspondants au JSX renvoyé par la fonction Edit :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

Notez que nous avons également mis à jour l'attribut style de l'élément RichText :

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

Étape 3 : Définir les attributs nécessaires dans block.json

Définissez maintenant les attributs backgroundColor et textColor dans le fichier block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

Étape 4 : Définir les gestionnaires d'événements

Vous devez maintenant définir deux fonctions pour mettre à jour backgroundColor et textColor lors de l'entrée de l'utilisateur :

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

Étape 5 : Enregistrer les données

Une dernière étape : ouvrez le fichier save.js et modifiez le script comme suit :

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

Maintenant, arrêtez le processus (^C) et exécutez à nouveau npm run start . Actualisez la page, supprimez toute instance de votre bloc et ajoutez-la à nouveau à votre publication :

Effectuez vos modifications, enregistrez la publication et affichez-la dans l'interface. Les modifications que vous avez apportées dans l'éditeur de blocs doivent être reflétées sur le site avant.

Ajouter et personnaliser un lien externe

Dans cette section, vous allez ajouter de nouveaux composants à votre type de bloc :

• Un composant ExternalLink permettant aux utilisateurs d'ajouter un lien personnalisable au bloc Affilié
• Plusieurs contrôles de la barre latérale permettant aux utilisateurs de personnaliser les paramètres de lien

Étape 1. Importer des composants depuis @wordpress/components

Vous devez maintenant importer plusieurs composants de @wordpress/components . Ouvrez votre fichier edit.js et ajoutez l'instruction import suivante :

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• PanelBody ajoute un conteneur pliable à la barre latérale des paramètres.
• PaneRow produit un conteneur générique pour les contrôles de la barre latérale.
• TextControl fournit un contrôle de saisie de texte.
• ToggleControl fournit une bascule permettant aux utilisateurs d'activer/désactiver une option spécifique
• ExternalLink est un composant simple pour ajouter un lien externe.

Étape 2. Incluez les éléments correspondants dans votre code JSX

Vous allez d'abord ajouter l'élément ExternalLink au même niveau de RichText dans un conteneur div :

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

Le composant ExternalLink n'étant pas documenté, nous nous sommes référés au composant lui-même pour obtenir la liste des attributs disponibles. Ici, nous utilisons les href , className et rel .

Par défaut, la valeur de l'attribut rel est définie sur noopener noreferrer . Notre code ajoutera le mot-clé nofollow à l' rel de la balise a résultante lorsque le contrôle bascule est activé .

Vous pouvez maintenant ajouter des paramètres de lien à la barre latérale du bloc.

Tout d'abord, vous allez ajouter un élément PanelBody dans InspectorControls au même niveau que PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

Voici ce que nous faisons avec ceci :

1. L'attribut title fournit le titre du panneau.
2. initialOpen définit si le panneau est initialement ouvert ou non.

Ensuite, nous ajouterons deux éléments PanelRow à l'intérieur PanelBody et un élément TextControl à l'intérieur de chaque PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

Le code ci-dessus devrait maintenant sembler assez simple. Les deux contrôles de texte permettent aux utilisateurs de définir le libellé du lien et l'URL.

Nous ajouterons également un PanelRow supplémentaire avec un ToggleControl pour activer/désactiver une option spécifique, telle que l'inclusion ou non d'un attribut :

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

Étape 3 : Définir les attributs nécessaires dans block.json

Définissez maintenant les linkLabel affiliateLink hasLinkNofollow dans le fichier block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

Rien de plus à ajouter ici ! Passons à la définition des fonctions de gestion des événements.

Étape 4 : Définir les gestionnaires d'événements

Revenez au fichier edit.js et ajoutez les fonctions suivantes :

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

Ces fonctions mettent à jour les valeurs d'attribut correspondantes lors de l'entrée de l'utilisateur.

Étape 5 : Enregistrer les données

Enfin, nous devons mettre à jour la fonction de save dans save.js :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

Notez qu'ici nous avons utilisé a élément a régulier au lieu de ExternalLink :

Maintenant, enregistrez les données et redémarrez votre environnement.

Ajout de plusieurs styles de bloc

Dans une section précédente, vous avez appris à ajouter un contrôle de barre d'outils de bloc permettant aux utilisateurs d'aligner l'entrée de l'utilisateur. Nous pouvons ajouter plus de contrôles de style à la barre d'outils de bloc, mais nous pouvons également fournir un ensemble de styles de bloc prédéfinis parmi lesquels l'utilisateur peut choisir en un seul clic.

Pour cela, nous allons utiliser une fonctionnalité utile de l'API Block : Block Styles.

Il vous suffit de définir la propriété block.json styles et de déclarer les styles correspondants dans vos feuilles de style.

Par exemple, vous pouvez ajouter le tableau de styles suivant :

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

Avec cela, vous venez d'ajouter un style par défaut et un style supplémentaire appelé border . Revenez maintenant à l'éditeur de blocs :

Les styles seront disponibles pour l'utilisateur en cliquant sur le sélecteur de bloc, puis en recherchant le panneau Styles dans la barre latérale des paramètres de bloc .

Sélectionnez un style et vérifiez les classes appliquées à l'élément p . Faites un clic droit sur le bloc et Inspecter . Une nouvelle classe a été ajoutée avec un nom structuré comme suit :

 is-style-{style-name}

Si vous avez coché le style "Border", alors une classe is-style-border sera ajoutée à l'élément p . Si vous avez coché le style "Default", une classe is-style-default sera ajoutée à la place.

Il ne vous reste plus qu'à déclarer les propriétés CSS. Ouvrez le fichier editor.scss et remplacez les styles actuels par les suivants :

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Maintenant, vous pouvez faire la même chose avec style.scss :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

Arrêtez le processus (^C) et exécutez à nouveau npm run start .

Et c'est tout! Actualisez la page et amusez-vous avec vos nouveaux styles de blocs :

Imbrication de blocs Gutenberg avec le composant InnerBlocks

Bien que pleinement fonctionnel, notre bloc d'affiliation n'est toujours pas très attrayant. Pour le rendre plus attrayant pour le public, nous pourrions ajouter une image.

Cela peut ajouter une couche de complexité à notre bloc, mais heureusement, vous n'avez pas besoin de réinventer la roue car Gutenberg fournit un composant spécifique que vous pouvez utiliser pour créer une structure de blocs imbriqués.

Le composant InnerBlocks est défini comme suit :

InnerBlocks exporte une paire de composants qui peuvent être utilisés dans les implémentations de blocs pour activer le contenu de bloc imbriqué.

Tout d'abord, vous devrez créer un nouveau fichier .js dans le dossier src . Dans notre exemple, nous appellerons ce fichier container.js .

Vous devez maintenant importer la nouvelle ressource dans le fichier index.js :

 import './container';

Revenez à container.js et importez les composants nécessaires :

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

L'étape suivante consiste à définir un modèle fournissant la structure à l'intérieur de laquelle les blocs seront placés. Dans l'exemple suivant, nous définissons un modèle composé de deux colonnes contenant un bloc Image principal et notre bloc Affilié personnalisé :

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

Le modèle est structuré comme un tableau de blockTypes (nom de bloc et attributs facultatifs).

Dans le code ci-dessus, nous avons utilisé plusieurs attributs pour configurer les blocs Columns et Column. Plus précisément, l'attribut templateLock: 'all' verrouille les blocs Column afin que l'utilisateur n'ajoute, ne réorganise ou ne supprime des blocs existants. templateLock peut prendre l'une des valeurs suivantes :

• all — InnerBlocks est verrouillé et aucun bloc ne peut être ajouté, réorganisé ou supprimé.
• insert — Les blocs peuvent uniquement être réorganisés ou supprimés.
• false — Le modèle n'est pas verrouillé.

Le modèle est ensuite affecté à l'élément InnerBlocks :

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

Pour éviter tout problème de compatibilité, nous avons également ajouté un attribut templateLock au composant InnerBlocks (voir aussi issue #17262 et pull #26128).

Voici notre fichier container.js final :

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

Améliorations supplémentaires

Notre bloc est entièrement fonctionnel, mais nous pourrions l'améliorer un peu avec quelques petits changements.

Nous avons attribué l'attribut backgroundColor au paragraphe généré par le composant RichText . Cependant, nous préférons peut-être attribuer la couleur de fond au conteneur div :

Donc, modifiez le fichier edit.js et save.js div comme suit :

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

Cela permettra à l'utilisateur de changer l'arrière-plan du bloc entier.

D'autre part, un changement plus pertinent implique la méthode useBlockProps . Dans le code d'origine, nous avons défini la constante blockProps comme suit :

 const blockProps = useBlockProps();

Mais nous pouvons utiliser useBlockProps plus efficacement en passant un ensemble de propriétés. Par exemple, nous pouvons importer des noms de classe à partir du module classnames et définir le nom de la classnames wrapper en conséquence.

Dans l'exemple suivant, nous attribuons un nom de classe basé sur la valeur de l'attribut align ( edit.js ) :

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

Nous ferons le même changement dans le fichier save.js :

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

Et c'est un enveloppement! Vous pouvez maintenant exécuter la génération pour la production.

Résumé

Et nous voilà arrivés à la fin de cet incroyable voyage ! Nous avons commencé par la configuration de l'environnement de développement et avons fini par créer un type de bloc complet.

Comme nous l'avons mentionné dans l'introduction, une solide connaissance de Node.js, Webpack, Babel et React est essentielle pour créer des blocs Gutenberg avancés et vous positionner sur le marché en tant que développeur Gutenberg professionnel.

Mais vous n'avez pas besoin d'avoir une expérience React établie pour commencer à vous amuser avec le développement de blocs. Le développement de blocs pourrait vous donner la motivation et les objectifs pour acquérir des compétences de plus en plus larges dans les technologies derrière les blocs Gutenberg.

Ce guide est donc loin d'être complet. Il s'agit simplement d'une introduction à une grande variété de sujets qui vous aideront à commencer à construire vos tout premiers blocs Gutenberg.

Pour cette raison, nous vous recommandons d'approfondir vos connaissances en lisant attentivement la documentation et les guides en ligne. Parmi les nombreuses ressources disponibles, nous recommandons ce qui suit :

• Tutoriel officiel Créer un bloc pour les débutants
• Tutoriel officiel sur les blocs pour les développeurs intermédiaires
• Blocs dynamiques
• Méta-boîtes
• Créer une barre latérale pour votre plugin

Si vous débutez dans le développement WordPress, vous souhaiterez peut-être comprendre les concepts de base du développement frontal. Voici une liste rapide de ressources qui peuvent vous aider à démarrer :

• Comment installer WordPress localement (ebook gratuit)
• La vraie valeur de l'hébergement WordPress géré (ebook gratuit)
• Qu'est-ce que JavaScript ?
• HTML contre HTML5
• Comment modifier le CSS dans WordPress
• Qu'est-ce que PHP ?
• Le Bootcamp des crochets WordPress : comment utiliser les actions, les filtres et les crochets personnalisés

Et rappelez-vous que le code complet des exemples de ce guide est disponible sur Gist.

Maintenant c'est à vous : avez-vous développé des blocs Gutenberg ? Quelles sont les principales difficultés que vous avez rencontrées jusqu'à présent ? Faites-nous part de votre expérience dans les commentaires !