Créer des blocs sur-mesure pour Gutenberg avec ACF

Ce qui fait peut-être l’une des plus grandes forces de Gutenberg, c’est la possibilité de créer des blocs sur-mesure pour répondre à tous les besoins. De cette manière, on lève toutes les limites techniques !

Mais voilà, Gutenberg est fait en React, et la plupart des développeurs WordPress sont historiquement appris à faire du PHP.

Dans ce cours, on va voir comment ACF peut nous sauver la mise en nous permettant de créer des blocs avec quelques lignes de PHP.

Pourquoi créer des blocs avec ACF ?

J’ai consacré une formation complète à la création de blocs Gutenberg natifs. Au travers d’une cinquantaine de cours je vous montre comment créer des blocs à partir de React.

Mais ça demande une certaine montée en compétences, surtout si comme moi, vous êtes un développeur PHP de formation.

Vous n’avez pas envie ? Eh bien j’ai une bonne nouvelle pour vous ! Il est possible de créer des blocs Gutenberg sur mesure grâce aux champs ACF !

Et il n’y a que des avantages à cela :

• C’est plus simple, on reste dans la logique ACF, il n’y a pas de JS à apprendre ;
• C’est beaucoup plus rapide et ça nécessite moins de code ;
• C’est tout autant efficace qu’un bloc natif, car le rendu se fait en quasi-temps réel ;
• Vous bénéficiez de la puissance de tous les champs ACF qu’on a vus jusqu’à présent.

En fait, vous n’êtes limités que par les possibilités des champs proposés par ACF.

Si vous souhaitez aller plus loin en créant de vrais blocs Gutenberg natifs, je vous propose de découvrir ma formation !

Découvrir la formation Gutenberg

Les premiers cours sont gratuits et vous permettront de découvrir plus en détails les avantages de l’éditeur visuel.

Différence d’UX entre les blocs ACF et les natifs

En réalité, il y a quand même une toute petite différence d’UX entre les blocs Gutenberg et les blocs natifs.

Et cette petite différence va peut-être faire toute la différence dans votre choix stratégique concernant les blocs.

Lorsqu’on édite un bloc natif, on écrit le contenu directement à son emplacement, c’est on ne peut plus fluide.

Mais lorsqu’on va créer un bloc avec ACF, le bloc va agir de 2 manières différentes lorsqu’on va le sélectionner, selon le réglage qu’on aura choisi :

• Soit le bloc va être remplacé par un groupe de champs classiques d’ACF ;
• Soit le bloc restera, et les champs apparaîtront sur le côté.

Dans le second cas, le bloc se mettra à jour quasiment en temps réel, avec toutefois un petit délai.

Dans les deux cas, il faudra saisir le contenu par le biais des champs et non directement dans l’aperçu. On remarque également que les champs ACF ont une apparence quelque peu différente des champs natifs de Gutenberg.

En général, les clients n’y verront que du feu, mais ces petits détails peuvent faire toute la différence et influencer votre choix.

Que faire avec les blocs ACF ?

Vous pouvez presque tout faire comme bloc avec ACF ! Toute ce que vous pouvez imaginer faire avec les champs textes, images, relationnel, flexible… Vous pourrez le refaire dans Gutenberg.

La documentation d’ACF montre comment faire un bloc « Témoignage ». Il est plus évolué que le bloc témoignage classique car il permet d’ajouter une photo et choisir une couleur de fond.

Cet exemple est très intéressant pour apprendre. De notre côté, on va voir 2 autres cas assez différents l’un de l’autre. On va créer :

• Un bloc qui permet de présenter une extension WordPress ;
• Et un bloc recettes qui récupère les données d’un article.

Dans le premier on va utiliser des champs standards comme l’image, le texte et l’URL. Mais pour le second on ira récupérer une recette grâce au champ « Objet publication ».

Pour en savoir plus sur les possibilités offertes par ACF pour la création de blocs, consultez la documentation à ce sujet.

Cas n°1 : le bloc Extension

On va commencer par notre bloc « Extension » qui est un bloc simple avec des champs ACF classiques. Voici à quoi il ressemblera une fois terminé :

Déclarer le bloc dans Gutenberg

Pour commencer, on va se rendre dans notre functions.php pour ajouter un peu de code. Le but étant de déclarer à Gutenberg un nouveau bloc. Pour cela, on va utiliser le Hook acf/init.

On utilisera ensuite la fonction native de WordPress register_block_type(), car ACF sait très bien se brancher dessus. Ainsi, on reste toujours au plus proche du natif.

C’est tout ce que l’on a besoin de faire côté PHP. Maintenant, ça va se jouer du côté du JSON.

Mais avant cela, créez un dossier /blocks/ dans votre thème, puis à l’intérieur un second dossier /plugin/.

