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

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.

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.

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

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. Et on va le faire au travers du Hook le plus classique de WordPress : 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 dont 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 style 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 connaitre 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 :

Et pour éviter quelques soucis de styles dans l’admin, on va également ajouter dans editor.css :

Si on ne fait pas ça, le style par défaut des paragraphes dans l’éditeur prendrait le dessus. On aurait donc une marge en trop à la fin du dernier paragraphe.

Aujourd’hui, le CSS de WordPress s’améliore de plus en plus, et on devrait donc avoir besoin de moins en moins de compenser les styles. Mais parfois, on n’aura pas le choix.

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 :

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.

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

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 :

Là encore, on va compenser le dernier paragraphe dans l’admin via editor.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 :

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

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

Dans ce cas, il faudrai 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, au niveau du code, 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.

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