Créer une librairie de blocs customisés Gutenberg

Des blocs customisés ?

Il arrive parfois que certaines personnes rencontrent des difficultés à rédiger leurs contenus comme elles l’entendent sur Gutenberg.
Cela pour de multiples raisons : un manque de connaissance de l’éditeur, une ergonomie trop peu accessible, ou tout simplement, l’absence totale de fonctionnalités pouvant permettre à l’utilisateur de disposer de sa page comme il l’entend ! Nous allons découvrir comment résoudre ce problème en créant une extension WordPress contenant une librairie de blocs customisés.

Prérequis

Pour créer notre extension contenant notre librairie de blocs customisés, nous allons avoir besoin de différents éléments :

  • Un ordinateur avec un gestionnaire de commande.
  • Un environnement WordPress (sur lequel nous allons installer notre extension)
  • L’environnement d’exécution NodeJs

Création de l’extension

Dans un premier temps, il est nécessaire de créer une extension pour accueillir notre bibliothèque de blocs customisés.
Pour cela, nous allons nous rendre dans le répertoire WordPress, dans le dossier « wp-content » puis dans le dossier « plugins » (c’est le dossier où se trouvent toutes les extensions de notre site internet.). Nous allons créer un dossier qui aura pour identifiant, le nom que vous souhaitez donner à votre extension. Pour cet exemple, je vais appeler mon extension « bloc-customises » mais vous n’êtes pas obligés de faire pareil. Ajouter dans ce dossier un fichier du même nom que le dossier que nous venons de créer et donnez-lui l’extension « .php ». Cela donne dans notre exemple « bloc-customises.php ».

Le schéma ci-dessous résume l’architecture à suivre.

Image de l'arborescence d'une extension WordPress

Nous allons ouvrir le fichier « .php » que nous venons fraîchement de créer et inscrire les lignes suivantes :

PHP/bloc-customises.php
<?php
/**
 * Plugin Name: Librairie de blocs customisés WordPress (Correspond au titre de votre extension)
 * Description: Cette extension propose à ses utilisateurs de nouveaux blocs pour l'éditeur Gutenberg ! (Correspond à la description de votre extension)
 * Author: Pierre Lejeune (Correspond à votre nom de créateur)
 * Author URI: https://pierrelejeune.fr (Correspond à une url à laquelle vous retrouvez, ce n'est pas obligatoire)
 * Version: 0.1 (Correspond à la version de votre extension)
 */

if( !defined( 'WPINC' ) ) { die; } // On vérifie que notre extension se trouve bien dans un répertoire WordPress

/**
 *  On renseigne les dépendances de notre extension. Elles seront créées plus tard.
 * */
function load_bloccustomises_gutenberg_dependencies() {
    $dir = plugin_dir_url(__FILE__) . 'build';
    wp_enqueue_script( "bloccustomises-plugin", "$dir/index.js", [ 'wp-blocks', 'wp-dom' ] , false, true );
}
//add_action( 'enqueue_block_editor_assets', 'load_bloccustomises_gutenberg_dependencies', 100 ); //Certains éléments ne sont pas encore créer, nous décommenterons cette ligne plus tard.

Nous devrions être en mesure de voir votre extension s’afficher sur notre interface d’administration WordPress (sur la page « extensions »). Nous pouvons l’activer.

Installation des dépendances et création de l’architecture de fichier

Notre extension WordPress est fonctionnelle. Il nous faut désormais installer les dépendances nous permettant de développer des blocs customisés facilement.

Installer nos dépendances avec le gestionnaire de modules

Nous allons désormais créer à la racine de notre extension un fichier « package.json ». C’est le fichier faisant office de gestionnaire de module, il définit et gère nos modules nodeJs dont nous avons parlé dans les prérequis.

Nous allons renseigner les informations suivantes dans notre fichier « package.json » :

Javascript/package.json
{
    "name": "bloc-customises",
    "private": true,
    "author": "Pierre Lejeune (pierrelejeune.fr)",
    "devDependencies": {
        "@wordpress/components": "^19.2.0",
        "@wordpress/scripts": "^19.2.3"
    },
    "scripts": {
        "start": "wp-scripts start src/index.js --output-path=build",
        "build": "wp-scripts build src/index.js --output-path=build"
    }
}

