Formation « Des champs administrables avec ACF »

Créer des blocs dans Gutenberg avec ACF

Lecture : 8 minutes • 23

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é !

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.

Conseil

Si vous êtes une entreprise, vous allez gagner énormément de temps avec cette approche, et donc être plus rentable, sans perdre en ergonomie ou en performance.

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 !

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.

Attention

Il vous faudra impérativement la version PRO d’ACF afin de créer d’utiliser les fonctions de création de blocs que l’on s’apprête à voir dans ce cours.

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.

Le bloc réalisé dans la documentation ACF

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

Conseil

Grâce aux champs de relations, vous allez pouvoir faire des blocs poussés qui seront capables de récupérer les données d’autres publications.


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

Documentation des blocs via ACF

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é :

Aperçu du rendu final de notre bloc Extension géré par ACF.
Voici à quoi ressemblera notre bloc Plugin géré par ACF

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 :

PHP
functions.php

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 :

Capture d'écran du menu d'insertion de blocs de l'éditeur, où l'on voit notre bloc apparaitre dans la liste
Votre bloc apparaîtra dans la liste, avec son icône, sa description et dans la catégorie indiquée

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.

Conseil

Utilisez une feuille de style séparée pour vos blocs car elle aura besoin d’être chargée dans l’éditeur visuel.

Configurer le groupe de champs

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

L'interface de configuration du groupe de champs d'ACF
La configuration du groupe de champs est tout à fait classique

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 :

PHP
blocks/plugin.php

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 :

CSS
css/blocks.css

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 :

Le bloc apparaît dans l'éditeur, avec son aperçu à gauche et les champs ACF à droite
L’aperçu du bloc apparaît en temps réel et on retrouve nos champs ACF à 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 :

Les champs peuvent s'afficher directement dans l'éditeur, ce qui est pratique lorsqu'il y en a beaucoup.
Les champs s’affichent dans l’éditeur directement

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 !

Capture d'écran du site, où l'on peut voir notre bloc ACF
Le bloc s’affiche correctement sur le site

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.

Aperçu du bloc recette
Voici à quoi ressemblera notre second bloc

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 :

PHP
functions.php

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

Configuration du groupe de champs pour le bloc recette
Le groupe contient simplement un champ 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.

PHP
blocks/recipe.php

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 :

CSS
css/blocks.css

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 :

Le message réservé à l'admin WordPress nous invite à sélectionner une recette
Le message nous invite à sélectionner une recette

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

L'éditeur affiche la recette dès la sélection
Sélectionnez une recette, 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.

L'éditeur met à jour instantanément le bloc avec la nouvelle recette
Changez de recette, la mise à jour est instantanée

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é !

23

Questions, réponses et commentaires

  1. fabien

    Le 16 avril 2021

    le premier code php à mettre dans fonctions est faux, et bloque tout le site

    1. Maxime BJ

      Le 16 avril 2021

      Quelle est l’erreur PHP correspondante ?

      1. Gov

        Le 5 septembre 2021

        Fatal error: Uncaught Error: Call to undefined function acf_register_block_type()

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

          1. 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à

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

            2. 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 !

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

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

  2. 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,

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

      1. Cha

        Le 11 mars 2022

        Super merci beaucoup 🙂

  3. 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 ?

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

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

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

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

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

  5. Thierry

    Le 5 juin 2023

    Bonjour Maxime,
    est-ce cela peut fonctionner avec les champs répéteurs ?

    1. 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 !

      1. Thierry

        Le 6 juin 2023

        je vais essayer cela. Merci pour ta réponse.

  6. 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,

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

Laisser un commentaire