Créer un block Gutenberg Personnalisé avec ACF

Dans cet article, nous allons voir comment créer un block personnalisé à l’aide du plugin ACF (Advanced Custom Field).

Lorsque nous développons des thèmes WordPress sur-mesure, nous réfléchissons en terme de blocks. De notre point de vue, la grande partie d’un site peu être vu comme des legos. Lors de la construction d’une page, nous empilons les blocks afin d’obtenir le rendu que nous souhaitons. Cette méthode permet de garder un site entièrement configurable par son propriétaire tout en gardant un code propre et entièrement contrôlé (ce qui n’est pas le cas lors de l’utilisation d’un page builder tel que Divi, WP Bakery, etc.).

Pourquoi créer des blocks Gutenberg personnalisés avec ACF ?

Lors de la création d’un site internet, tout le monde n’est pas à l’aise avec les notions d’optimisation du temps de chargement et de référencement naturel. Afin d’obtenir un site optimisé, à la fois pour les moteurs de recherche, et pour les internautes, il y a un certain nombre de paramètres à prendre en compte. L’utilisation de blocks Gutenberg personnalisés permet de garder le contrôle sur le code HTML de la page, permettant ainsi d’avoir un site toujours optimisé pour le référencement naturel avec un minimum de code (et donc un site qui se charge rapidement). Aussi, d’un point de vue graphique, l’utilisation de blocks personnalisés permet de contraindre les modifications possibles et donc d’assurer une cohérence graphique sur l’ensemble du site.

Lors de la création des blocks Gutenberg pour WordPress, de nombreuses tâches sont nécessaires : enregistrer le block, réaliser l’intégration du block, générer les champs configurables et enfin créer l’administration. ACF permet de gagner beaucoup de temps sur différentes de ces tâches et nous permet de nous concentrer sur l’essentiel : répondre au besoin du client.

La création de blocks Gutenberg ACF nécessite la maîtrise de plusieurs langages de programmation : HTML, CSS, PHP et bien souvent Javascript. Mais une fois développé, vous obtenez une mise en forme parfaitement adapté aux usages d’aujourd’hui.

Les avantages des blocks ACF

Avant de rentrer dans le vif du sujet, voici quelques avantages qui vous décideront peut-être à passer à cette méthode pour la création de vos thèmes WordPress sur-mesure.

  • ACF se base uniquement sur PHP : vous n’avez pas besoin de connaître de nombreux langages afin de pouvoir utiliser ACF. Il suffit d’écrire quelques fonctions PHP afin de pouvoir utiliser le plugin. Si vous êtes novice en PHP, ne vous inquiétez pas, le code nécessaire à la création des blocks et très accessibles et compréhensibles même par les personnes ayant un niveau débutant.
  • Une mise en forme simplifiée : c’est sûrement l’un des points les plus important, il est très simple de gérer la mise en forme de votre block. Il vous suffit pour cela de créer un fichier PHP qui sera appelé à chaque rendu du block. Vous gardez ainsi un contrôle total sur le code généré.
  • Compatible avec l’ensemble des champs ACF : si vous avez l’habitude d’utiliser ACF pour ajouter des champs à vos Custom Post Type, sachez que l’ensemble des champs dont vous avez l’habitude sont utilisables dans les blocks Gutenberg.
  • Aperçu en direct : pour les clients, c’est désormais devenu une nécessité, avoir la possibilité de visualiser en direct, directement dans l’espace administration le rendu d’un block. Sachez qu’ACF vous permet de prévisualiser vos modifications directement dans l’édition des pages de WordPress.
  • Et bien d’autre, la liste est longue, nous vous invitons à regarder plus en détail la documentation disponible sur le site d’ACF afin d’en apprendre plus.

Comment créer un block Gutenberg avec ACF ?

Avant de commencer, il est bon de noter que la fonctionnalité « Block » n’est disponible que dans la version Pro d’ACF. Il vous sera donc nécessaire d’acheter une licence afin de pouvoir profiter de cette fonctionnalité. Nous partons du principe que vous possédez une licence pour la suite de ce tutoriel (et que le plugin est installé sur votre WordPress).

Enregistrez votre block dans votre fichier function.php

Lors de la création d’un block Gutenberg avec ACF, la première chose à faire est d’enregistrer le block dans votre code. Vous pouvez intégrer ce code dans votre fichier function.php ou bien dans un fichier de votre choix, tant que celui-ci est exécuté au chargement du thème. Le code ci-dessous présente le code nécessaire à l’enregistrement du block :