Nous pouvons enregistrer notre fichier et ouvrir notre gestionnaire de commande ( « cmd » sur window ou « terminal » sur Mac ).

Avec la commande « cd », nous allons nous placer dans le répertoire de notre extension. Si vous n’avez jamais utilisé cette commande, voici ce à quoi elle devrait ressembler :

Et nous allons installer nos modules avec la commande suivante :

Des lignes vont défiler, c’est normal. Notre gestionnaire télécharge toutes les dépendances nécessaires à la création de blocs. Une fois que les lignes s’arrêtent, si tout est vert, c’est que nous avons réussi et que nous pouvons passer à l’étape suivante ! Dans le cas contraire, il faut se référer aux aides associées aux erreurs inscrites dans la console.

Notre gestionnaire de blocs

Nous allons maintenant créer notre arborescence de fichier nous permettant d’accueillir nos différents blocs. Je vous invite pour cela à créer un dossier « src » à la racine de notre extension et de créer à l’intérieur, un répertoire « blocs », ainsi qu’un fichier « index.js ». Nous utiliserons le dossier « blocs » pour stocker nos blocs et le fichier « index.js » pour les instancier.

Le schéma ci-dessous résume l’architecture à suivre :

Architecture extension pour créer des blocs customisés wordpress

Dans le fichier « index.js » nous allons pouvoir inscrire les lignes suivantes :

Javascript/src/index.js
import { registerBlockType } from '@wordpress/blocks'; //On importe la librairie WordPress qui permet d'instancier de nouveau bloc

//import * as MonPremierBloc from './MonPremierBloc/MonPremierBloc'; //Il faudra décommenter cette ligne plus tard

export const listeDeBlocsCustomises= () => [ //On créer une liste de bloc
    //MonPremierBloc, //Il faudra décommenter cette ligne plus tard
]

/**
* La fonction suivante nous permet d'instancier un bloc
*/
function registerBlock ( block ){
    if ( ! block ) {
        return; //Si le bloc transmit en paramètre de fonction n'existe pas, je retourne une variable nulle
    } 
    const { name, settings } = block; //Je récupère le nom et les paramètres de mon bloc
    registerBlockType( `bloccustomises/${name}`, settings ); //J'instancie mon bloc
};

const registerPierrelejeuneBlocks = (blocks = listeDeBlocsCustomises()) => {
    blocks.forEach( registerBlock ); //Je parcours la liste de mes blocs pour les instancier en utilisant la fonction "registerBlock"
};
registerPierrelejeuneBlocks();

Créer son premier bloc

Nous avons défini notre architecture, renseignés nos dépendances… Il ne nous reste plus qu’à créer notre bloc !

Nous allons créer un répertoire « MonPremierBloc » dans notre fichier « blocs » et créer à l’intérieur les fichiers suivants :

  • MonPremierBloc.js
  • MonPremierBlocSave.js
  • MonPremierBlocEdit.js

Le fichier « MonPremierBloc.js » va nous permettre de définir le nom et les paramètres globaux de notre bloc (le titre, la description, l’icône, …). Ce fichier ne génère rien de concret, il nous permet simplement de définir la structure de notre bloc.
« MonPremierBlocEdit.js » quant à lui va générer le contenu visible sur notre interface d’administration, sur Gutenberg exactement.
« MonPremierBlocSave.js », vous l’aurez peut-être compris, génère le contenu visible sur la partie publique de notre site internet.

Nous pourrions utiliser qu’un seul fichier pour créer notre bloc, mais utiliser cette architecture apporte plus de lisibilité et d’aisance de navigation dans notre code, si votre bloc ne fonctionne pas correctement sur l’interface d’administration ou sur la partie publique, vous savez dans quel fichier vous rendre tout de suite.

Ouvrons notre fichier « MonPremierBloc.js » pour définir nos paramètres globaux. Il faut utiliser le code suivant :

