Formation « Créer des blocs avec Gutenberg »

Create-guten-block : démarrer rapidement ses projets Gutenberg

Lecture : 8 minutes • Pratique : 10 minutes • 4

La partie la moins évidente de Gutenberg est de mettre en place les outils de build avec Webpack, afin de compiler ses fichiers. Et ça peut vite devenir un casse-tête ! Heureusement, tout va être extrêmement simple avec create-guten-block.

Qu'est-ce que create-guten-block ?

Le logo Create-Guten-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-guten-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 !

Create-guten-block est un projet open source créé par Ahmad Awais, un développeur très actif dans la communauté WordPress, qui participe régulièrement à l’amélioration du coeur du CMS. Voici ce qu’il dit de son projet :

Ahmad Awais
WordPress Core Contributor
Tedx Speaker

Le conseil Ahmad Awais

Full Stack WordPress Developer & Designer

Il est très compliqué de configurer des choses comme webpack, React, ES 6/7/8/Next, ESLint, Babel, etc…

Vous risquez d’y passer des heures avant même de pouvoir écrire votre premier block Gutenberg « Hello World ».

En plus cela nécessite de constamment maintenir et mettre à jour votre configuration avec les nouveaux outils d’une communauté JS toujours en mouvement.

create-guten-block vous permet de vous affranchir de toutes ces problématiques et avoir un environnement prêt-à l’emploi pour créer sereinement vos blocs Gutenberg.

Suivez-moi sur Twitter : @MrAhmadAwais • Mon site : AhmadAwais

Eh bien merci Ahmad !

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 !

Information

WordPress devrait proposer à terme un module un peu plus officiel, mais en attendant, celui-ci tient ses promesses de simplicité et marche très bien !

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

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-guten-block sur Github pour voir un peu de quoi il en retourne.

Mise en place de create-guten-blocks

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 by Flywheel, 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.

Attention

Si vous suivez cette formation avant la sortie officielle de Gutenberg, il faudra alors télécherger l'extension Gutenberg sur le répertoire officiel. Allez dans Extensions > Ajouter puis cherchez simplement "Gutenberg".

1. Installer create-guten-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 échaper avec un backslash \ (Alt + Maj + / sur Mac)

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

npx create-guten-block capitainewp

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

Installation de create guten blocks
Le script d’installation de create-guten-block s’occupe de tout !

Une fois installé, vous devriez voir votre nouveau dossier dans plugins/ :

Le dossier a été créé automatiquement

C’est parfait ! On peut maintenant lancer Webpack.

Attention

Si vous obtenez une erreur, vérifiez que votre version de node.js est bien à jour car create-guten-block nécessite au moins la version 8. Dans ce cas rendez-vous simplement sur le site de node et téléchargez la dernière version de l'installeur Windows/Mac/linux.

2. Lancer Webpack

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

cd capitainewp puis npm start.  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 :

cd /Sites/gutenberg/app/public/wp-content/plugins/capitainewp puis npm start.

Webpack est lancé, prêt à compiler lors d’un changement de fichier

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.

Ok c’est parfait ! Comme promis, il n’y a eu aucune configuration difficile ni le besoin de traiter avec Webpack directement. Ahmad a fait un excellent travail avec ce module !

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 :

Dist : les fichiers de production

Dans dist, vous retrouvez 3 fichiers :

  • blocks.build.js : c’est le JS compilé par Webpack qui contient tout le code back de vos blocks.
  • blocks.style.build.css : le CSS pour le front-end, qui contient les styles de vos blocks
  • blocks.editor.build.css : le CSS pour le back-end, pour des styles supplémentaires

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 blocks.build.js compilé mais vous verrez un code vraiment pas sexy : c’est le code compilé rétrocompatible généré par Webpack.

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 à CGB-script. En fait Ahmad a créé son propre package avec ses dépendances afin d’éviter de saturer votre fichier.

Vous pourrez donc ajouter vos propres dépendances NPM ici. C’est d’ailleurs ce que l’on fera plus tard dans cette formation.

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 init.php contient l’enregistrement des styles et scripts via 2 nouveaux hooks : enqueue_block_assets et enqueue_block_editor_assets.  On y reviendra mais tout ce qu’il faut savoir pour le moment c’est que create-guten-block s’est occupé de tout câbler afin que tout fonctionne directement.

Le fichier src/blocks.js est le fichier original, qui sert à appeler tous les blocs. Quand on regarde son code on a simplement :

JS
src/blocks.js
import './block/block.js';

Lorsque l’on ajoutera d’autres blocs, on viendra ajouter de nouvelles lignes ici pour les appeler.

Attention

Quand vous avez créé un nouveau bloc et que vous ne le voyez pas apparaitre dans Gutenberg, vérifiez en premier lieu que vous n'avez pas simplement oublié d'ajouter l'import dans ce fichier.

Le dossier src/block/ est un exemple basic de bloc. Le fichier principal est block.js mais je vais vous proposer de l’appeler index.js à l’avenir car ce sera plus simple pour l’appeler.

On retrouve aussi un editor.scss et un style.scss : Webpack les compilera automatiquement dans le bon fichier CSS. La plupart du temps on écrit directement dans style.scss : c’est le CSS qui donnera son apparence au bloc.

Comme je disais précédemment, editor.scss permet de mettre des styles pour corriger les effets de bord de l’éditeur ou ajouter des styles aux champs d’édition, juste pour l’interface d’administration.

Et enfin si on remonte d’un cran on voit src/common.scss : Ce fichier vous permet d’y stocker des styles communs à tous les blocs, ainsi que des variables Sass (couleurs, tailles)… afin d’observer le principe DRY : dont repeat yourself.

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-guten-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.

En parallèle je vous conseille d’installer Emmet sur votre éditeur de code afin d’être au top de l’efficacité !

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

Vous voilà désormais pleinement opérationnel pour créer vos blocs ! Dites-moi en commentaire si vous avez trouvé l’approche facile ou compliquée, autant au niveau de l’installation que la compréhension de ce que vous faites.

Dernière chose : n’oubliez pas d’activer votre extension avant de continuer. Vous pouvez en profiter pour modifier la description dans plugin.php.

N’oubliez pas d’activer votre extension !

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.

4

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 ?

Laisser un commentaire