add_action('acf/init', 'my_acf_init_block_types');
function my_acf_init_block_types() {

    // On vérifie l'existence de la fonction
    if( function_exists('acf_register_block_type') ) {

        // On enregistre le premier block
        acf_register_block_type(array(
            'name'              => 'mon-block-acf',
            'title'             => __('Mon Block ACF'),
            'description'       => __('Mon premier block ACF.'),
            'render_template'   => 'template-parts/blocks/mon-block-acf/mon-block-acf.php',
            'category'          => 'formatting',
            'icon'              => 'admin-comments',
            'keywords'          => array( 'block', 'acf' ),
        ));
    }
}

Les premières lignes du code permettent d’indiquer à WordPress quand exécuter la fonction. Dans notre cas, nous souhaitons exécuter la fonction lors du chargement d’ACF, soit le hook « acf/init ». Nous ne rentrerons pas dans le détail du code PHP, mais nous allons voir les différents arguments de la fonction acf_register_block_type :

  • name : il s’agit du nom du block, son identifiant. Ce nom sera utilisé dans WordPress.
  • title : il s’agit du titre du block qui sera visible dans l’espace administration, vous devez indiquer un nom correspondant à la fonctionnalité de votre block.
  • description : une description du block qui permet de comprendre son fonctionnement.
  • render_template : il s’agit du fichier PHP qui sera appelé lors du rendu du block, c’est là que vous devez ajouter votre code HTML.
  • category : dans quelle catégorie doit se trouver le block (les catégories sont disponibles dans l’espace administration de WordPress et permettent de mieux organiser les blocks)
  • icon : quelle est l’icône qui doit être affichée dans l’espace administration.
  • keywords : différents mots clés qui permettront de faciliter la recherche du block dans l’espace Administration.

Il est possible d’ajouter d’autres paramètres, vous trouverez l’ensemble des éléments nécessaires pour aller plus loin sur le site officiel d’ACF.

Rendre le block configurable

Désormais, nous allons voir comment ajouter des variables configurables dans notre nouveau block. Pour cela, rendez-vous dans l’espace administration de WordPress et allez dans l’administration du plugin ACF et cliquez sur « Ajouter ». Vous arrivez sur une page vous proposant de créer un nouveau groupe de champs, voici maintenant les étapes à suivre :

  • Dans le champ titre, indiquez le nom que vous souhaitez, vous pouvez par exemple reprendre le titre du Block tel que vous l’avez défini dans le code, cela vous permettra de mieux vous y retrouver lorsque vous aurez de nombreux blocks.
  • Dans le second block « Emplacement », cliquez sur « Type de publication » et sélectionnez « Bloc ».
  • Dans la select de droite, sélectionnez désormais le titre de votre block, dans notre cas : « Mon Block ACF »
  • Il ne vous reste plus qu’a utiliser le bouton « Ajouter un champ » pour ajouter les champs configurables de votre block. Dans votre exemple, nous allons donner la possibilité d’ajouter un titre, une description et une image. Pour voir la liste des champs disponibles et leur fonctionnement, vous pouvez vous rendre sur le site officiel d’ACF.
  • Une fois l’ensemble des actions faites, il vous suffit de cliquer sur « Publier ».
  • Vous avez désormais un block ACF configurable.
Administration Block ACF

Mise en forme de votre block.

Lors de l’étape 1, nous avons renseigné un fichier dans le paramètre « render_template ». C’est ce fichier qui sera exécuté par WordPress lorsque l’utilisateur demandera l’affichage du block. Vous devez donc créer ce fichier dans votre thème WordPress : « template-parts/blocks/mon-block-acf/mon-block-acf.php ».

Sans trop rentrer dans le détail, nous allons voir la structure type d’un fichier, par exemple :

<div class="mon-block-acf">
	<h1><?php echo get_field('titre'); ?></h1>
	<p><?php echo get_field('description'); ?></p>
	<img src="<?php echo get_field('image')['url']; ?>" />
</div>

Dans les faits, nous devrions ajouter des vérifications afin d’être sûr que les valeurs sont définies, mais dans le cadre de l’exemple, nous allons simplifier au maximum. La chose à savoir est que lorsque vous appelez la fonction get_field d’ACF dans votre fichier, celle-ci renvoi la valeur indiquée dans l’espace administration.

Où trouver le block ACF

Maintenant que votre block Gutenberg ACF est prêt, vous pouvez le retrouver dans l’administration des pages lorsque vous souhaitez ajouter un nouvel élément à votre page.

Vous pouvez retrouver le tutoriel officiel à cette adresse : https://www.advancedcustomfields.com/resources/blocks/

Mise à jour 27 mai 2023
Nicolas Trimardeau
Depuis 2004, je parcours le web et fais des tests pour comprendre les algorithmes de Google. Je vous partage mon expérience du SEO et du SEA pour vous aider à exploiter correctement le pouvoir du plus grand moteur de recherche du monde.