Dedans, ajoutez ces 4 fichiers :

• block.json pour déclarer le bloc ;
• template.php qui va accueillir le template HTML/PHP de notre bloc ;
• style.css la feuille de styles du bloc ;
• editor.css une feuille de styles spéciale pour l’admin.

Cette dernière servira à compenser certains styles qui passeraient mal dans l’interface d’administration, à cause des surcharges en markup et en styles de l’éditeur sur les blocs.

Si votre bloc nécessite un script JS, ajoutez également un fichier script.js. Mais pour notre exemple, ce ne sera pas nécessaire.

Votre structure devrait ressembler à ceci :

On va commencer par remplir les informations du JSON :

Dans ce fichier, on va déclarer quelques paramètres pour qualifier notre bloc :

• name : son slug, qui doit être un nom unique ;
• title : le titre, qui apparaîtra dans l’interface de l’éditeur ;
• description : la description, pour indiquer à quoi sert ce bloc ;
• category : la catégorie dans laquelle apparaîtra le bloc dans le menu d’insertion ;
• keywords : quelques mots-clés pour trouver facilement le bloc via la recherche ;
• icon : l’icône du bloc dans le sélecteur ;
• style : la feuille de styles dédiée au bloc ;
• script : le fichier JavaScript dédié au bloc (facultatif) ;
• viewScript : Pour charger un JS seulement en front (facultatif) ;
• editorStyle : la feuille de styles de compensation pou l’admin (facultative) ;
• acf : cette partie est ajoutée par ACF aux blocs conçus avec les champs.

Dans cette dernière section, on doit définir 2 informations :

Tout d’abord le mode qui permet de définir si on veut les blocs dans l’inspecteur à droite ou dans l’éditeur à la place du bloc.

• preview permet d’afficher les champs à droite dans l’inspecteur, mais comme la zone est étroite, ce n’est pas idéal pour certains champs comme le répéteur et le champ relationnel.
• auto permet d’afficher les champs dans l’éditeur lorsqu’on clique sur le bloc. On ne voit plus l’aperçu du bloc, mais on a beaucoup plus d’espace pour éditer nos contenus.
• edit affiche toujours les champs et jamais l’aperçu du bloc. Déconseillé !

Ensuite, renderTemplate définit le fichier qui va être utilisé à la fois sur le site, pour le rendu final, mais également dans l’éditeur en back, pour créer l’aperçu en temps réel.

Pour connaître toutes les catégories disponibles nativement dans WordPress, consultez la documentation officielle. À ce jour il existe : text, media, design, widgets, theme, et embed.

Si on va dans l’éditeur, on devrait voir l’icône, la description et le titre s’afficher dans l’interface de sélection de blocs :

Vous pouvez définir une icône en SVG, ou pour faire plus simple, utiliser l’une de celles proposées par les Dashicons de WordPress, exactement comme lorsque l’on définit un custom post type.

La seule différence c’est qu’on retire le préfixe dashicons-.

Configurer le groupe de champs

On va maintenant aller configurer un nouveau groupe de champs et l’assigner à notre bloc :

Je vais avoir besoin :

• D’un champ texte, pour le titre ;
• D’un champ zone de texte pour la description ;
• D’un champ image pour l’icône ;
• D’un champ URL pour faire un lien vers la page de l’extension ;
• Et d’un champ couleur pour personnaliser le fond du bouton.

Pour terminer, on va l’assigner à Bloc, et on devrait trouver dans la liste notre bloc Extension.

Préparer le template du bloc

Dernière étape : il faut écrire le template de notre bloc. Il sera utilisé non seulement en front sur le site, mais également en back dans l’éditeur, pour l’aperçu quasi temps réel.

Je crée donc un fichier blocks/plugin/template.php dans le dossier de mon thème, et j’ajoute le code PHP habituel pour donner un rendu à mon bloc :

Rien de nouveau ici, puisqu’on utilise simplement les fonctions classiques d’ACF comme the_field() et get_field(). Elles iront automatiquement récupérer les valeurs des champs rattachés à ce bloc.

Maintenant il va falloir ajouter un peu de CSS et on va aller le mettre dans notre fichier style.css dédié à ce bloc :

Tester le fonctionnement de notre bloc

Allez, on va maintenant pouvoir tester notre bloc ! Créez une nouvelle page ou un article, et appuyez sur le bouton + pour ajouter votre bloc.

Si tout s’est bien passé, il devrait s’afficher dans la liste. Sélectionnez-le et vous devriez voir apparaître votre bloc avec son aperçu, ainsi que les champs ACF dans la colonne de droite :

