Guide d’utilisation

Comment récupérer un bloc

  1. Copier le dossier du bloc dans blocks et aller le placer dans le dossier blocks de votre projet.
  2. Vérifier dans les fichiers de style et de script si ceux-ci n’importent pas des dépendances qui seraient manquantes sur votre projet. (Fancybox pour une galerie photos par exemple, countUp.js pour les animations de nombre, etc.)
  3. Lancer une compilation et vérifier qu’il n’y a pas d’erreurs, potentiellement dû à des variables Sass ou des dépendances manquantes.
  4. Synchroniser le nouveau groupe de champs disponible via ACF.
  5. S’il y a besoin, récupérer les templates additionnels du bloc et les réorganiser comme souhaité au sein du projet.
  6. Penser à consulter la page Notes sur les blocs au cas où il y aurait des informations additionnelles à savoir sur le bon fonctionnement du bloc que vous venez de récupérer.
  7. Optionnel : Ajouter la documentation du bloc dans votre projet en reprenant ce qui a été écrit dans la page du module et le mettre dans le fichier doc/client/custom-blocks.md avec une capture d’écran.

Comment ajouter un bloc

  1. Copier le dossier de votre bloc et aller le placer dans le dossier blocks du répertoire.
  2. Si le bloc appelle des templates spécifiques avec get_template_part, les mettre à l’intérieur du dossier de votre bloc et changer le chemin du template (voir section Pour les blocs plus complexes plus bas).
  3. Vérifier que la compilation du bloc fonctionne bien, ajuster les éléments de style trop spécifiques à votre projet au besoin.
  4. Ajouter un élément de type Modules dans le répertoire et ajouter votre bloc sur la page. Ajoutez une description du bloc avec une explication des champs qui y sont liés et mentionnez toute particularité au bon fonctionnement du bloc, par exemple si c’est un carrousel qui a un nombre limite d’éléments à afficher, s’il faut un minimum de texte pour que le bloc affiche correctement, etc. Pensez aussi à classer le module dans le bon type de module et la bonne catégorie.
  5. Si votre bloc a besoin d’une librairie pour fonctionner ou d’une mise en place particulière, veuillez aller ajouter l’indication dans la page Notes sur les blocs.

À ce stade-ci, vous devriez avoir un bloc fonctionnel sur le répertoire. Après avoir lancé une compilation avec npm, vérifiez que votre bloc peut être ajouté à une page et s’affiche bien dans celle-ci. Vérifiez qu’il n’y a pas d’erreur lors de la compilation (est-ce que par exemple une variable SASS serait utilisée dans le style de votre bloc qui n’existe pas dans le répertoire?), qu’il n’y a pas d’erreur dans la console (est-ce que des dépendances sont manquantes ou causent un conflit avec d’autres fonctionnalités?) et que tous vos fichiers sont bien chargés (est-ce que les fichiers appelés dans le block.json existent bien et sont bien nommés?)

Ajustements à surveiller

Il se peut que la transposition du bloc de votre projet au répertoire ne se passe pas aussi aisément que prévu. Si des erreurs surviennent ou que le bloc ne s’affiche pas correctement, on peut commencer par ces quelques pistes de solution.

Des erreurs de compilation SASS

Normalement, le répertoire comprend un style UI de base dans lequel votre bloc devrait pouvoir facilement s’imbriquer. Il peut y avoir un travail d’ajustement à faire si le style a été monté avec des variables spécifiques à votre projet :

  • Pour les polices, le bloc devrait utiliser les variables $font1 et $font2, et avoir des tailles de police en rem.
  • Pour les couleurs, le bloc devrait utiliser les variables $primary et $secondary, $borders, $background-light, $background-dark, ou encore des variations de gris (les variables entre $grey-100 et $grey-900).
  • Le répertoire contient déjà du style pour les composants de base (boutons, liens, flèches de carrousel, etc.). Votre bloc ne devrait pas contenir du style supplémentaire pour ces composants de base (à moins que ce soit vraiment nécessaire pour la particularité du bloc) ou overrider ces styles inutilement.
  • Les liens devraient utiliser le mixin styled-link()

Il se peut que votre bloc nécessite plus de style spécifique (plus de variables de couleur par exemple) et qu’on doive réajuster le style de base du répertoire. Cependant, on va prioriser les ajustements au bloc pour le rendre plus facilement réutilisable sur d’autres projets plutôt que d’ajouter du style dans le répertoire qui possiblement ne servira que pour des cas spécifiques.

Problèmes de dépendance

Faites attention si votre bloc a certaine dépendance, celles-ci pourraient être manquantes ou à une version différente.

Si la dépendance est manquante, c’est à voir selon le contexte et les besoins mais elle pourrait simplement être ajoutée au répertoire. Le répertoire n’a peut-être simplement pas encore de blocs qui demandent cette dépendance, et n’a donc pas été ajoutée pour le moment.

S’il y a une différence de version, ça nécessitera alors peut-être plus d’ajustements. Par exemple, si votre bloc est un carrousel fait avec Swiper à la version 6, il risque de ne pas fonctionner sur le répertoire qui est à la version 7. Vaut mieux alors ajuster le bloc pour que celui-ci fonctionne à la version plus récente et s’ajoute facilement sur les nouveaux projets.

Pour les blocs plus complexes

Si votre bloc est dépendant de d’autres modules de votre projet, on va essayer de le sortir de ces dépendances-là, ou de les rapatrier dans le bloc en essayant le plus possible de les mettre dans le dossier du bloc. Par exemple, si votre bloc est un carrousel d’articles, et que la boucle des articles appelle un template à part, on va tenter de ramener le template dans le bloc. On pourrait par exemple ajouter le fichier du template dans le dossier du bloc, au même niveau que le init.php et le template.php. À ce moment-ci, il faudrait juste réajuster l’appel au template pour diriger vers le bon dossier, comme ceci :

<?php
get_template_part(
  'blocks/nom-du-bloc/nom-du-template',
  null,
  array(
    'item' => $item,
  )
);
?>

Ainsi, les personnes qui récupéreront le bloc pourront alors déplacer le template à l’endroit qu’ils le souhaitent dans leur projet ou le mettre en commun avec un template déjà existant dans leur projet.

Quelques critères à respecter

Pour qu’un bloc puisse être ajouté au répertoire, il doit respecter quelques critères :

  • Le code du bloc doit être d’excellente qualité et il ne doit pas y avoir de bogues.
    Par exemple, le bloc doit respecter les bonnes pratiques PHP et les normes d’accessibilité.
  • La nomenclature des composants doit être respectée, que ce soit au niveau des noms des fichiers, de leur emplacement, ou le nom du groupe de champs ACF.

Aucun bloc ne peut être ajouté au répertoire sans passer par une revue de code par un Lead.