Avec l’éditeur de blocs modernes qui a succédé à TinyMCE, les développeurs peuvent désormais créer de superbes blocs sur mesure. Le souci c’est qu’il faut avoir de bonnes bases en ReactJS, ce qui n’est pas toujours le cas pour les développeurs WordPress qui sont plutôt spécialistes de PHP. Heureusement, ACF va nous permettre de créer des blocs en toute simplicité !
Sommaire du cours
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 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 par exemple vous vouliez communiquer avec une API externe, alors ce serait impossible.
Si tel est votre cas et si vous souhaitez aller plus loin en créant de vrais blocs Gutenberg natifs, je vous propose de découvrir ma formation !
Les premiers cours sont gratuits et vous permettront de découvrir plus en détails les avantages de l’éditeur visuel.
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.
Afin d’éviter de reprendre le même exemple, on va voir 2 autres cas assez différents. 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 non natif. Et on va le faire au travers d’un Hook ACF :
La fonction acf_register_block_type()
est une surcouche d’ACF qui va appeler au final la fonction native de WordPress register_block_type()
, justement conçue pour déclarer un bloc dans l’éditeur visuel.
À l’intérieur on va déclarer quelques paramètres pour qualifier notre bloc :
- Son slug, qui doit être un nom unique ;
- Le titre, qui apparaîtra dans l’interface de l’éditeur ;
- La description, pour indiquer à quoi sert ce bloc ;
- Le template PHP qui sera appelé. Pour cela on va créer un dossier
/blocks/
à cet effet ; - La catégorie dans laquelle apparaîtra le bloc dans la fenêtre de sélection de blocs ;
- L’icône du bloc dans le sélecteur ;
- Quelques mots-clés pour trouver facilement le bloc via la recherche ;
- Et enfin, on va déclarer une feuille de styles dédiée à nos blocs.
Le template c’est 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.
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 remarquerez d’ailleurs que le bloc sera rangé dans la catégorie « Mise en forme » car on a indiqué formatting
. Les valeurs disponibles sont common, formatting, layout, widgets, ou encore embed.
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-
.
Et enfin, un petit mot sur le CSS : on a besoin d’une feuille de styles séparée de celle de notre thème, car il va falloir également la charger dans l’éditeur visuel pour que notre aperçu temps réel s’affiche correctement.
Ce que l’on va donc déclarer dans enqueue_assets
va être chargé autant en back qu’en front, et seulement si le bloc est utilisé, d’où l’intérêt de dédier un fichier au CSS de notre bloc.
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 créer 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éé donc un fichier blocks/plugin.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()
.
Maintenant il va falloir ajouter un peu de CSS et on va aller le mettre dans notre fichier dédié aux blocs :
Comme l’éditeur visuel de WordPress a la fâcheuse tendance à mettre de grosses marges sur les paragraphes, j’ai dû ajouter des styles de compensation pour l’éditeur visuel en surchargeant .editor-styles-wrapper
.
Tester le fonctionnement de notre bloc
Allez, on va maintenant pouvoir aller 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.
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 recette
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 :
On utilise à nouveau les mêmes paramètres mais on change les valeurs. Cette fois le template sera blocks/recipe.php
et l’icône une carotte. Je ne mets pas de mots-clés cette fois car « recette » est assez explicite.
Aparté: Une feuille de styles par bloc ?
Vous remarquerez que j’ai déclaré la même feuille de style au lieu d’en créer une nouvelle et c’est voulu : au lieu de déclarer une feuille CSS par bloc, je n’en veux qu’une pour tous mes blocs. La raison est l’optimisation des performances : avec une seule feuille de styles, je diminue les requêtes HTTP au chargement de la page.
Même si j’utilise 2 fois wp_enqueue_style()
, le fichier ne sera chargé qu’une seule fois car il a le même slug capitaine-blocks
et donc WordPress comprendra.
Rien ne vous empêche de charger une feuille de styles par bloc si vous préférez. Ce qui est d’ailleurs plus simple si vous comptez réutiliser des blocs d’un projet à un autre. Dans ce cas rangez la feuille dans le dossier /blocks/votre-block
pour récupérer facilement tous les fichiers d’un bloc entre chaque projet.
Du coup, c’est à vous de choisir !
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 ».
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.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 :
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 à droite, elle s’affiche instantanément :
Essayez de changer de recette, la modification se fait 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 !
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é !
fabien
Le 16 avril 2021
le premier code php à mettre dans fonctions est faux, et bloque tout le site
Maxime BJ
Le 16 avril 2021
Quelle est l’erreur PHP correspondante ?
Gov
Le 5 septembre 2021
Fatal error: Uncaught Error: Call to undefined function acf_register_block_type()
Maxime BJ
Le 12 septembre 2021
Est-ce que tu as bien vérifier qu’ACF est installé, et activé ? Car je ne vois que ça comme cause possible. Pour référence : https://www.advancedcustomfields.com/resources/acf_register_block_type/ prouve que j’ai bien ortographié le nom de la fonction.
Batiste
Le 2 mars 2022
Bonjour je sais d’où vient l’erreur qu’il a, il faut une version payant pour créer de blocs gutenberg avec acf voilà
Steffy
Le 3 mars 2022
Merci Batiste,
cela faisait 2 heures que je debuggais pour savoir où cela merdait …
Bref retour à la case départ pour moi.. merci encore
Maxime BJ
Le 2 mars 2022
Ouais en effet, c’est une fonction déclarée uniquement dans ACF Pro ! J’ignorais complètement. J’ai ajouté une remarque à ce sujet au début du cours. Merci pour ta contribution !
Arthur
Le 19 décembre 2023
Bonjour, s’il vous plaît, ajoutez cette mention au tutoriel car c’est très frustrant et je préfèrerai être averti avant de commencer que je ne peux pas utiliser cette fonction.
Maxime BJ
Le 19 décembre 2023
C’est déjà fait. Il y a un bloc jaune au début du cours qui indique cela.
Cha
Le 11 mars 2022
Bonjour Maxime,
Merci pour ce super tuto qui m’a permis de créer mes premiers blocs ACF Gutenberg !
J’ai juste un petit problème, dans le template d’un de ces blocs, j’aimerai appeler un champ créé dans ma page d’options / dans une autre page, mais ça ne semble pas fonctionner.. Pourtant je n’ai pas d’erreur spécifique…
Merci d’avance,
Maxime BJ
Le 11 mars 2022
J’ai un cours dédié aux pages options dans ACF justement. Tu y trouveras la réponse ! Il faut ajouter un second paramètre pour indiquer que l’information se trouve dans les pages d’options : https://capitainewp.io/formations/acf/acf-page-options
Cha
Le 11 mars 2022
Super merci beaucoup 🙂
Nolwenn
Le 25 avril 2022
Bonjour Maxime,
J’essaye de créer un groupe de champs acf pour faire :
– une relation entre un type de publication cpt ui et une taxonomie
– un changement de couleur de bloc en fonction des informations (liste déroulante)
Je n’arrive pas à faire le code qu’il faut pour afficher mon groupe de champs acf sur ma page et tous les tutos que j’ai trouvé ne fonctionne pas.
Peux tu m’aider ?
Maxime BJ
Le 25 avril 2022
Pour le premier tu ne devrais pas avoir besoin de quoi que ce soit, puisque une taxonomie est forcément rattachée à un CPT et WordPress fournit déjà l’interface pour ça. Tu peux créer et associer une taxo à un CPT dans CPT UI d’ailleurs.
Pour ton second bloc, ça va dépendre de ce que tu veux faire exactement, il faut que les valeurs de ta liste déroulante correspondent aux noms de classes CSS (qui définissent la couleur). Dans ton champ select ACF tu peux définir tes valeurs comme suit : « color-red: Couleur Rouge » le premier élément étant la valeur stockée et affichée dans le template (donc ta classe CSS) et la seconde la valeur affichée dans le champ select.
Julien
Le 23 mars 2023
Bonjour,
Est-il possible de faire appel à une requête type get_posts() avec les blocks dans le template ?
Mon template contient la requête et l’appel à un template_part pour afficher les derniers articles, cependant, le rendu n’est pas du tout celui que j’attends, la boucle retourne à chaque fois le titre de la page d’accueil par exemple.
Merci bien.
Maxime BJ
Le 23 mars 2023
Il faut que tu utilises la WP_Query plutôt. Les paramètres seront les mêmes mais ça ne se basera pas sur la requête principale : https://capitainewp.io/formations/developper-theme-wordpress/wp-query/ n’oublie pas d’utilise wp_reset_postdata(); à la fin de ta boucle personnalisée.
Julien
Le 23 mars 2023
Merci pour votre réponse.
Comme mon template n’est pas attaché à un groupe field ACF, j’ai également dû utiliser le paramètre « mode » en « view » dans la fonction acf_register_block_type.
Tout fonctionne à la perfection. Merci de votre réponse et aide.
Maxime BJ
Le 23 mars 2023
Il est forcément rattaché à un groupe de champ, sinon ce n’est pas un bloc ACF par définition. Le mode view permet d’afficher les champs dans l’éditeur ou dans l’inspecteur, de mémoire.
Thierry
Le 5 juin 2023
Bonjour Maxime,
est-ce cela peut fonctionner avec les champs répéteurs ?
Maxime BJ
Le 5 juin 2023
Tous les champs ACF sont utilisables dans les blocs ACF en effet ! Au final derrière tu vas simplement créer un rendu PHP de ton bloc de manière tout à fait classique, comme si tu rendais une page. Donc tout fonctionnera comme d’habitude, c’est ça qui est magique !
Thierry
Le 6 juin 2023
je vais essayer cela. Merci pour ta réponse.
Dépres
Le 6 décembre 2023
Bonjour,
J’ai créé mes bloc ACF et ils sont bien disponibles dans Gutenberg mais je ne peux pas leur attribuer de champs class qui me permettrait de les styliser au besoin (l’option bloc > avancé > class des bloc gutenberg classique ne fonctionne pas. Peux-tu m’aider ?
Merci d’avance.
Bien cordialement,
Maxime BJ
Le 6 décembre 2023
Je me rend compte que ce cours n’est pas du tout à jour, notamment sur la déclaration du bloc (qui passe maintenant par un block.json) et je ne récupère pas en effet la class CSS du bloc. Normalement, dans ton PHP, tu as accès à une variable $block qui va contenir les classes CSS de celui-ci, dont celles que tu as customisé dans l’éditeur. Essaie d’afficher : $block[‘className’] et tu devrais avoir tes classes.
Quentin
Le 8 août 2024
Bonjour,
Dans la partie « Afficher ce groupe de champs si », on ne peut pas cumuler « Bloc = monbloc » et « Type de page = page d’accueil » ?
Merci d’avance pour ton retour
Maxime BJ
Le 12 août 2024
Oui tu peux tout à fait avoir des conditions « Et » et « Ou » que tu peux cumuler. Tu peux donc faire des conditions complexes pour répondre à des besoins très spécifiques.