Si vous avez besoin de plus d’espace pour vos champs, vous pouvez cliquer sur le crayon dans la barre d’outils, et ils seront déplacés dans l’éditeur :

Mais dans ce cas vous perdrez le bénéfice de l’aperçu en temps réel. Toutefois, cela peut être utile lorsque vous avez beaucoup de champs, ou un champ relationnel par exemple.

Vous pouvez forcer ce comportement en indiquant comme mode auto dans le block.json.

Maintenant, affichez votre publication pour vérifier que votre bloc s’affiche là aussi correctement !

Il n’y a rien de plus à faire. Votre bloc fonctionne à la perfection et en toute simplicité !

---

Bien sûr, ce bloc serait parfait s’il permettait de récupérer les informations directement depuis le répertoire officiel de WordPress et sans qu’on ait besoin de les saisir à la main.

Mais ce n’est pas directement possible avec ACF car on aurait besoin de communiquer avec une API distante. Si vous voulez apprendre à faire cela, il faudra basculer sur la formation Développer des blocs Gutenberg.

Cas n°2 : le bloc dynamique des recettes

Pour ce deuxième exemple, on va tirer parti de toute la puissance d’ACF grâce aux champs de relations : on va créer un bloc qui permet de faire la promotion d’une recette à partir de n’importe laquelle de nos publications.

Et il n’y a rien de compliqué là-dedans puisqu’il nous suffit d’utiliser le champ Objet publication ou même le champ relationnel.

Déclarer le bloc

On va utiliser la même fonction acf_register_block_type() que précédemment, et on va le faire dans le même hook. Pas besoin d’en recréer une. Voici ce que ça donne :

Comme pour le premier bloc, créez un dossier /recipes/ dans /blocks/ et ajoutez là aussi les fichiers template.php, block.json, editor.css et style.css.

Puis rendez-vous dans le block.json pour y ajouter les informations de sa déclaration :

On va simplement changer le nom du bloc (chaque bloc doit impérativement avoir un nom unique), son titre, sa description, ses mots-clés et son icône.

je vais également passer le mode en preview pour que le champ s’affiche toujours dans l’inspecteur à droite.

Comme on respecte la même structure pour chaque bloc, l’appel des styles et du modèle PHP seront toujours les mêmes.

Configurer le groupe de champs

On va maintenant aller créer le groupe de champs qui va être simple puisqu’il contiendra un seul champ de type « Objet publication ». C’est lui qui va nous permettre de sélectionner la recette à afficher.

Dans les options du champ, je limite aux Articles (comme je n’avais pas créé de CPT pour mes recettes) et je choisis le format de sortie ID.

On l’assigne cette fois au bloc « Recette ».

Préparer le template

On va maintenant éditer notre fichier blocks/recipe/template.php pour récupérer les informations de notre recette et pour cela on va faire comme on a appris dans le cours sur le champ publication.

Notez que tant qu’on a pas choisi de recette, rien ne s’affichera, d’où l’importance du test pour ne pas générer d’erreur. Dans le elseif, je teste si on est dans l’admin WordPress grâce au conditional tag is_admin() afin d’afficher un message incitant à choisir une recette dans la colonne de droite.

Par contre, sur le site, rien ne s’affichera si aucune recette n’est sélectionnée.

Pour terminer, j’ai ajouté quelques lignes de CSS dans css/blocks.css. J’en profite pour regrouper les sélecteurs de correction des styles de l’éditeur :

Comme le message « Sélectionnez une recette… » n’apparaitra que dans l’interface d’administration, on va utiliser editor.css pour écrire les styles le concernant :

De cette manière, ce CSS ne sera pas chargé inutilement en front.

Tester le bloc

Retournez sur votre publication et ajoutez le bloc. Pour le moment, comme on n’a pas encore choisi de recette, le message s’affiche :

Mais dès lors que vous en choisissez une dans le sélecteur, elle s’affiche instantanément :

Essayez de changer de recette, la modification se fait presque en temps réel ! Il n’y a presque aucun délai de prise en compte.

Pas mal non ? On n’a aucune perte de performance par rapport à des blocs natifs !

Cas n°3 : Un bloc conteneur avec InnerBlocks

Ce qui est fascinant avec les blocs ACF, c’est que vous pouvez ajouter une zone dans laquelle vous pourrez glisser des blocs natifs. Votre bloc agira donc comme un conteneur.

Cette fonctionnalité était à l’origine seulement disponible sur les blocs React, mais ACF a trouvé un moyen de l’implémenter. On va donc voir comment ça fonctionne.

Pour cet exemple, je vais faire un conteneur qui va agir comme un lien d’article.

En effet, bien souvent, on aimerait que tout notre article soit cliquable, au lieu de définir un lien sur l’image, le titre, le texte… mais WordPress ne propose pas ce bloc par défaut.

