De nombreuses personnes se plaignent des obstacles à surmonter pour se lancer dans la construction de blocs et d’applications Gutenberg. La courbe d’apprentissage est raide, principalement en raison de la difficulté d’installer et de configurer l’environnement de développement. En outre, 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 de WordPress fournit aux développeurs une quantité considérable d’informations, mais vous risquez de vous perdre dans cette mer de détails.
Et il convient de mentionner ce que Matías Ventura, architecte principal du projet Gutenberg, a rapporté dans son entretien avec WP Tavern :
Bien que certaines personnes puissent l’apprendre rapidement, c’est toujours un obstacle important pour les gens. Je pense qu’il y a plusieurs niveaux à cela ; la documentation pourrait être améliorée d’un ordre de grandeur à la fois dans l’organisation et la présentation. J’espère que nous pourrons faire beaucoup plus dans ce domaine.
Dans cette optique, nous avons décidé de fournir un tutoriel étape par étape visant à aider nos lecteurs à se lancer dans le développement de blocs Gutenberg.
Cela vous semble intéressant ? Plongeons-y !
Conditions préalables au développement de bloc Gutenberg
Pour ce tutoriel, les seules compétences requises sont une bonne connaissance du développement d’extensions WordPress et au moins une compréhension basique de HTML, CSS, JavaScript et React.
S’agira-t-il d’un projet ambitieux ? Bien sûr qu’il le sera !
Il n’a pas été facile de trouver le bon compromis entre exhaustivité et simplicité, ni de décider des sujets à inclure et de ceux à laisser de côté.
Espérons que les lecteurs intermédiaires et avancés nous pardonneront de ne pas approfondir certains concepts tels que React state, Redux store, les composants d’ordre élevé, etc. Ces sujets nécessitent un espace et une attention supplémentaires et sont probablement trop avancés pour le développement de blocs par des débutants (à moins que vous ne soyez 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 des blocs Gutenberg, tels que les blocs dynamiques et les boîtes méta.
Grâce aux connaissances que vous aurez acquises à la fin de cet article, vous pourrez commencer dès maintenant à vous amuser et à être productif.
Une fois que vous aurez commencé à construire des blocs, vous serez en mesure d’améliorer vos compétences et de 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é sur tous les plans : des API plus puissantes, une interface utilisateur plus avancée, une utilisibalité améliorée, une tonne de nouveaux blocs, les premières implémentations de Full Site Editing, 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 du développeur, Gutenberg est une application mono-page (Single Page Application ou 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 que cela soit clair :
Dans Gutenberg, le contenu est divisé en blocs, qui sont des « briques » que les utilisateurs peuvent utiliser pour créer des articles et des pages ou leurs sites web.
Mais techniquement, qu’est-ce qu’un bloc ?
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 les codes courts, le HTML personnalisé et la découverte d’intégration dans une API et une expérience utilisateur uniques et cohérentes.
Les titres, paragraphes, colonnes, images, galeries et tous les éléments qui composent l’interface de l’éditeur, des panneaux de la colonne latérale aux commandes de la barre d’outils du 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. Ils servent le même objectif que les fonctions JavaScript, mais fonctionnent de manière isolée et renvoient du HTML via une fonction
render().
Alors que l’expérience d’édition délivrée par Gutenberg est nouvelle par rapport à l’éditeur classique de WordPress, la façon dont WordPress stocke vos morceaux de contenu dans la base de données ne change pas du tout. C’est parce que Gutenberg est une application qui fonctionne au sein de WordPress, mais qui ne change pas la façon dont le CMS fonctionne en son cœur.
Les publications (et cela inclut les articles, 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 publications créées via l’éditeur classique et Gutenberg.
Ces éléments d’information ressemblent à des commentaires HTML, et ils ont une fonction spécifique : délimiter des blocs :
Les délimiteurs de bloc indiquent à WordPress quel bloc doit être rendu à l’écran. Ils fournissent également des valeurs pour les propriétés du bloc dans un objet JSON. Ces propriétés déterminent la manière dont le bloc doit être rendu à l’écran :
wp_posts.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 le 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 fastidieux.
Pour garder les choses simples, nous ne couvrirons pas la transpilation dans cet article (avec laquelle nous vous recommandons néanmoins de vous familiariser une fois que vous aurez appris les bases du développement par blocs). Au lieu de cela, nous allons présenter deux outils alternatifs que vous pouvez utiliser pour mettre en place rapidement et facilement un environnement de développement JavaScript moderne en quelques minutes. C’est à vous de choisir celui qui vous convient le mieux pour votre projet.
La mise en place d’un environnement de développement JavaScript pour construire des blocs Gutenberg est un processus en trois étapes :
Commençons.
1. Installer 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 paquets Node (npm).
Vous pouvez installer Node.js et npm de plusieurs façons différentes. Mais d’abord, vous pouvez vérifier si le logiciel est déjà installé sur votre machine.
Pour ce faire, lancez le terminal et exécutez la commande suivante :
node -vSi le résultat est commande non trouvée, alors 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, qui est le Node Installer. Tout ce que vous devez faire est 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 vous avez le paquet npm disponible.
Vous êtes maintenant équipé des outils suivants :
- Le gestionnaire de paquets node.js
npx. Cela vous permet d’exécuter une commandenpmsans l’installer au préalable. - Le gestionnaire de paquets
npmNode.js (voir docs). Il est utilisé pour installer les dépendances et exécuter les scripts.
L’étape suivante consiste à installer l’environnement de développement.
2. Configurer votre environnement de développement
Une fois que vous aurez installé les dernières versions de Node.js et de 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 officiel de WordPress. Jetons un coup d’œil aux deux options.
Option 1 : Environnement de développement local (DevKinsta)
En quelques clics, vous pouvez installer WordPress localement en utilisant DevKinsta, notre outil moderne de développement local de WordPress. Vous pouvez également 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 officielwp-env , qui fournit un environnement de développement WordPress local que vous pouvez lancer directement à partir de la ligne de commande. Noah Alen le définit comme suit :
Les environnements locaux de WordPress sont maintenant aussi simples que l’exécution d’une seule commande.
wp-envest un outil sans configuration pour des environnements locaux de WordPress sans douleur. 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 autre.
Si vous décidez d’essayer, l’installation de wp-env ne demande qu’un effort minimal. Il suffit de suivre les étapes suivantes :
Étape 1 : Confirmer l’installation de Docker et Node.js
Pour répondre aux exigences techniques, vous devrez d’abord avoir installé Docker et Node.js sur votre ordinateur. En effet, wp-env crée une instance Docker qui exécute un site web WordPress. Toute modification apportée au code est immédiatement répercutée dans l’instance WordPress.
Étape 2 : Installer @wordpress/env à partir de la ligne de commande
Une fois que Docker et Node.js fonctionnent sur votre ordinateur, vous pouvez passer à l’installation de l’environnement de développement WordPress.
Vous pouvez installer wp-env de manière globale ou locale. Pour l’installer globalement, vous devez exécuter la commande suivante à partir du répertoire des extensions (plus d’informations à ce sujet dans l’encadré « Important » ci-dessous) :
npm install -g @wordpress/envDécomposons ça :
npm installinstalle le paquet.- Le suffixe
-gajouté à la commande installe le paquet spécifié de manière globale. @wordpress/envest le paquet que vous allez installer.
Pour confirmer que wp-env a bien été installé, exécutez la commande suivante :
wp-env --versionVous devriez voir la version actuelle de wp-env, ce qui signifie que vous pouvez maintenant lancer l’environnement en utilisant la commande suivante depuis le dossier de votre extension :
wp-env startVous pouvez accéder au tableau de bord de WordPress en utilisant l’adresse suivante :
- http://localhost:8888/wp-admin/
Les informations d’identification par défaut sont les suivantes :
- Identifiant :
admin - Mot de passe :
password
Configurez votre extension de bloc
Vous avez maintenant besoin d’une extension de bloc de démarrage sur laquelle vous appuyer. Mais au lieu de créer manuellement une extension de bloc de développement avec tous les fichiers et répertoires nécessaires, vous pouvez simplement exécuter un outil de développement fournissant tous les fichiers et configurations dont vous avez besoin pour commencer le développement de blocs.
Là encore, vous avez le choix entre plusieurs options. Examinons chacune d’elles.
Option 1 : Configurer une extension de bloc avec @wordpress/create-block
@wordpress/create-block est l’outil officiel sans configuration pour la création de blocs Gutenberg :
Create Block est un moyen officiellement supporté de créer des blocs pour enregistrer un bloc pour une extension WordPress. Il offre une configuration de construction moderne sans aucune 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. Un grand bravo à @gaearon, à toute l’équipe de 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 commande npx @wordpress/create-block, et il fournira tous les fichiers et répertoires dont vous avez besoin pour créer l’échafaudage de l’extension et enregistrer un nouveau bloc.
Faisons un test pour voir comment cela fonctionne.
À partir de 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-blockLorsqu’on vous demande de confirmer, saisissez y pour continuer :
Le processus prend quelques instants. Une fois qu’il est terminé, vous devriez obtenir la réponse suivante :
Et c’est tout !
Lancez maintenant votre environnement de développement WordPress et allez à l’écran des Extensions dans le tableau de bord de WordPress. Une nouvelle extension nommé « My First Block » devrait avoir été ajoutée à votre liste d’extensions :
Activez l’extension si nécessaire, créez un nouvel article de blog, faites défiler l’outil dinsertion de blocs jusqu’à la section Widgets, et sélectionnez votre nouveau bloc :
Maintenant, retournez au terminal et changez le répertoire courant en my-first-block :
cd my-first-blockEnsuite, exécutez la commande suivante :
npm startCela vous permet d’exécuter l’extension en mode développement. Pour créer le code de production, vous devez utiliser la commande suivante :
npm run buildOption 2 : Configuration d’une extension de bloc avec create-guten-block
create-guten-block est un outil de développement tiers pour la construction de blocs Gutenberg :
create-guten-blockest un dev-toolkit 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 première extension de bloc sans problème.
La boîte à outils fournit tout ce dont vous avez besoin pour créer une extension WordPress moderne, notamment les éléments suivants :
- Prise en charge des syntaxes React, JSX et ES6.
- Processus de construction de webpack pour le développement et la production en arrière-plan.
- Les extras du langage au-delà de l’ES6, comme l’opérateur d’étalement d’objet.
- CSS auto-préfixé, de sorte que vous n’avez pas besoin de -webkit ou d’autres préfixes.
- Un script de construction pour regrouper JS, CSS et images pour la production avec des cartes de source.
- Mises à jour sans problème pour les outils ci-dessus avec une seule dépendance cgb-scripts.
Il convient de noter l’avertissement suivant :
La contrepartie est que ces outils sont préconfigurés pour fonctionner d’une manière spécifique. Si votre projet nécessite davantage de personnalisation, vous pouvez « l’éjecter » et le personnaliser, mais vous devrez alors maintenir cette configuration.
Une fois que vous avez un site WordPress local en main, lancez votre outil de ligne de commande, allez dans le répertoire /wp-content/plugins de votre installation, et exécutez la commande suivante :
npx create-guten-block my-first-blockVous 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 :
L’image suivante montre la structure du projet avec le terminal exécuté dans Visual Studio Code :
Retournez maintenant à votre tableau de bord WordPress. Un nouvel élément devrait être listé dans l’écran des extensions – il s’agit de l’extension my-first-block :
Activez l’extension et retournez dans le terminal. Changez le répertoire courant en my-first-block, puis lancez npm start :
cd my-first-block
npm startVous devriez obtenir la réponse suivante :
Encore une fois, cela vous permet d’exécuter l’extension en mode développement. Pour créer le code de production, vous devez utiliser :
npm run buildActivez l’extension 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’erreur, consultez la documentation fournie par Ahmad Awais.
Une visite guidée de l’échafaudage du Starter Block
Quel que soit l’outil de développement choisi (create-block ou create-guten-block), vous disposez maintenant d’un échafaudage de blocs que vous pouvez utiliser comme point de départ pour créer une extension de bloc.
Mais qu’est-ce qu’un échafaudage de bloc ?
L’échafaudage (scaffolding) de bloc est un terme abrégé qui décrit la structure de répertoire de soutien dont vous avez besoin pour que WordPress reconnaisse un bloc. En général, ce répertoire comprend des fichiers tels que index.php, index.js, style.css, et d’autres – qui contiennent à leur tour des appels comme
register_block_type.
Nous avons opté pour l’outil officiel Create Block, car 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.
Ceci étant dit, plongeons plus profondément dans l’outil create-block.
Un regard plus approfondi sur l’outil de développement Create Block
Comme nous l’avons mentionné plus haut, Create Block est l’outil officiel en ligne de commande pour créer des blocs Gutenberg. L’exécution de @wordpress/create-block dans votre terminal génère les fichiers PHP, JS, et SCSS et le code nécessaire pour enregistrer un nouveau type de bloc :
npx @wordpress/create-block [options] [slug][slug](facultatif) – permet d’attribuer le slug du bloc et d’installer l’extension.[options](facultatif) – 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, ce qui vous permet 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’une extension de bloc créée avec l’outil officiel Create Block :
Ceci étant dit, passons en revue les principaux fichiers et répertoire de notre nouvelle extension de bloc.
Le fichier de l’extension
Avec le fichier principal de l’extension, vous enregistrez le bloc sur le serveur :
<?php
/**
* Plugin Name: Kinsta Academy Block
* Plugin URI: https://kinsta.com/
* Description: An example block for Kinsta Academy students
* Requires at least: 5.9
* Requires PHP: 7.0
* Version: 0.1.0
* Author: Kinsta Students
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: ka-example-block
*
* @package ka-example-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/reference/functions/register_block_type/
*/
function ka_example_block_ka_example_block_block_init() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'ka_example_block_ka_example_block_block_init' );La fonction register_block_type enregistre un type de bloc sur le serveur en utilisant les métadonnées stockées dans le fichier block.json.
- Le nom du type de bloc, y compris l’espace de noms, ou un chemin d’accès au répertoire où se trouve le fichier block.json, ou un objet
WP_Block_Typecomplet. - Un tableau d’arguments de type de bloc
Dans le code ci-dessus, la constante magique __DIR__ renvoie le répertoire actuel. Cela signifie que le fichier block.json réside dans le sous-dossier /build.
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": "ka-example-block",
"version": "0.1.0",
"description": "An example block for Kinsta Academy students",
"author": "Kinsta Students",
"license": "GPL-2.0-or-later",
"homepage": "https://kinsta.com/",
"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",
"packages-update": "wp-scripts packages-update",
"plugin-zip": "wp-scripts plugin-zip",
"start": "wp-scripts start"
},
"devDependencies": {
"@wordpress/scripts": "^24.1.0"
},
"dependencies": {
"classnames": "^2.3.2"
}
}La propriété scripts est un dictionnaire contenant des commandes qui sont exécutées à différents moments du cycle de vie d’un paquet en utilisant npm run [cmd].
Dans cet article, nous utiliserons les commandes suivantes :
npm run build– crée un build de production (compressé)npm run startounpm start– crée un build de développement (non compressé)
dependencies et devDependencies sont deux objets faisant correspondre un nom de paquet à une version. dependencies est nécessaire en production, tandis que devDependences est uniquement nécessaire pour le développement local (en savoir plus).
La seule dépendance de développement par défaut est le paquet @wordpress/scripts, qui est défini comme « une collection de scripts réutilisables adaptés au développement de WordPress ».
Le fichier block.json
À partir de WordPress 5.8, le fichier de métadonnées block.json est la façon canonique d’enregistrer les types de blocs.
Le fait de disposer d’un fichier block.json présente plusieurs avantages, notamment une amélioration des performances et une meilleure visibilité dans le répertoire des extensions de WordPress :
Du point de vue des performances, lorsque les thèmes prennent en charge le chargement différé des ressources, la mise en file d’attente des ressources des blocs enregistrés avec block.json est optimisée dès le départ. Les ressources CSS et JavaScript frontend énumérées dans les propriétés de
styleou descriptne seront mises en file d’attente que lorsque le bloc sera présent sur la page, ce qui permettra de réduire la taille des pages.
L’exécution de la commande @wordpress/create-block génère le fichier block.json suivant :
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 2,
"name": "ka-example-block/ka-example-block",
"version": "0.1.0",
"title": "Kinsta Academy Block",
"category": "widgets",
"icon": "superhero-alt",
"description": "An example block for Kinsta Academy students",
"supports": {
"html": false
},
"textdomain": "ka-example-block",
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./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, y compris un espace de noms.version— la version actuelle d’un bloctitle— un titre d’affichage pour un bloccategory— une catégorie de blocicon— un slug Dashicon ou une icône SVG personnaliséendescription— une brève description visible dans l’inspecteur de blocsupports— un ensemble d’options pour contrôler les fonctionnalités utilisées dans l’éditeurtextdomain— le text-domain de l’extensioneditorScript— définition du script de l’éditeureditorStyle— définition du style de l’éditeurstyle— fournit des styles alternatifs pour un bloc
Outre les propriétés répertoriées ci-dessus, vous pouvez (et allez probablement) définir un objet attributes fournissant des informations sur les données stockées par votre bloc. Dans votre block.json, vous pouvez définir un nombre quelconque 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.
Regardez l’exemple suivant de définitions d’attributs :
"attributes": {
"content": {
"type": "array",
"source": "children",
"selector": "p"
},
"align": {
"type": "string",
"default": "none"
},
"link": {
"type": "string",
"default": "https://kinsta.com"
}
},Nous nous pencherons plus en détail sur 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 répertoire src
Le répertoire src est l’endroit où le développement se fait. Dans ce répertoire, vous trouverez les fichiers suivants :
- index.js
- edit.js
- save.js
- editor.scss
- style.scss
index.js
Le fichier index.js est votre point de départ. C’est ici que vous allez importer les 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';
import metadata from './block.json';
registerBlockType( metadata.name, {
/**
* @see ./edit.js
*/
edit: Edit,
/**
* @see ./save.js
*/
save,
} );La première déclaration importe la fonction registerBlockType depuis le paquetage @wordpress/blocks. Les instructions d’importation suivantes importent la feuille de style ainsi que les fonctions Edit et save, et un objet de métadonnées depuis le fichier block.json.
La fonction registerBlockType enregistre le composant sur le client. La fonction prend deux paramètres : un nom de bloc et un objet de configuration de bloc.
La fonction Edit fournit l’interface du 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 construire 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 paquet @wordpress/i18n (ce paquet contient une version JavaScript des fonctions de traduction), le crochet React useBlockProps et le fichier editor.scss.
Ensuite, il exporte le composant React (pour en savoir plus sur les déclarations d’importation et d’exportation).
save.js
Le fichier save.js est l’endroit où nous construisons la structure du bloc à sauvegarder 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 répertoires 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 pour l’affichage dans l’interface publique ainsi que dans l’éditeur. Nous nous pencherons plus en détail sur ces fichiers dans la deuxième partie de ce guide.
Les répertoires node_modules et build
Le répertoire node_modules contient les modules node et leurs dépendances. Nous n’allons pas nous plonger plus profondément dans les paquets node car cela dépasse le cadre de cet article, mais vous pouvez en lire plus dans cet article sur l’endroit où npm installe les paquets.
Le répertoire build contient les fichiers JS et CSS résultant du processus de construction. Vous pouvez approfondir le processus de construction dans les guides de syntaxe ESNext et 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 à créer une extension fournissant un bloc d’appel à action (CTA) nommé Kinsta Academy.
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 :
Ce n’est qu’un exemple simple, mais il nous permet de couvrir les bases du développement des blocs Gutenberg. Une fois que vous aurez bien compris les bases, vous pourrez vous lancer dans la création de blocs Gutenberg de plus en plus complexes avec l’aide du Block Editor Handbook et de toutes les autres ressources disponibles.
En supposant que vous avez la dernière version de WordPress sur votre environnement de développement local, voici ce que vous allez apprendre à partir de maintenant :
- Comment configurer l’extension Starter Block ?
- block.json au travail
- Utilisation des composants intégrés : Le composant RichText
- Ajout de contrôles à la barre d’outils du bloc
- Personnalisation de la colonne latérale des réglages du bloc
- Ajout et personnalisation d’un lien externe
- Ajout de styles de blocs multiples
- Emboîtement des blocs avec le composant InnerBlocks
- Améliorations supplémentaires
À vos marques…prêts… partez !
Comment configurer l’extension Starter Block ?
Lancez votre outil de ligne de commande et accédez au répertoire /wp-content/plugins :
Maintenant, exécutez la commande suivante :
npx @wordpress/create-blockCette commande génère les fichiers PHP, SCSS et JS pour l’enregistrement d’un bloc en mode interactif, ce qui vous permet d’ajouter facilement les données nécessaires à votre bloc. Pour notre exemple, nous utiliserons les données suivantes :
- Variante du modèle : statique
- Nom du bloc : ka-example-block
- Espace de noms interne : ka-example-block
- Titre d’affichage du bloc : Bloc Kinsta Academy
- Description courte du bloc : Un bloc d’exemple pour les étudiants de la Kinsta Academy
- Dashicon : superhero-altsuperhero-alt
- Nom de la catégorie : widgets
- Voulez-vous personnaliser l’extension WordPress? : oui
- La page d’accueil de l’extension : https://kinsta.com/
- Version actuelle de l’extension : 0.1.0
- Auteur de l’extension : votre nom
- Licence : –
- Lien vers le texte de la licence : –
- Chemin du domaine personnalisé pour les traductions : –
L’installation de l’extension et de toutes les dépendances prend quelques minutes. Lorsque le processus est terminé, vous verrez la réponse suivante :
Maintenant, exécutez la commande suivante depuis le répertoire /wp-content/plugins :
cd ka-example-block
Enfin, à partir du répertoire de votre extension (ka-example-block dans notre exemple), vous pouvez commencer à développer avec :
npm startOuvrez maintenant l’écran Extensions pour trouver et activer l’extension Kinsta Academy Block :
Créez un nouvel article, ouvrez le module d’insertion de blocs et faites défiler la liste jusqu’à la catégorie Design. Cliquez pour ajouter le bloc Kinsta Academy :
block.json au travail
Comme nous l’avons mentionné précédemment, l’enregistrement du bloc côté serveur a lieu dans le fichier .php principal. Cependant, nous ne définirons pas les réglages dans le fichier .php. Nous utiliserons plutôt le fichier block.json.
Ouvrez à nouveau le fichier block.json et examinez de plus près les réglages par défaut :
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 2,
"name": "ka-example-block/ka-example-block",
"version": "0.1.0",
"title": "Kinsta Academy Block",
"category": "widgets",
"icon": "superhero-alt",
"description": "An example block for Kinsta Academy students",
"supports": {
"html": false
},
"textdomain": "ka-example-block",
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./style-index.css"
}Scripts et styles
Les propriétés editorScript, editorStyle et style fournissent les chemins relatifs vers les scripts et les styles de l’interface publique et de l’administration.
Vous n’avez pas à enregistrer manuellement les scripts et les styles définis ici car ils 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 dans l’image ci-dessus, notre script index.js résidant dans le répertoire build a été régulièrement mis en file d’attente sans avoir à ajouter de code PHP.
Libellés de l’UI
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 réglages de vos blocs à 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",
"academy",
"superhero"
],Si vous saisissez maintenant « kinsta », « academy » ou « superhero » dans l’insertion rapide, l’éditeur vous proposera le bloc Kinsta Academy :
Localisation
Si vous vous demandez comment se fait la localisation des chaînes de caractères dans le fichier JSON, voici la réponse :
En JavaScript, vous pouvez utiliser la méthode
registerBlockTypeFromMetadatadu package@wordpress/blockspour enregistrer un type de bloc à l’aide des métadonnées chargées dans le fichier block.json. Toutes les propriétés localisées sont automatiquement enveloppées dans des appels de fonction_x(du paquet@wordpress/i18n) de la même manière que cela fonctionne en PHP avecregister_block_type_from_metadata. La seule exigence est de définir la propriététextdomaindans le fichier block.json.
Nous utilisons ici la fonction registerBlockType au lieu de registerBlockTypeFromMetadata, car cette dernière est obsolète depuis Gutenberg 10.7, mais le mécanisme est le même.
Utilisation des composants intégrés : Le composant RichText
Les éléments qui composent un bloc Gutenberg sont des composants React, et vous pouvez accéder à ces composants via la variable globale wp. Par exemple, essayez de saisir wp.editor dans la console de votre navigateur. Vous obtiendrez ainsi la liste complète des composants inclus dans le module wp.editor.
Faites défiler la liste et devinez à quoi servent les composants d’après leur nom.
De même, vous pouvez vérifier la liste des composants inclus dans le module wp.components :
Retournez maintenant au fichier edit.js et regardez de plus près le script :
import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';
export default function Edit() {
return (
<p { ...useBlockProps() }>
{ __(
'Kinsta Academy Block – hello from the editor!',
'ka-example-block'
) }
</p>
);
}Ce code génère un bloc statique avec un texte simple et non modifiable. Mais nous pouvons facilement changer les choses :
Pour rendre le texte modifiable, il faudra remplacer la balise <p> actuelle par un composant qui rend le contenu de la saisie 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 :
- Importer les composants nécessaire à partir d’un paquet WordPress
- Inclure les éléments correspondants dans votre code JSX
- Définir les attributs nécessaires dans le fichier block.json
- Définir les gestionnaires d’événements
- Enregistrer les données
Étape 1 : Importer les composants nécessaires à partir d’un paquet WordPress
Ouvrez maintenant le fichier edit.js et modifiez l’instruction import suivante :
import { useBlockProps } from '@wordpress/block-editor';…en :
import { useBlockProps, RichText } from '@wordpress/block-editor';De cette façon, vous importez la fonction useBlockProps et le composant RichText du paquet @wordpress/block-editor.
useBlockProps
Le crochet React useBlockProps marque l’élément d’habillage du bloc :
Lorsque vous utilisez la version 2 de l’API, vous devez utiliser le nouveau crochet
useBlockPropsdans la fonctioneditdu bloc pour marquer l’élément d’habillage du bloc. Le crochet insérera les attributs et les gestionnaires d’événements nécessaires pour activer le comportement du bloc. Tous les attributs que vous souhaitez transmettre à l’élément du bloc doivent passer paruseBlockPropset la valeur renvoyée doit être répartie sur l’élément.
Pour faire simple, les useBlockProps attribuent automatiquement des attributs et des classes à l’élément d’habillage (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 aux fonctionnalités et au style des blocs :
Comme nous l’expliquerons plus tard, vous pouvez également passer à useBlockProps un objet de propriétés pour personnaliser la sortie.
RichText
Le composant RichText fournit une entrée dont le contenu est modifiable, ce qui permet 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— nom de la balise de l’élément HTML modifiableonChange— fonction appelée lorsque le contenu de l’élément changeallowedFormats— tableau des formats autorisés. Par défaut, tous les formats sont autorisésvalue— chaîne HTML à rendre modifiableplaceholder— texte de remplacement à 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, comme le contenu riche, la couleur d’arrière-plan, les URL, etc.
Vous pouvez définir un nombre arbitraire attributes dans un objet attributs sous forme de 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 prop suivants :
"attributes": {
"content": {
"type": "string",
"source": "html",
"selector": "p"
}
},L’attribut de content permet de stocker le texte saisi par l’utilisateur dans le champ modifiable :
typeindique le type de données stockées par l’attribut. Le type est obligatoire, sauf si vous définissez une propriété de typeenum.sourcedéfinit comment la valeur de l’attribut est extraite du contenu de l’article. 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).selectorest 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. Donc, retournez au fichier edit.js et faites la modification suivante :
export default function Edit( { attributes, setAttributes } ) { ... }Étape 4 : Définir les gestionnaires d’événements
L’élément RichText possède un attribut onChange, qui fournit 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...' ) }
/>
);
}Enregistrez maintenant le fichier et retournez à votre tableau de bord WordPress, créez un nouvel article ou une nouvelle page et ajoutez votre bloc personnalisé :
Ajoutez du texte et passez à la vue Code. Voici à quoi devrait ressembler votre code :
<!-- wp:ka-example-block/ka-example-block -->
<p class="wp-block-ka-example-block-ka-example-block">Kinsta Academy Block – hello from the saved content!</p>
<!-- /wp:ka-example-block/ka-example-block -->Comme vous pouvez le voir, si vous passez à l’éditeur de code, le contenu de votre bloc a changé. 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 l’article est enregistré.
É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
RichTextdu paquetageblock-editor. - Passez plusieurs propriétés à la fonction de
savevia un argument objet (dans cet exemple, nous ne passons que lesattributsproperty). - 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 props sur Github.
Allons maintenant un peu plus loin. Dans la section suivante, vous apprendrez à ajouter des contrôles à la barre d’outils du bloc.
Ajout de contrôles à la barre d’outils du bloc
La barre d’outils du bloc contient un ensemble de contrôles permettant aux utilisateurs de manipuler des parties du contenu du bloc. Pour chaque contrôle de la barre d’outils, vous trouverez un composan :
Par exemple, vous pouvez ajouter un contrôle d’alignement du texte pour votre bloc. Il vous suffit d’importer deux composants du paquetage @wordpress/block-editor.
Nous allons suivre les mêmes étapes que dans l’exemple précédent :
- Importer les composants nécessaires à partir des paquets WordPress
- Inclure les éléments correspondants dans votre code JSX
- Définir les attributs nécessaires dans le fichier block.json
- Définir les gestionnaires d’événements
- Enregistrer les données
Étape 1 : Importer les composants BlockControls et AlignmentControl de @wordpress/block-editor
Pour ajouter un contrôle d’alignement à la barre d’outils du bloc, vous avez besoin de deux composants :
BlockControlsrend une barre d’outils dynamique de contrôles (non documenté).AlignmentControlrend 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 import comme indiqué ci-dessous :
import {
useBlockProps,
RichText,
AlignmentControl,
BlockControls
} from '@wordpress/block-editor';Étape 2 : Ajouter les éléments BlockControls et AlignmentControl
Allez dans la fonction Edit et insérez l’élément <BlockControls /> au même niveau que <RichText />. Ajoutez ensuite un <AlignmentControl /> à l’intérieur de <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 sont la façon dont nous retournons plusieurs éléments dans React.
Dans cet exemple, AlignmentControl possède deux attributs :
valuefournit la valeur actuelle de l’élémentonChangefournit un gestionnaire d’événement à 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
Maintenant, allez dans le fichier block.json et ajoutez l’attribut align :
"align": {
"type": "string",
"default": "none"
}Quand vous avez terminé, retournez à l’éditeur de bloc, actualisez la page et sélectionnez le bloc. Vous devriez voir un message d’erreur dans votre bloc.
La raison en est que nous n’avons pas encore défini notre 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 mettons newAlign à 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 retourner dans l’éditeur et aligner le contenu du bloc. Votre bloc devrait maintenant afficher fièrement une barre d’outils d’alignement.
Mais si vous enregistrez l’article, vous verrez que le contenu de votre bloc n’est pas aligné sur l’interface publique comme il l’est dans l’éditeur de bloc. C’est parce que nous devons modifier la fonction save afin de boutique le contenu et les attributs du bloc dans la base de données.
Étape 5 : Sauvegarder les données
Ouvrez save.js et modifiez la fonction 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 en utilisant la syntaxe d’affectation de la déstructuration :
export default function save( { attributes } ) {
const blockProps = useBlockProps.save();
const { content, align } = attributes;
return (
<RichText.Content
{ ...blockProps }
tagName="p"
value={ content }
style={ { textAlign: align } }
/>
);
}Vous pouvez faire de même dans le fichier edit.js.
Enregistrez maintenant le fichier et passez à l’éditeur de code. Le code du bloc devrait ressembler à quelque chose comme ceci :
<!-- wp:ka-example-block/ka-example-block {"align":"right"} -->
<p class="wp-block-ka-example-block-ka-example-block" style="text-align:right">This is my first editable <strong>Gutenberg</strong> <em>block</em> 😎</p>
<!-- /wp:ka-example-block/ka-example-block -->
Voilà, c’est fait ! 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 du bloc dans le manuel de l’éditeur de bloc.
Personnalisation de la colonne latérale des réglages du bloc
Vous pouvez également ajouter des contrôles à la colonne latérale des réglages du bloc (ou même créer une nouvelle colonne latérale pour votre application).
L’API fournit un composant InspectorControls pour cela.
Le manuel de l’éditeur de blocs explique comment utiliser la colonne latérale des réglages :
La colonne latérale des réglages est utilisée pour afficher les réglages moins souvent utilisés ou ceux qui nécessitent plus d’espace à l’écran. La colonne latérale des réglages ne doit être utilisée que pour les réglages au niveau du bloc.
Si vous disposez de réglages qui n’affectent que le contenu sélectionné à l’intérieur d’un bloc (par exemple, le réglage « gras » pour le texte sélectionné dans un paragraphe), ne les placez pas dans la colonne latérale des réglages. La colonne latérale des réglages s’affiche même lors de l’édition d’un bloc en mode HTML. Elle ne doit donc contenir que les réglages relatifs aux blocs.
Encore une fois :
- Importer les composants nécessaires à partir des paquets WordPress
- Inclure les éléments correspondants dans votre code JSX
- Définir les attributs nécessaires dans le fichier block.json
- Définir les gestionnaires d’événements
- Enregistrer les données
Étape 1. Importation des 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 devez importer les composants InspectorControls et PanelColorSettings du 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 { content, align, backgroundColor, textColor } = attributes;
const onChangeContent = ( newContent ) => {
setAttributes( { content: newContent } )
}
const onChangeAlign = ( newAlign ) => {
setAttributes( {
align: newAlign === undefined ? 'none' : newAlign,
} )
}
return (
<>
<InspectorControls>
<PanelColorSettings
title={ __( 'Color settings', 'ka-example-block' ) }
initialOpen={ false }
colorSettings={ [
{
value: textColor,
onChange: onChangeTextColor,
label: __( 'Text color', 'ka-example-block' )
},
{
value: backgroundColor,
onChange: onChangeBackgroundColor,
label: __( 'Background color', 'ka-example-block' )
}
] }
/>
</InspectorControls>
<BlockControls>
<AlignmentControl
value={ align }
onChange={ onChangeAlign }
/>
</BlockControls>
<RichText
{ ...blockProps }
tagName="p"
onChange={ onChangeContent }
allowedFormats={ [ 'core/bold', 'core/italic' ] }
value={ content }
placeholder={ __( 'Write your text...' ) }
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...' ) }
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 en fonction des entrées 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 } }
/>
);
}Enregistrez le fichier et vérifiez le bloc dans l’éditeur. Vous trouverez peut-être une mauvaise surprise : un message d’erreur vous informant que le bloc contient un contenu inattendu ou non valide.
Cela se produit parce que le fichier save.js est modifié et que le code enregistré dans la base de données ne correspond pas au code utilisé dans l’éditeur.
Pour résoudre ce problème, actualisez la page, supprimez toute instance de votre bloc et ajoutez-le à nouveau à votre publication :
Apportez vos modifications, enregistrez l’article et affichez-le dans le site principal. Les modifications que vous avez apportées dans l’éditeur de blocs doivent être reflétées sur le site principal.
Ajout et personnalisation d’un lien externe
Dans cette section, vous allez ajouter de nouveaux composants à votre type de bloc :
- Un composant
ExternalLinkpermettant aux utilisateurs d’ajouter un lien personnalisable à votre bloc personnalisé - Plusieurs contrôles de la colonne latérale permettant aux utilisateurs de personnaliser les réglages des liens.
Étape 1. Importez les composants depuis @wordpress/components
Maintenant, vous devez 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';PanelBodyajoute un conteneur pliable à la colonne latérale des réglages.PaneRowproduit un conteneur générique pour les contrôles de la colonne latérale.TextControlfournit un contrôle de saisie de texte.ToggleControlfournit une bascule permettant aux utilisateurs d’activer/désactiver une option spécifique.ExternalLinkest un composant simple pour ajouter un lien externe.
Étape 2. Inclure les éléments correspondants dans votre code JSX
Vous allez d’abord ajouter l’élément ExternalLink au même niveau que RichText dans un conteneur div :
<div { ...blockProps }>
<RichText
...
/>
<ExternalLink
href={ kaLink }
className="ka-button"
rel={ hasLinkNofollow ? "nofollow" : "" }
>
{ linkLabel }
</ExternalLink>
</div>Le composant ExternalLink n’est pas documenté, nous nous sommes donc référés au composant lui-même pour obtenir la liste des attributs disponibles. Ici, nous utilisons les attributs href, className et rel.
Par défaut, la valeur de l’attribut rel est définie sur noopener noreferrer. Notre code ajoutera le nofollow mot clé à l’attribut rel de la balise a résultante lorsque la commande de basculement sera activée.
Vous pouvez maintenant ajouter des réglages de liens dans la colonne 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' )}
initialOpen={true}
>
...
</PanelBody>
</InspectorControls>Voici ce que nous faisons avec ça :
- L’attribut
titlefournit le titre du panneau. initialOpendéfinit si le panneau est initialement ouvert ou non.
Ensuite, nous allons ajouter deux éléments PanelRow à l’intérieur de PanelBody, et un élément TextControl à l’intérieur de chaque PanelRow :
<PanelBody
title={ __( 'Link Settings', 'ka-example-block' )}
initialOpen={true}
>
<PanelRow>
<fieldset>
<TextControl
label={__( 'KA link', 'ka-example-block' )}
value={ kaLink }
onChange={ onChangeKaLink }
help={ __( 'Add your Academy link', 'ka-example-block' )}
/>
</fieldset>
</PanelRow>
<PanelRow>
<fieldset>
<TextControl
label={__( 'Link label', 'ka-example-block' )}
value={ linkLabel }
onChange={ onChangeLinkLabel }
help={ __( 'Add link label', 'ka-example-block' )}
/>
</fieldset>
</PanelRow>
</PanelBody>Le code ci-dessus devrait maintenant avoir l’air 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, comme 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 attributs kaLink, linkLabel et hasLinkNofollow dans le fichier block.json :
"kaLink": {
"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, ajoutez les nouveaux attributs à l’objet attributes, et ajoutez les fonctions suivantes :
const { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;
const onChangeKaLink = ( newKaLink ) => {
setAttributes( { kaLink: newKaLink === undefined ? '' : newKaLink } )
}
const onChangeLinkLabel = ( newLinkLabel ) => {
setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } )
}
const toggleNofollow = () => {
setAttributes( { hasLinkNofollow: ! hasLinkNofollow } )
}Ces fonctions mettent à jour les valeurs des attributs correspondants lors de la saisie par 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 { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;
const blockProps = useBlockProps.save( {
className: `has-text-align-${ align }`
} );
return (
<div
{ ...blockProps }
style={ { backgroundColor: backgroundColor } }
>
<RichText.Content
tagName="p"
value={ content }
style={ { color: textColor } }
/>
<p>
<a
href={ kaLink }
className="ka-button"
rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" }
>
{ linkLabel }
</a>
</p>
</div>
);
}Notez qu’ici nous avons utilisé un élément a normal au lieu de ExternalLink .
Vous pouvez voir le résultat dans l’image ci-dessous.
Ajout de styles de blocs multiples
Dans une section précédente, vous avez appris à ajouter un contrôle de barre d’outils de bloc permettant aux utilisateurs d’aligner la saisie de l’utilisateur. Nous pouvons ajouter d’autres 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 d’un simple clic.
À cette fin, nous allons utiliser une fonctionnalité utile de l’API de bloc : les styles de bloc.
Il vous suffit de définir la propriété styles du fichier block.json 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"
}
],Ainsi, 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 de styles dans la colonne latérale des réglages du bloc.
Sélectionnez un style et vérifiez les classes appliquées à l’élément p. Cliquez avec le bouton droit de la souris sur le bloc et inspectez. Une nouvelle classe a été ajoutée avec un nom structuré comme suit :
is-style-{style-name}Si vous avez coché le style « Border », 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-ka-example-block-ka-example-block {
padding: 4px;
}Vous pouvez maintenant faire de même avec style.scss. Comme nous l’avons mentionné plus haut, les styles définis dans style.scss sont appliqués à la fois sur l’interface publique et dans l’éditeur :
.wp-block-ka-example-block-ka-example-block {
&.is-style-default{
border: 0;
background-color: #FFE2C7;
}
&.is-style-border{
border: 2px solid #000;
border-radius: 16px;
background-color: #F6F6F6;
}
}Et c’est tout ! Rafraîchissez la page et amusez-vous avec vos nouveaux styles de blocs :
Emboîter les blocs Gutenberg avec le composant InnerBlocks
Bien que pleinement fonctionnel, notre bloc personnalisé 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 :
InnerBlocksexporte une paire de composants qui peuvent être utilisés dans les implémentations de blocs pour activer le contenu des blocs imbriqués.
Tout d’abord, vous devez 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';Retournez dans le fichier 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 dans laquelle les blocs seront placés. Dans l’exemple suivant, nous définissons un modèle composé de deux colonnes contenant un bloc Image de base et notre bloc personnalisé :
const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [
[ 'core/column', { templateLock: 'all' }, [
[ 'core/image' ],
] ],
[ 'core/column', { templateLock: 'all' }, [
[ 'ka-example-block/ka-example-block', { placeholder: 'Enter side content...' } ],
] ],
] ] ];Le modèle est structuré comme un tableau de blockTypes (nom du 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 Columns afin que l’utilisateur ne puisse pas ajouter, réorganiser ou supprimer des blocs existants. templateLock peut prendre l’une des valeurs suivantes :
all—InnerBlocksest 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 également le problème #17262 et la commande #26128).
Voici notre fichier final container.js :
registerBlockType('ka-example-block/ka-example-container-block', {
title: __( 'KA Container block', 'ka-example-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 pouvons préférer attribuer la couleur d’arrière-plan à la div du conteneur :
Donc, modifiez le fichier edit.js et div save.js comme suit :
<div
{ ...blockProps }
style={ { backgroundColor: backgroundColor } }
>
...
</div>Cela permettra à l’utilisateur de modifier l’arrière-plan de l’ensemble du bloc.
En revanche, un changement plus pertinent concerne la méthode useBlockProps. Dans le code original, nous définissions la constante blockProps comme suit :
const blockProps = useBlockProps();Mais nous pouvons utiliser useBlockProps de manière plus efficace en passant un ensemble de propriétés. Par exemple, nous pouvons importer classnames depuis le module classnames et définir le nom de la classe d’enveloppe en conséquence.
Dans l’exemple suivant, nous attribuons un nom de classe en fonction de la valeur de l’attribut align (edit.js) :
import classnames from 'classnames';
...
export default function Edit( { attributes, setAttributes } ) {
...
const onChangeAlign = ( newAlign ) => {
setAttributes( {
align: newAlign === undefined ? 'none' : newAlign,
} )
}
const blockProps = useBlockProps( {
className: `has-text-align-${ align }`
} );
...
}Nous ferons le même changement dans le fichier save.js :
import classnames from 'classnames';
...
export default function save( { attributes } ) {
...
const { content, align, backgroundColor, textColor, kaLink, linkLabel, hasLinkNofollow } = attributes;
const blockProps = useBlockProps.save( {
className: `has-text-align-${ align }`
} );
...
}Et c’est fini ! Vous pouvez maintenant exécuter le build pour la production :
npm run buildRésumé
Et nous voici 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 établie de React pour commencer à vous amuser avec le développement de blocs, cependant. Le développement de blocs pourrait vous donner une motivation et des 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 vous recommandons les suivantes :
- Tutoriel officiel de création d’un bloc pour les débutants
- Tutoriel officiel sur les blocs pour les développeurs intermédiaires
- Blocs dynamiques
- Comment créer des blocs dynamiques pour Gutenberg
- Boîtes méta
- Création d’une colonne latérale pour votre extension
Si vous débutez dans le développement de WordPress, vous voudrez peut-être comprendre les concepts de base du développement frontend. Voici une liste rapide de ressources qui peuvent vous aider à démarrer :
- Comment installer WordPress en local (e-book gratuit)
- La valeur réelle de l’hébergement WordPress infogéré (e-book gratuit)
- Qu’est-ce que JavaScript ?
- HTML et HTML5
- Comment modifier le CSS dans WordPress
- Qu’est-ce que le PHP ?
- Le Bootcamp WordPress Hooks : Comment utiliser les actions, les filtres et les crochets personnalisés
Et n’oubliez pas que le code complet des exemples de ce guide est disponible sur Gist.
Maintenant c’est votre tour : 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 !
Carlo est un passionné de webdesign et de développement frontend. Il joue avec WordPress depuis plus de 10 ans, notamment en collaboration avec des universités et des établissements d'enseignement italiens et européens. Il a écrit des dizaines d'articles et de guides sur WordPress, publiés à la fois sur des sites web italiens et internationaux, ainsi que dans des magazines imprimés. Vous pouvez trouver Carlo sur X et LinkedIn.
Laisser un commentaire