Formation « Créer des blocs avec Gutenberg »

Create-block : une librairie pour démarrer rapidement ses projets Gutenberg

Lecture : 7 minutes • 15

Webpack, afin de compiler ses fichiers. Et ça peut vite devenir un casse-tête ! Heureusement, tout va être extrêmement simple avec la librairie officielle de WordPress : create-block.

Qu’est-ce que create-block ?

Aujourd’hui, pour faire du javascript moderne, on a besoin d’outils en tous genres pour vérifier et compiler le code, le rendre compatible avec les navigateurs…

Et tout cela nécessite généralement pas mal d’outils et beaucoup de configuration via Webpack et NPM.

On utilise notamment :

  • Webpack : qui va permettre de surveiller notre dossier et lancer les opérations nécessaires lors d’un changement de fichier
  • Babel : qui compile le javascript moderne et en crée une version rétrocompatible
  • React : la librairie JS de facebook utilisée par Gutenberg pour gérer l’éditeur visuel
  • JSLint : qui permet de vérifier que notre code ne contient pas d’erreurs

Même les habitués de Webpack et du développement en JS passent du temps pour faire de telles configurations.

Create-block est un set d’outils (un toolkit en anglais) qui ne nécessite aucune configuration préalable et qui va mettre en place toute la structure nécessaire au développement de blocs Gutenberg avec React.

En d’autre termes, on installe le projet, on commence à coder, et on oublie les soucis. Et ça, ça me plait !

Je dois avouer que j’ai été conquis par ce projet. Comme je le dis tout le temps je ne suis pas un grand fan de la ligne de commande. Mais pour le coup je dois avouer que tout fonctionne à merveille du premier coup !

Allez maintenant si vous le voulez bien, lançons-nous dans l’installation de create-block :

Prérequis

Comme on l’a vu dans les cours précédents, nous allons avoir préalablement besoin d’installer NodeJS, (version 8 au minimum), le serveur Javascript qui nous permettra de lancer des commandes NPM.

Il nous faut aussi un outil de ligne de commande comme Powershell sur Windows et le terminal sur Mac. Les deux sont déjà installés avec le système.

Une fois que l’on à ça, il suffit de nous rendre sur la page du projet create-block sur la documentation WordPress pour voir un peu de quoi il en retourne.

Documentation de create-block

Mise en place de create-block

D’après la documentation, nous n’avons rien besoin de télécharger. Il faudra simplement taper quelques lignes de commandes pour initialiser un nouveau plugin avec toute la configuration nécessaire à Gutenberg.

Avant toute chose, si ce n’est pas déjà fait, on va installer une instance de WordPress en local. Pour cela vous pouvez utiliser l’excellent Local WP, dont un cours est dédié dans la formation développer un thème sur mesure.

Installer un site en local
Préparer un nouveau site avec Local

Ok ! De là retenez-bien le chemin de votre site, le Site Path sur Local, car on va devoir y aller en ligne de commande.

1. Installer create-block

On va ouvrir notre terminal et se déplacer dans notre projet grâce à la commande cd (pour change directory).

On va devoir se rendre directement dans le dossier des extensions de notre site fraichement installé:

cd /Sites/gutenberg/app/public/wp-content/plugins

Adaptez cette ligne en fonction d’où est installé votre site. Si vous n’utilisez pas Local alors vous n’aurez pas besoin de la partie /app/public/.

Conseil

Dans le cas où un dossier contient des espaces, comme Local Sites, pensez à les échapper avec un backslash \ (Alt + Maj + / sur Mac).

L’autre solution serai d’ouvrir le dossier plugins via votre explorateur de fichiers, faire un clic droit dessus et sélectionner : Nouveau terminal au dossier.

L'explorateur de fichiers, et le menu pour ouvrir le terminal dans le dossier présenté
Une alternative pour ouvrir votre terminal sur le bon dossier

De là on va lancer la commande d’installation de create-block. Cette commande va créer le dossier de l’extension, donc vous n’avez pas besoin de le faire manuellement.

