Depuis sa version 5.0, WordPress intègre son propre builder (constructeur de page), nommé Gutenberg dans le but que le commun des mortel puisse créer et intégrer ses composants (blocks) via, par exemple, le Drag & Drop et construire des pages rapidement et simplement, sans extensions tierces du même type. Aujourd’hui, je m’attarde sur les blocks Gutenberg.
Je vous avais promis ici que je m’écartais de WordPress pour parler de React sur ce blog. C’est ici une bonne transition : je lie les deux 🙂
Un départ mitigé
L’outil en question n’avait pas fait beaucoup d’émules à son arrivée, et la communauté WordPress avait fort critiqué l’avènement de cette nouvelle façon d’écrire les articles et le contenu des pages, imposé alors à l’installation du CMS. C’est pourquoi l’extension « disabled Gutenberg » était née et avait eu quant à elle pas mal de succès ! Je faisais également partie de ces utilisateurs / modérateurs WordPress qui ne l’avaient pas apprécié dès le départ, en installant quant à moi le plugin « Classic Editor » par respect pour tous les contributeurs de WordPress.. Soit, ce fut un départ mitigé pour moi aussi.
Mais avec le temps et de bonnes mises à jour, le builder intégré s’imposait à tous et je me suis alors interrogé sur les moyens de manipuler les blocks / composants de la plateforme afin de proposer à mes clients d’ajouter / éditer des sections personnalisées sur leurs pages, tout en respectant le design validé en amont, et que je ne permettais pas alors de modifier. C’est l’objectif de cet article, vous montrer ma façon de travailler avec les blocks Gutenberg et comment les manipuler au niveau de code backend.
2 façons d’intégrer vos Blocks Gutenberg
Je séparerai en deux les manières de travailler les blocks WordPress.
Tout simplement parce que l’évolution de WordPress suit la tendance actuelle ; le Javascript.
Je prends donc comme angle de vue, deux langages, le langage natif de WordPress, surtout basé sur PHP, et puis l’autre manière de créer des blocks avec le JS/Javascript.
Avec PHP
Vous pouvez le faire avec PHP uniquement si vous le souhaitez. Cette méthode est un peu lourde et utilise la fonction native du CMS, nommée « register_block_type« . En paramètres, vous donnez le slug du thème suivi du slug de votre composant (soit un namespace) (obligatoire), éventuellement le nom de l’icône à afficher dans le Dashboard, une description, une catégorie et puis surtout un render.
Ce dernier affiche les données dynamiques via un tableau (array) « $attributes » que vous définissez également dans la fonction susmentionnée. Pour la clé « attributes« , vous définissez le type de valeur (String, booleen, enum, integer…) et le contenu par défaut.
Vous pouvez aussi, dans cette fonction, ajouter la clé « supports » qui vous permet d’ajouter dans l’éditeur, les alignements, les couleurs ou les espaces par exemple. Voilà à quoi ressemblerait un block dans une fonction PHP :
register_block_type(
'montheme-child/blog',
[
'title' => 'Blog',
'icon' => 'post',
'render_callback' => function ($attributes) {
return sprintf(
'<section id="blog" class="collections">
<div class="section-header">
<h2 class="section-title">%s</h2>
<p class="section-subtitle">%s</p>
</div>
<div class="grid" id="collectionsGrid">
'. runPosts() .'
</div>
</section>',
esc_html($attributes['title']),
esc_html($attributes['subtitle']),
);
},
'style_handles' => array( 'namespace_du_style' ),
'supports' => [
'autoRegister' => true,
],
'attributes' => [
'title' => [
'type' => 'string',
'default' => 'Latest articles',
],
'subtitle' => [
'type' => 'string',
'default' => 'Discover our curated news',
],
],
]
);
Vous l’aurez compris, plus vous avez du contenu dynamique, plus le code sera long (et lourd). Dans cet exemple, la fonction « runPosts() » pourrait appeler une fonction qui affiche les derniers articles par exemple. Mais je l’ai séparée pour ne pas se perdre dans le code ainsi produit, et vous verrez également que les string dynamique (%s) ne sont pas très visibles, cela manque de clarté et ce n’est pas très pratique. Autrement dit, ce n’est pas la méthode que je préconise, mais je voulais vous montrer que c’était toujours possible d’ajouter un block custom via un seul fichier (.php), qui renfermerait la dynamique du block Gutenberg (excepté le style).
Un autre désavantage, est que vous ne verrez pas le style du composant dans le dashboard si vous n’importez pas le style comme dans l’exemple ci-dessus, avec la clé « style_handles« . Et lors de l’édition de votre contenu, vous n’aurez pas accès aux médias, à l’imbrication d’autres composants ou encore au texte enrichi (et bien d’autres fonctionnalités). Ici, et c’est dans cette optique que vous devriez travailler avec cette méthode, vous restez en back, l’utilisateur ne fait que modifier son block via les entrées (limitées) et prévues à cet effet.
Pour le style, vous pouvez l’importer via votre thème par exemple ou via la clé valeur suivante : ‘style_handles’ => array( ‘namespace_du_style’ ) pour en voir tout de suite les aspects). J’aurais pu également séparer la fonction render ailleurs dans le code (‘render_callback’ => function ($attributes) {…} => ‘render_callback’ => ‘ma_fonction_de_rendu’) pour alléger le code, mais globalement, tout ce joue depuis la fonction native que je viens de vous décrire.
Je vous donne un exemple de thème et deux sections qui utilise cette méthode :
https://github.com/ProjetsMerlin/Walhain
Avec Javascript et React
C’est sans doute ce qui est recommandé par les instances officielles de WordPress aujourd’hui. Ici, on change complètement de philosophie, et on code en Javascript. On utilisera PHP uniquement pour inclure le block dans votre thème, avec la fonction précitée, mais avec un seul paramètre ; contenant le chemin du dossier du composant et son namespace. Exemple :
register_block_type(get_theme_file_path('blocks/blog'));Il faut ensuite créer un dossier (ici « blog dans « blocks ») et y inclure une série de fichiers pour ajouter le composant à votre thème.
Voici les fichiers et ce qu’ils font :
block.json | La carte d’identité : nom, titre, attributs, fichiers à charger |
edit.js | Le composant React affiché dans l’éditeur |
save.js | Le HTML enregistré en base et servi aux visiteurs |
index.js | Le point d’entrée qui relie tout avec registerBlockType() |
En gros, c’est le fichier block.json à la racine de votre block qui va tout relier et tout gérer. On y retrouve un peu toutes les caractéristiques présentées dans la fonction register_block_type() précédemment, surtout les attributs que vous devez renseigner pour que votre client puisse implémenter sont contenu. Ici, la structure vous présente les fichiers construits, il faudra en effet compiler vos fichiers pour que tout fonctionne et si vous voulez comme moi, travailler avec REACT. Voilà un exemple de ce fichier json :
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "monsite/callout",
"title": "Encadré",
"category": "text",
"icon": "info-outline",
"description": "Encadré d'info pour mettre en avant une astuce ou un avertissement.",
"textdomain": "monsite",
"attributes": {
"type": {
"type": "string",
"default": "info"
},
"content": {
"type": "string",
"source": "html",
"selector": ".callout__content"
}
},
"supports": {
"html": false,
"align": ["wide", "full"]
},
"editorScript": "file:./index.js",
"editorStyle": "file:./index.css",
"style": "file:./style-index.css"
}Il existe un module Node pour travailler et compiler ces fichiers proprement, voilà la ligne de commande pour l’installer :
npm install --save-dev @wordpress/scriptsEt voilà un exemple du fichier index.js, qui est le point d’entrée de votre nouveau composant :
import { registerBlockType } from '@wordpress/blocks';
import './style.css';
import './editor.css';
import Edit from './edit';
import save from './save';
import metadata from './block.json';
registerBlockType(metadata.name, {
edit: Edit,
save,
});Comme vous pouvez le voir, on y lie les deux autres fichiers, mais aussi le style côté frontend & backend que vous verrez au final en ligne et dans l’édition de votre contenu.
Et la suite ?
À partir de là, vous créez vos composants.
Mais avec cette méthode, vous allez pouvoir visuellement déplacer en Drag & Drop, vos composants depuis le Dashboard.
Et ça, en plus d’être gratifiant, ergonomique, vous mettez en place pour vous ou votre prestataire un outil fait sur mesure qu’il peut lui-même adapter avec WordPress. Que demander de plus ?