Qu’à cela ne tienne, vous allez voir que c’est hyper facile à mette en place. Tout d’abord, déclarons notre bloc dans le fichier functions.php :

Il est important de noter que, pour que ce bloc fonctionne, il faudra l’utiliser dans une boucle de requête uniquement.

Je vous passe les détails du block.json car il n’y a rien de nouveau dedans (pensez juste à changer le slug). C’est par contre dans template.php que ça va être intéressant :

La magie opère grâce au composant <InnerBlocks />. C’est un composant React mais comme on est sur du PHP, c’est juste une chaîne de texte tout à fait classique.

En réalité, ACF va venir chercher cette chaîne et la remplacer par les blocs enfants que vous y aurez éventuellement placé.

Autour, j’utilise un tag <a> pour créer le lien, et je récupère le permalien de l’article actuel pour l’afficher dans href.

Côté CSS, on va apporter quelques ajustements pour éviter que tous les textes enfants soient soulignés et de la couleur des liens, car ce ne serait pas très élégant :

Dans editor.scss, j’ajoute une bordure en pointillés pour que l’on voit notre bloc uniquement dans l’éditeur. Mais ce n’est pas une obligation :

Allez insérer ce bloc dans les boucles de requêtes où vous souhaitez englober tous les éléments dans un lien :

Comme vous pouvez le voir, vous allez pouvoir ajouter tous les blocs à l’intérieur. Insérez ensuite les blocs enfants comme l’image mise en avant, le titre de publication, la date…

Bon par contre, un truc chiant, c’est que si vous cliquez dans la zone, ça va activer le lien et naviguer vers la page. Utilisez plutôt la Vue en liste pour manipuler vos blocs.

Astuces des blocs ACF

Pour terminer ce cours intense, mais ô combien pratique, voici quelques petites astuces supplémentaires qui vous seront utiles au quotidien.

Récupérer les champs de la page à partir d’un bloc

Parfois, vous aurez besoin de stocker des informations au niveau de la page plutôt qu’au niveau d’un bloc.

Pour illustrer la problématique, imaginez un blog de jeux vidéo comme IGN ou jv.com :

On pourrait créer un bloc « Note » et stocker la valeur directement dans le bloc, via un champ texte.

Le souci, c’est que si la donnée est enregistrée dans le contenu, on ne pourra pas la requêter. Imaginez que votre client vous demande d’afficher sur la page d’accueil la liste des 5 jeux-vidéo les mieux notés : vous êtes bloqué.

Pour que ça fonctionne, il faudrait plutôt déclarer un groupe de champs au niveau de la page et non pas du bloc. Dans ce cas, le bloc ACF ne contiendrait pas de groupe de champs ACF, et c’est totalement possible.

Mais du coup, il faudra légèrement adapter le code :

La fonction get_field() est programmée pour récupérer en priorité les valeurs du groupe de champs du bloc. Or, là, on veut récupérer les données de la page.

Dans ce cas, utilisez le second paramètre et passez l’identifiant de la page en cours via get_the_ID(). Ainsi, vous récupérez bien les champs assignés à la page.

Activer les fonctionnalités de personnalisation natives

Dernière chose très pratique ! Vous n’aurez parfois pas besoin de réinventer la roue, car même via ACF, vous allez pouvoir activer les fonctionnalités natives des blocs, comme le choix des couleurs de texte, de fond, les espacements, les bordures et les alignements.

Pour les activer, il suffit d’ajouter quelques instructions dans la propriété supports dans le fichier block.json du bloc concerné.

Jetez maintenant un œil à votre bloc depuis l’interface de Gutenberg, et vous verrez de nouvelles options :

Vous allez désormais pouvoir passer votre bloc en pleine largeur, changer les couleurs, modifier les espacements… Si vous voulez connaître toutes les valeurs disponibles, consultez la documentation de WordPress à ce sujet.

D’ailleurs, je vous recommande de passer au moins html à false pour éviter que vos clients n’essaient de modifier le HTML du bloc.

Tout cela est possible car les classes de ces options sont appliquées sur le premier élément HTML du bloc. Si vous avez bien utilisé get_block_wrapper_attributes(), elle va générer automatiquement la classe et l’id du bloc.

Et voilà ! Plus besoin de champs ACF pour gérer les espacements, les couleurs ou même les bordures de vos blocs custom !

---

Vous savez maintenant créer des blocs pour Gutenberg sans même avoir appris à coder en React ! C’est plutôt génial non ? Même si c’est un peu moins temps réel qu’un bloc natif, ça reste très ergonomique et beaucoup plus rapide à mettre en place ! Et pour une agence, cela veut dire meilleure rentabilité !