Shell

Remplacez « capitainewp-gut-bases » par le nom que vous souhaitez donner à votre extension. Notez également que npx est une commande dérivée de npm.

Le terminal de MacOS avec la commande NPX visant à installer create-block
Lancez la commande NPX

Patientez quelques secondes, le temps que les packages soient téléchargés et installés. Tout se fait automatiquement.

Une fois l’installation terminée, vous devriez avoir cet écran :

Le terminal indique que create-block a été installé avec succès dans votre dossier plugins
L’installation est terminée !

Vous devriez voir votre nouveau dossier dans plugins/ :

L'architecture de votre extension dans votre explorateur de fichiers
Voici à quoi ressemble votre plugin dans l’explorateur de fichiers

C’est parfait ! On peut maintenant lancer Webpack.

2. Lancer Webpack

De là, comme vous le suggère le terminal, il vous suffit de taper :

Shell

Là encore adaptez en fonction du nom de votre extension.

Au prochain démarrage de votre ordinateur, il ne faudra pas oublier de relancer Webpack. Pour cela vous ferez :

Shell

Voici ce que devrait afficher votre terminal :

Le terminal affiche différentes informations, comme le fait que Webpack est bien lancé et prêt à compiler les fichiers
Wepack est lancé, prêt à compiler les fichiers de l’extension

Le terminal indique qu’il surveille le dossier en vue de changements et que la compilation s’est bien déroulée. C’est le signe que tout fonctionne correctement !

Le jour ou vous aurez une erreur de compilation, ou une erreur React, elle s’affichera dans cette fenêtre, en rouge.

Conseil

Vous pourriez également lancer directement cette commande depuis le terminal intégré de VSC si vous utilisez cet éditeur de code. Pour cela cliquez sur Terminal > New terminal.

Le terminal sera directement ouvert dans le bon dossier, et vous aurez tout dans une seule fenêtre :

Le terminal de Visual Studio Code
La console dans VSC

De cette manière, vous verrez immédiatement l’état de la compilation ainsi que toute erreur qui s’afficherait en rouge dans la zone inférieure.

Ok c’est parfait ! Comme promis, il n’y a eu aucune configuration difficile ni le besoin de traiter avec Webpack directement.

3. Pour plus tard : mise en production

Lorsque votre extension sera prête pour la production, il faudra lancer la commande npm run build afin de créer une version optimisée de l’extension.

Analyse de l’arborescence de notre extension

Allez, maintenant que c’est installé on va rapidement jeter un oeil à notre extension. Voici son arborescence :

Fenêtre du système montrant l'arborescence des dossiers et fichiers générés par create-block
L’arborescence des fichiers de notre extension de blocs

Build : les fichiers de production

Dans build, vous retrouvez plusieurs fichiers, qui sont le résultat de la compilation par Webpack :

  • index.js est le JS compilé par Webpack qui contient tout le code de vos blocks.
  • style-index.css est le CSS pour le front-end, qui contient les styles de vos blocks
  • index.css : le CSS pour le back-end, pour des styles supplémentaires
  • block.json : qui contient la définition de votre bloc ainsi que certains paramètres

Conseil

Du côté de l’administration WordPress, on va parfois avoir besoin de créer des styles CSS spéciaux pour les champs éditables de nos blocks ou pour surcharger un style de l’admin. C’est pour cette raison que l’on a une feuille de style spécifique pour l’éditeur.

Vous pouvez jeter un oeil au fichier index.js compilé mais vous verrez un code vraiment pas sexy : c’est le code compilé rétrocompatible généré par Webpack.

Nodes modules : les dépendances du projet

On retrouve également le dossier nodes_modules. Regardez le nombre de dossiers qu’il contient : ce sont toutes les dépendances nécessaires au projet (il faut savoir que certaines dépendances ont aussi leurs propres dépendances).