Javascript/src/MonPremierBloc/MonPremierBloc.js
import MonPremierBlocEdit from './MonPremierBlocEdit'; //Notre bloc sur l'interface d'administration
import MonPremierBlocSave from './MonPremierBlocSave'; //Notre bloc sur l'interface public
export const name = "mon-premier-bloc"; //Le nom de notre bloc
export const settings = { // Les paramètres de notre bloc
    title: "Mon Premier Bloc",  //Le titre de notre bloc
    description: "Ceci est mon premier bloc !", // La description de notre bloc
    category: "text", //La category de notre bloc
    icon:"smiley", //L'icone de notre bloc
    edit:MonPremierBlocEdit, // La fonction à appeler pour afficher notre bloc sur l'interface d'administration
    save:MonPremierBlocSave // La fonction à appeler pour afficher notre bloc sur l'interface public
}

Adaptez évidemment les attributs définis en fonction de vos besoins.

Comme nous pouvons le lire, nous faisons appel à notre fichier « MonPremierBlocEdit » pour l’attribut « edit » et « MonPremierBlocSave » pour l’attribut « save ».

Ouvrons désormais notre fichier « MonPremierBlocEdit.js » et saisissons les lignes suivantes :

Javascript/src/MonPremierBloc/MonPremierBlocEdit.js
import { useBlockProps} from '@wordpress/block-editor'; // Récupération de la méthode permettant à WordPress de nous transmettre les attributs propres à notre bloc

const MonPremierBlocEdit = () => { //La fonction affichant notre premier bloc sur l'interface d'administration
    const blockProps = useBlockProps() // Récupération des attributs propres à notre bloc
    return (
        <div {...blockProps}>
            <p>Mon premier Bloc</p>
        </div>
    ); //Affichage de notre bloc
}
export default MonPremierBlocEdit;

Pour terminer, nous allons compléter notre fichier « MonPremierBlocSave.js » avec le code suivant :

Javascript/src/MonPremierBloc/MonPremierBlocSave.js
import { useBlockProps } from '@wordpress/block-editor';// Récupération de la méthode permettant à WordPress de nous transmettre les attributs propres à notre bloc

const MonPremierBlocSave = () => {//La fonction affichant notre premier bloc sur l'interface public
    const blockProps = useBlockProps.save();// Récupération des attributs propres à notre bloc
    return (
        <div {...blockProps}>
            <p>Mon premier bloc</p>
        </div>
    );//Affichage de notre bloc
}

export default MonPremierBlocSave;

Vous pouvez faire un rendu différent entre la version affichée sur l’interface d’administration (Gutenberg) et la version affichée sur votre interface publique en modifier les fichiers « MonPremierBlocEdit.js » et « MonPremierBlocSave.js ».

Compiler l’extension

Nous avons terminé d’établir notre architecture et nos dépendances. Il ne nous reste plus qu’à compiler notre travail qui sera chargé par WordPress.

Pour cela, nous allons dans un premier temps décommenter nos trois lignes (Les deux lignes de notre fichier « index.js » et la ligne de notre fichier « .php » à la racine de notre extension.). Ensuite, nous allons ouvrir de nouveau notre terminal et nous rendre à la racine de notre extension ou nous avons tapé notre commande npm install plus tôt.

Si vous le voulez bien, nous allons taper la commande suivante :

Cette commande va compiler notre extension et créer notre librairie de blocs.

Une fois que notre console nous aura annoncé que notre projet à bien été compilé, nous pouvons retourner sur notre projet Worpdress, vérifier que notre extension est bel et bien installée et ouvrir une page ou un article (afin d’accéder à l’éditeur Gutenberg).
Et si tout s’est bien passé, nous devrions être en mesure de voir notre bloc ! Voyez plutôt :

Image animée de mon premier bloc

Félicitations ! Vous avez réussi.

Vous pouvez désormais créer autant de blocs que vous le souhaitez. Ajoutez autant de fois que nécessaire des blocs à votre dossier « blocs » et importez-les dans votre fichier « index.js ».

Nous verrons dans le prochain article comment personnaliser l’icône de notre bloc et lui définir un comportement visuel (avec du style/SASS).

Télécharger le projet

Vous pouvez télécharger le projet sur mon GitHub en cliquant ici.