Depuis la version 5.8 d’Advanced Custom Fields (ACF) Pro, vous pouvez utiliser ACF pour créer des blocs Gutenberg personnalisés. Tout ce que vous devez gérer, ce sont les modèles PHP. Cela rend très facile pour les développeurs qui ne sont pas encore expérimentés dans le Javascript moderne requis de créer des blocs personnalisés pour Gutenberg avec l’un des types de champs qu’ACF a à offrir. Gardez à l’esprit que cette fonctionnalité n’est disponible que dans la version payante (Pro) des champs personnalisés avancés. Il n’est pas disponible dans la version gratuite, vous devrez donc acheter une licence.
Si vous êtes un éditeur WordPress ou un webmaster qui ne souhaite pas plonger dans le codage, cet article est définitivement pour vous. Cependant, si vous souhaitez être un développeur de thèmes ou de plugins WordPress, je vous recommande de franchir le pas pour apprendre à créer vos propres blocs personnalisés. Cependant, l’utilisation de champs personnalisés avancés pour créer des blocs peut fournir une bonne introduction à la gestion des blocs personnalisés dans Gutenberg.
Créer un bloc Gutenberg avec ACF
Il y a essentiellement trois étapes simples pour créer un bloc Gutenberg personnalisé avec des champs personnalisés avancés. La première est facile et probablement familière ; configurer les champs (paramètres) que vous souhaitez avoir dans votre bloc. La deuxième étape consiste à utiliser la fonction ACF pour enregistrer un bloc Gutenberg. Et la troisième étape consiste à écrire le modèle PHP pour le bloc. Vous écrivez simplement le code HTML et gérez les paramètres comme vous le feriez avec les champs ACF autrement. Et c’est tout! (D’accord, il y a peut-être une quatrième étape ; styliser votre bloc. Mais je n’entrerai pas dans les détails dans cet article).
Créez vos paramètres / champs
Si vous avez déjà utilisé des champs personnalisés avancés, vous savez probablement comment configurer des champs. Vous pouvez utiliser l’interface utilisateur d’administration du champ personnalisé avancé pour le faire. Ou si vous voulez que les paramètres de bloc soient intégrés dans votre plugin ou votre thème, écrivez les paramètres avec PHP. J’ai un article de référence complet sur la façon d’ajouter des paramètres ACF avec PHP.
La chose essentielle que vous devez faire avec votre groupe est de définir l’emplacement sur "Bloquer". Mais comme nous n’avons pas encore enregistré notre bloc, il sera par défaut sur "Tous". Laissez-le ainsi, enregistrez vos champs et passons à enregistrer notre bloc.
Enregistrer un bloc Gutenberg
Dans le code de votre thème functions.phpou plugin, vous devez écrire une fonction accrochée à acf/initet appeler [acf_register_block](https://www.advancedcustomfields.com/resources/acf_register_block_type/)()pour enregistrer un bloc. Comme cette fonction est assez nouvelle dans ACF et dépend d’un plugin à activer, je vous recommande d’envelopper votre code dans un if-check pour vous assurer que votre thème ou plugin ne plantera pas votre WordPress.
L’enregistrement d’un bloc avec ACF est en fait similaire à la façon dont nous enregistrerions manuellement un bloc Gutenberg personnalisé. Avec ACF, vous devez fournir un nom slugifié unique pour votre bloc name. Je recommande d’utiliser un nom explicite, par exemple ctapour un bloc Appel à l’action, ou author-cardpour un bloc montrant des auteurs ou similaires. Si vous connaissez un peu Gutenberg, vous savez peut-être que tous les blocs doivent être enregistrés avec un espace de noms, un /, puis leur nom de slug. Par exemple, l’espace de noms de WordPress est core, donc par exemple le bloc de paragraphe dans WordPress s’appelle core/paragraph. Avec ACF, l’espace de noms sera acf, donc par exemple le bloc ci-dessus sera enregistré dans Gutenberg en tant que acf/yourblock. Si vous enregistrez vos champs avec PHP, comme vous le verrez plus tard, nous devons nous en souvenir.
Dans categoryvous définissez dans quelle catégorie Gutenberg vous souhaitez que votre bloc apparaisse. Pour le moment, les valeurs possibles sont common, formatting, layout, widgets, ou embed. Si vous créez des catégories Gutenberg personnalisées, vous pouvez les ajouter à celles-ci si vous le souhaitez. Quant à iconfournir n’importe quel nom d’icône de WordPress Dashicons (moins les).
Pour informer ACF comment rendre ce bloc, vous avez deux choix : soit fournir un nom de fonction à la clé render_callback(comme ci-dessus), soit fournir un nom de modèle dans votre thème à la clé render_template. Donc, si vous préférez vous référer directement à un modèle, par exemple template-parts/block-yourblock.phpdans votre thème, faites-le simplement comme ceci et supprimez le render_callback:
Connectez votre groupe de champs à votre bloc enregistré
Lorsque vous êtes satisfait de votre code d’enregistrement de bloc, il est temps de connecter votre bloc aux paramètres que vous avez définis précédemment. Si vous avez créé les champs dans l’administrateur, revenez simplement en arrière et choisissez votre bloc dans Emplacement. Et si vous avez ajouté le groupe de champs avec PHP, à l’emplacement fournissez la valeur ‘ acf/yourblock‘ où yourblockest ce que vous avez fourni comme nameci-dessus.
Ecrire le modèle
La dernière étape, et la plus amusante, consiste à écrire le modèle pour la sortie du bloc !
L’emplacement de votre sortie de rendu de bloc dépend de ce que vous avez décidé d’utiliser dans votre enregistrement de bloc, render_callbackou render_template.
Si vous avez fourni un nom de fonction, render_callbackvous devez définir cette fonction dans le functions.phpcode de votre thème ou plugin. Vous obtenez quatre paramètres pour votre fonction, comme vous le verrez ci-dessous :
Le premier paramètre, $block, contient certaines informations de Gutenberg. Par exemple, chaque bloc Gutenberg aura presque toujours className, que vous devez définir comme classe sur votre wrapper le plus externe. $block['align']pour l’alignement peut également être défini et quelque chose que vous souhaitez également ajouter. Le deuxième paramètre, $content, sera toujours vide avec ACF (cela serait rempli si vous ajoutiez des blocs imbriqués, mais ce n’est pas possible avec ACF). Le booléen $is_previewsera vrai si nous examinons actuellement le rendu du bloc en mode aperçu dans l’éditeur Gutenberg. Et enfin $post_id, le message dans lequel ce bloc est ajouté.
En ce qui concerne les champs, vous récupérez les champs comme vous le feriez normalement, avec get_field(). La sortie HTML dépend entièrement de vous et de la manière dont vous souhaitez générer vos champs.
Si vous avez fourni un fichier de modèle à la render_templateplace, créez simplement le fichier à l’emplacement spécifié dans votre thème. À l’intérieur, vous avez accès aux mêmes variables globales qu’avec la fonction ci-dessus (par exemple $block). Par exemple:
Et c’est tout ce qu’il y a à faire. C’est aussi simple que de créer vos blocs Gutenberg personnalisés avec ACF.
Conclusion
Aussi simple que cela puisse paraître, s’appuyer sur un plugin – en particulier un plugin payant – n’est pas une bonne solution finale si vous souhaitez développer des thèmes ou des plugins. Gardez à l’esprit que vos blocs cesseront de fonctionner si vous déplacez votre code de thème dans un autre WordPress sans ACF Pro. Ou lorsque vos paramètres de champ n’ont pas été configurés (sauf si vous les avez intégrés dans votre code avec PHP ou assurez-vous de les exporter et de les importer). En tant que développeur de thème (ou plugin) qui distribue du code, vous ne pouvez pas vous attendre à ce que chaque utilisateur achète sa propre licence d’ACF Pro afin de faire fonctionner votre thème! Mais c’est une bonne solution temporaire pour ceux qui ne peuvent pas ou n’auront pas besoin de coder.
Si vous êtes convaincu que vous devez franchir le pas et apprendre Javascript et Gutenberg, consultez mon introduction à Gutenberg post ou la catégorie Gutenberg sur ce site pour en savoir plus.