C’est le fichier package.json qui est le responsable. D’ailleurs si vous l’ouvrez vous ne verrez qu’une dépendance à @wordpress/scripts. C’est cette librairie qui appelera toutes les sous-dépendances nécessaires au bon fonctionnement du projet.

Vous pourrez donc ajouter vos propres dépendances NPM ici si vous en avez le besoin dans votre projet.

Src : le dossier de travail

Le dossier src est celui dans lequel on va travailler. C’est un dossier qui disparait lorsque l’on « build » le projet pour le mettre en production car il ne sert qu’au développeur.

Le fichier src/index.js est le script de base de notre premier bloc. Il est accompagné de edit.js ainsi que save.js. On va analyser tout cela en détail un peu plus tard. On retrouve également block.json qui permet de définir l’existence du bloc.

D’ailleurs, lorsque l’on ajoutera d’autres blocs, il faudra légèrement modifier cette structure de base.

On retrouve également un fichier editor.scss et un autre style.scss : Webpack les compilera automatiquement dans le bon fichier CSS.

Aparté: Les préprocesseurs CSS

Un petit mot sur les préprocesseurs CSS comme Sass : leur objectif est de vous simplifier l’écriture du CSS en proposant des écritures sympathiques :

– Les variables, pour réutiliser facilement des valeurs

– l’imbrication, afin d’éviter la répétition des sélecteurs

– la séparation en plusieurs fichiers, pour mieux organiser votre code…

Create-block embarque Sass, le plus utilisé des préprocesseurs CSS. Webpack compilera automatiquement les fichiers.

Si vous n’êtes pas à l’aise avec les préprocesseurs CSS, aucun souci, vous pouvez écrire du CSS standard dans ces fichiers et ça fonctionnera tout aussi bien !

Si vous voulez réviser ou apprendre les bases en 5 minutes, direction la doc ! Vous allez très vite gagner du temps sur l’écriture de votre CSS.

Les bases de Sass

En parallèle je vous conseille d’installer Emmet sur votre éditeur de code afin d’être au top de l’efficacité ! Il est déjà inclus de base dans VSC.

Le fichier capitainewp-gut-bases.php

Enfin, le fichier capitainewp-gut-bases.php (où tout autre nom correspondant au nom de votre projet) contient la déclaration du bloc via la fonction register_block_type() dont on va bientôt reparler.

Il n’y aura même pas besoin de charger les scripts et les styles, comme on le fait avec les thèmes (voir le cours chargement des ressources) grâce aux fonctions wp_register_style() et wp_register_script(), car WordPress s’en charge automatiquement pour chaque bloc !

Le nécessaire a également été fait pour vous permettre d’internationaliser vos blocs et les traduire dans différentes langues.

Vous êtes prêt à créer votre premier bloc

Vous voilà désormais pleinement opérationnel pour créer vos blocs !

Dernière chose : n’oubliez pas d’activer votre extension avant de continuer. Vous pouvez en profiter pour modifier la description au début du fichier capitainewp-gut-bases.php.

L'écran des extensions dans WordPress. Pour le moment, notre extension de blocs Gutenberg n'est pas activée
N’oubliez pas d’activer l’extension avant de continuer !

N’hésitez pas à utiliser cet outil pour tous vos sites qui nécessiteront des blocs sur mesure !

Maintenant, avant de se lancer dans la création de notre premier bloc, on va faire un dernier petit détour pour aborder quelques notions fondamentales d’ESnext ainsi que de React.

15

Questions, réponses et commentaires

  1. contact

    Le 12 avril 2018

    Hello Maxime,
    Merci pour cette formation.
    Pas moyen d’installer Local by Flywheel. Peut-on le remplacer par Wamp pour suivre ce tuto ?

    1. Maxime BJ

      Le 12 avril 2018

      Oui pas de souci ! Je te conseille même plutôt MAMP qui fonctionne mieux sur Windows que ses collègues (Wamp…) et reconnu pour poser moins de soucis.

      Qu’est-ce qui bloque pendant l’installation de Local ? Tu sais ?

      1. contact

        Le 14 avril 2018

        Difficile de savoir, ça bloque sur starting local machine… J’ai essayé en supprimant Oracle VM virtual box, comme conseillé sur les forums mais sans résultat. On est apparement un certain nombre à être bloquer surtout avec win 7.

  2. info3

    Le 17 décembre 2018

    Bravo Maxime, un super boulot, riche d’enseignements, de bonnes pratiques, vraiment didactique.

    1. Maxime BJ

      Le 21 décembre 2018

      Merci beaucoup ! 🙂

  3. Houwk

    Le 20 février 2019

    Un article parfait 😀

    Petite question lorsqu’on créé un bloc, tout le code est compilé dans gutenberg_blocks-cgb-block-js pas moyen de faire un appel js et css que lorsque le bloc est appelé ?

    1. Maxime BJ

      Le 20 février 2019

      Merci !
      Tout le code est effectivement compilé dedans oui, mais tu pourrais très bien appeler un autre script en parallèle via enqueue script. Mais ça dépend vraiment de ce que tu veux faire !

  4. guillaume.tirard

    Le 18 mars 2019

    Hello, merci beaucoup, oui c’est très clair pour l’instant.

    Toute l’installation est basée sur le fait de créer ses blocs dans des plugins, j’aurai besoin de les installer plutôt dans mon thème enfant. Mais je verrai bien plus tard comment adapter la configuration à ce besoin, cela ne m’empêche pas d’apprendre les fondamentaux en attendant.

    Merci.

    1. Maxime BJ

      Le 18 mars 2019

      En fait il vaut mieux les laisser dans une extension quand même comme je l’explique dans un cours précédent. C’est plus simple à gérer !

  5. Ogan

    Le 6 juin 2021

    Hello,

    Merci pour ce tuto qui permet de découvrir les coulisses de Gutenberg.

    Je pense avoir trouvé une mini coquille dans le texte au point 2. Lancer Webpack … Au prochain démarrage de votre ordinateur

    Le nom de dossier à la fin de la ligne de commande ( cd /Sites/gutenberg/app/public/wp-content/plugins/capitainewp ) devrait être “capitainewp-gut-bases”, non ?

    1. Maxime BJ

      Le 7 juin 2021

      Merci ! Je corrige tout de suite 🙂

  6. Mary

    Le 12 avril 2023

    Bonjour, Tout d’abord, merci pour vos cours qui sont toujours aussi bien rédigés et compréhensibles et pour la qualité de la pédagogie ! J’avais une question bête… est-ce qu’il est pertinent de coupler la création de blocks Gutenberg et ACF ou un seul des deux suffit à personnaliser un site web ? Merci par avance pour votre réponse.

    1. Maxime BJ

      Le 13 avril 2023

      Merci !
      Tu peux choisir : soit faire des blocs avec ACF, ce qui est beaucoup plus simple et beaucoup plus rapide, avec seulement du PHP. Soit les faire nativement en React. Dans l’absolu il n’y a plus trop d’avantages à utiliser la méthode native en réalité. Donc je recommande l’utilisation d’ACF. Ce cours te montre comment faire : https://capitainewp.io/formations/acf/blocs-acf-gutenberg/

      1. Mary

        Le 13 avril 2023

        Bonjour Maxime, merci beaucoup pour ces précisions, d’après ce que je lis, si on souhaite faire appel à une API il vaut mieux privilégier la création de blocks natifs en REACT, si ce n’est pas le cas on peut utiliser ACF ? Merci d’avance pour la réponse.

        1. Maxime BJ

          Le 13 avril 2023

          Au final tu pourrais faire ça aussi avec des blocs ACF. Après ça dépend vraiment de comment tu vas appeler l’API et les besoins en performance. Les 2 solutions peuvent marcher en tous cas. si tu le fais en ACF, tu pourras appeler l’API distante à partir du template de rendu PHP. Si tu utilises React, tu pourrais aller directement sonder l’API à partir de JS.

Laisser un commentaire