La binding API permet d’intégrer des valeurs dynamiques directement au sein des blocs, ce qui permettra dans certains cas d’éviter une saisie manuelle et fastidieuse d’informations. On va voir comment en tirer parti dans notre site.
Sommaire du cours
Imaginez que vous avez un blog de jeux-vidéo et que vous souhaitez tester des jeux, et leur donner une note, un peu comme le font IGN et JV.com.
Vous pourriez indiquer cette note directement dans un bloc de votre page, mais ce serait une information statique parmi d’autres.
Si demain vous voulez créer une boucle de requête personnalisée sur la page d’accueil pour afficher les meilleurs jeux-vidéo du moment, vous seriez bloqué.
Dans les standards de WordPress, l’idéal serait donc de stocker la note dans les metadonnées de l’article : la donnée serait alors stockée dans la table wp_postmeta et serait requetable lors d’une WP Query.
Et grâce à la Block Bindings API de WordPress, introduit avec la version 6.5, vous allez pouvoir récupérer automatiquement cette donnée et l’injecter dans un bloc de votre page ou de votre modèle.
Et il y a deux façons de faire : soit on utilise les champs personnalisés natifs de WordPress, qui souffrent d’une interface très rudimentaire, soit on utilise toute la puissance d’ACF et de son interface ergonomique et sexy.
On va justement voir les 2 approches dans la suite de ce cours.
On va même voir ensuite comment connecter un bloc à une source de données personnalisée en créant notre propre fonction.
Activer les champs personnalisés de WordPress
Afin de bien comprendre le fonctionnement du Block Bindings, on va commencer par un exemple tout simple en utilisant les champs personnalisés natifs de WordPress.
Vidéo premium
Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?
Bien sûr, dans un vrai projet client, je vous recommanderai plutôt d’utiliser les champs ACF (en version gratuite ou pro). C’est ce qu’on va voir dans la suite du cours.
Pour l’instant, on va avoir besoin d’activer l’interface des champs personnalisés de WordPress dans Gutenberg. Pour cela, cliquez sur le menu 3 points en haut à droite de l’interface, puis sélectionnez « Préférences » :
Sous l’onglet « Général », activez « Champs personnalisés ». Vous allez devoir ensuite recharger la page.
L’interface des champs devrait ensuite apparaître en bas de l’éditeur de blocs :
Comme vous pouvez le constater, elle n’est pas très engageante. Après tout, elle n’a pas bougé depuis son introduction il y a de ça de nombreuses années.
Activer les champs personnalisés dans un Custom Post Type
Si vous souhaitez faire la même chose dans un Custom Post Type (par exemple le Portfolio), il faudra ajouter une instruction dans la déclaration du type de publication personnalisé :
Dans supports, il faudra simplement ajouter custom-fields. Et là, vous pourrez activer les champs personnalisés pour ce CPT également.
Le Block Binding avec les post metas
Commençons par mettre en place le Block Binding avec les champs personnalisés natifs de WordPress.
Vidéo premium
Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?
Et pour cela on va passer par plusieurs étapes :
- On va commencer par déclarer les metas dans l’API REST de WordPress ;
- On va ensuite insérer les blocs en vue de les connecter aux données ;
- Après, on va connecter les blocs aux metadonnées ;
- Enfin, on insérera nos données dans les champs personnalisés.
Lorsqu’on enregistrera la page, les données des meta seront automatiquement reportées dans notre contenu.
Pour illustrer le Block Binding, l’objectif de ce cours va être d’ajouter 2 informations dynamiques dans les articles du blog, à savoir la distance et le dénivelé de chacune de nos balades. Et ça ressemblera à ceci :
Allez, on va maintenant mettre ça en place.
Déclarer les meta dans l’API REST
Avant de pouvoir utiliser nos metas dans les blocs, il va falloir déclarer à WordPress lesquelles on va vouloir utiliser, au travers du functions.php.
Cette déclaration va surtout servir à ajouter la meta dans l’API REST de WordPress, afin que Gutenberg puisse recevoir la donnée et l’injecter dans un bloc.
Ce n’est pas très compliqué, on va utiliser la fonction register_meta() dans le hook init.
Le premier paramètre indique le type de publication visé, et le second le slug que vous allez donner à votre metadonnée.
Le paramètre show_in_rest va être primordial ici, et il doit impérativement rester à true pour que la manipulation fonctionne.
Vous allez également pouvoir indiquer une valeur par défaut, ainsi qu’un libellé qui sera affiché dans l’inspecteur de Gutenberg.
Préparer le contenu
Maintenant, on va aller dans un article et on va insérer quelques blocs pour préparer nos contenus dynamiques.
Mon exemple est le suivant : on va ajouter un bloc rose après le contenu de l’article pour afficher la distance d’une randonnée, ainsi que son dénivelé.
J’ai créé une rangée à fond rose avec une répartition des blocs. À l’intérieur, j’ai mis 2 autres rangées qui contiennent chacune 2 paragraphes : un pour le libellé de l’élément (Distance et Dénivelé), et un paragraphe vide qui accueillera la donnée dynamique.
En effet, un bloc doit être dédié à l’affichage de votre donnée dynamique, il ne doit donc contenir rien d’autre, d’où le fait de mettre 2 paragraphes côte à côte en rangée.
Déclarer le binding dans le HTML
On va maintenant connecter nos paragraphes vides aux sources de données, c’est là qu’opère la magie du Block Binding.
En cliquant sur le paragraphe concerné, vous verrez dans l’inspecteur à droite une section « Attributs ». C’est ici que l’on va pouvoir connecter notre donnée dynamique.
Dans le paragraphe, seul l’attribut content est connectable. On va donc connecter le paragraphe de gauche à ma donnée Distance, et celui de droite à ma donnée Dénivelé.
Cliquez ensuite sur le menu 3 points en haut à droite de Gutenberg et sélectionnez « Éditeur de code ».
Localisez vos deux paragraphes « Bindés ». Sur le premier, vous devriez voir ceci :
Ce que WordPress a fait ici, c’est d’ajouter au commentaire du bloc une donnée JSON dans metadata > bindings.
Pour le bloc paragraphe, c’est dans l’attribut content que l’on va injecter notre meta.
WordPress a ensuite indiqué la source de données : on veut récupérer une métadonnée de l’article. C’est pour cela qu’il indique core/post-meta dans source. Pour ACF, on mettra une source différente justement. Enfin, il indique l’identifiant de notre meta via key.
Vous verrez la même chose pour le dénivelé, mais cette fois avec la key égale à elevation.
Pour connecter des données à une image, c’est un peu différent . Vous allez pouvoir connecter une source pour l’URL et une autre source pour le texte alternatif.
Mais revenons-en à notre meta.
Repassez en mode visuel et enregistrez votre article. Si tout s’est bien passé, vous devriez voir apparaître les valeurs par défaut précédemment définies dans register_meta().
Ok, notre binding est opérationnel ! Il ne nous reste plus qu’une étape.
Insérer les données dans les champs personnalisés
Pour terminer, on va simplement devoir ajouter nos meta dans l’interface des champs personnalisés.
Pour cela, vous devriez voir cette interface :
Cliquez sur le bouton « Saisissez-en un nouveau » et indiquez dans « Nom » le slug de votre meta, d’abord distance, et indiquez une valeur, par exemple 16 Km.
Validez puis ajoutez un nouveau champ, en indiquant comme nom elevation cette fois. Vous devriez avoir ceci dans les champs personnalisés en bas de l’écran :
Enregistrez l’article. Vous devriez maintenant voir apparaître vos valeurs dans le bloc rose. Elles ont été injectées automatiquement par Gutenberg.
Félicitations, le Block Binding est opérationnel !
Essayez maintenant de sélectionner l’un des deux paragraphes connectés, il devrait apparaître en violet pour indiquer que c’est une source dynamique.
Déplacer les champs liés dans les modèles de page
Pour que cette manipulation ait un sens, on va déplacer notre bloc dans un modèle de page, dans notre cas, le modèle de publication single.html.
Sinon, il faudrait refaire ce bloc pour chaque article, ce qui ne présenterait pas d’intérêt.
Le but ici va être de copier tout le groupe et on va l’insérer juste après la balise de contenu dynamique :
Mais cette fois, on ne verra plus apparaître le résultat dans Gutenberg, car par défaut, il n’affiche pas le modèle en entier lors de l’édition.
Affichez-le en cliquant sur « Modèle » puis sur « Afficher le modèle ».
Vous devriez voir à nouveau le bloc avec les données connectées :
Par contre, au moment où j’écris ces lignes (avec WordPress 6.7) lorsque j’affiche le modèle, l’interface des champs personnalisés disparaît. C’est probablement un bug.
Beaucoup de boulot pour pas grand chose n’est-ce pas ? Pour rendre ça un peu plus sexy, on va connecter nos données à des champs ACF dans la suite de ce cours afin de profiter de l’interface des champs d’ACF.
Le bloc binding avec les champs ACF
Pour avoir des groupes de champs bien plus ergonomiques, on va refaire le même exemple mais cette fois avec des champs ACF.
Vidéo premium
Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?
Pour commencer, on va télécharger et installer l’extension. La version gratuite suffira. Si vous ne connaissez pas encore ACF, j’ai toute une formation pour vous :
Pour cet exemple on va imaginer deux nouvelles données dynamiques à afficher dans nos articles : le prix d’un voyage présenté sur le blog, et sa durée en jours.
Cette fois, on n’aura pas besoin de register_meta() car c’est ACF qui va gérer la déclaration de nos valeurs.
On va ensuite aller ajouter un nouveau groupe de champs via le menu ACF de l’administration.
Cliquez sur « + Ajouter » pour déclarer un nouveau groupe. Ajoutez 2 champs de type « Texte » :
Dans le premier champ dédié au prix, mettez « Prix » dans le libellé et price dans le nom du champ (qui est en fait le slug).
Faites pareil pour le second champ, mais indiquez cette fois « Durée » dans le libellé et duration dans le nom.
Dans l’onglet « Présentation » de chaque champ, activez l’option « Autoriser l’accès à la valeur dans l’interface de l’éditeur ».
En bas de page, vérifiez que le groupe de champs est bien assigné au type de publication « Article » (c’est le cas par défaut).
Allez dans l’onglet « Réglages du groupe » et activez « Afficher dans l’API REST ». Cela permettra à l’éditeur d’accéder aux champs via l’API REST de WordPress.
Publiez votre groupe de champs, puis rendez-vous ensuite dans un article. Votre groupe de champs devrait apparaître en bas de l’écran. Saisissez des valeurs dans chacun des champs :
D’ailleurs, depuis que ACF a été activé, il a désactivé automatiquement l’interface native des champs personnalisés.
Ajoutez 2 paragraphes vides dans le but de les connecter aux champs ACF.
Modifiez ensuite le HTML, pour ajouter les informations de binding. Cette fois dans l’attribut source, vous écrirez acf/field au lieu de core/post-meta.
Lorsque vous reviendrez en mode « Éditeur visuel », vous devriez voir les mentions « Champ ACF » apparaître dans les paragraphes connectés.
Comme pour l’exemple précédent, je vous recommande plutôt de placer le HTML correspondant à votre binding dans un fichier de modèle. Dans notre cas : single.html.
Sauvegardez votre article, et affichez-le en front. Les nouvelles valeurs devraient bien s’afficher.
En résumé, si vous souhaitez uniquement utiliser ACF, la procédure sera la suivante :
- Ajoutez un groupe de champs via l’interface d’ACF ;
- Pour chaque champ, activez « Autoriser l’accès à la valeur dans l’interface de l’éditeur » ;
- Activez « Afficher dans l’API REST » dans les réglages du groupe de champs ;
- Ajoutez des blocs dans votre modèle en vue de les connecter aux données ;
- Enfin, connectez les blocs aux données d’ACF via les commentaires HTML ;
Il ne vous reste plus qu’à saisir vos données via les champs ACF, et elles apparaîtront automatiquement dans vos contenus !
Vous pouvez imaginer plein d’usages avec la Block Bindings API. Comment l’utiliserez-vous ? N’hésitez pas à me dire comment sur le Slack Capitaine WP.
Créer une source de données personnalisée
Pour terminer, on va maintenant créer notre propre source de données. Ainsi, on aura un meilleur contrôle sur le contenu à afficher dans notre bloc.
Vidéo premium
Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?
On pourrait faire plein de choses comme :
- Récupérer tout type d’information native à WordPress ;
- Aller chercher des informations dans une table custom de la base de données ;
- Et même pourquoi pas aller chercher des données externes via une API REST.
Dans les deux exemples qui vont suivre, je vais simplement :
- Récupérer le nombre de commentaires de l’article car il n’existe à ce jour aucun bloc pour afficher ce nombre autre part que dans le titre du bloc « Commentaires » ;
- Récupérer le lien d’un article pour le mettre dans un bouton dans la « Boucle de requête », car si vous vous souvenez, jusque là on ne pouvait mettre qu’un lien.
Pour ce faire, on va avoir besoin de 2 petites étapes :
- Tout d’abord déclarer notre source de données personnalisée en PHP ;
- Et ensuite assigner cette source à un bloc compatible dans notre HTML.
Déclarer nos sources de données personnalisées
La création des sources de données va se faire du côté du functions.php :
Dans le premier hook, j’utilise la fonction register_block_bindings_source() pour déclarer une nouvelle source de données.
Je les appellent capitaine/comments-number et capitaine/permalink. Commencez toujours par un préfixe séparé du nom avec un slash afin de la distinguer d’éventuelles autres sources déclarées par des extensions.
Dans get_value_callback, j’indique le nom de la fonction à appeler lorsque la source de données sera trouvée dans la page.
Dans ma fonction capitaine_comments_binding(), je vais simplement retourner le texte à afficher via la fonction get_comments_number_text() de WordPress qui me renvoie le nombre de commentaires publiés dans l’article.
Je fais pareil dans capitaine_permalink_binding() où j’appelle get_permalink(). Comme on utilisera le binding dans une boucle de requête, cette dernière sera automatiquement reliée à l’article en cours.
Assigner la source à un bloc en HTML
Maintenant, je vais retourner dans mon modèle single.html et je vais ajouter un paragraphe vide à côté de l’auteur et de la date de publication.
Je vais ensuite passer en mode code et assigner ma source de données :
Contrairement aux précédents exemples :
- Indiquez dans
sourcevotre sourcecapitaine/comments-number; - Vous n’avez pas besoin de définir de
keypour une source simple.
Enregistrez votre modèle. Allez en front et observez le résultat :
Et voilà, le nombre de commentaires apparaît en haut de mon article. Au final, c’est plutôt simple à mettre en place et ça nous ouvre pas mal de possibilités.
Du côté de la « Boucle de requête », on va faire de même dans notre composition post-grid.php par exemple, mais cette fois au lieu d’attribuer le lien au content du paragraphe, on va assigner le bindings à l’attribut url du bouton.
Le bouton possède d’ailleurs 4 attributs : url, text, linkTarget, et rel ! Mais je vous reparle de ça juste après.
Voici du coup le résultat une fois la composition appliquée dans le modèle home.html par exemple :
J’y vois un usage qui me sera pratique pour Capitaine WP : mes formations sont liées aux produits WooCommerce grâce à un champ « Relation » d’ACF. Je pourrais donc facilement récupérer le prix du produit attaché via la relation pour l’afficher ensuite sur chaque formation de ma liste des formations !
Aller plus loin avec les sources de données personnalisées
On peut aller encore plus loin grâce aux sources personnalisées.
Vidéo premium
Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?
La fonction de callback renvoie 3 données intéressantes, mais nous n’en avons utilisé aucune tout à l’heure.
Faites un petit var_dump() des familles pour voir ce que nous retourne WordPress.
$source_attrsnous renvoie les paramètres de notre binding HTML, comme la clé ;$block_instancenous renvoie toutes les informations du bloc ciblé par le binding ;$attribute_namenous renvoie l’attribut sur lequel est connecté le binding.
Concernant le premier paramètre, cela vous permettrait d’insérer des arguments dans votre HTML et les récupérer en PHP :
Côté PHP, vous les récupéreriez de cette manière :
Le second argument permet de tout savoir sur le bloc ciblé. Vous pourriez ainsi vérifier que votre bloc est bien un paragraphe ou une image par exemple.
Enfin, le troisième argument permet de savoir à quel attribut du bloc la donnée a été attachée. Dans le cas d’un paragraphe, c’est content. Pour une image, ça peut être url ou alt par exemple.
Vous pourriez donc connecter une seule source de données à plusieurs blocs et agir en fonction du bloc et de l’attribut récupérés en paramètres.
Avec toutes ces informations, vos possibilités sont quasiment illimitées ! Cela dit, la Block Bindings API n’est pas encore parfaite et il existe tout de même quelques limitations à son usage.
Les limites de la Block bindings API
Mais la question qu’on se pose à ce point, c’est est-ce que le Block Bindings est vraiment pratique ? Car on nous a promis une interface graphique pour gérer ça, mais ce n’est toujours pas arrivé dans le cœur de WordPress.
Vidéo premium
Cette vidéo est réservée aux détenteurs de l’offre premium.
Envie de nous rejoindre ?
Voici les problèmes que je vois pour l’instant :
- Il n’y a pas d’interface pour configurer la connexion d’une source custom ;
- Il faut modifier le code HTML de la page à la main pour attacher une donnée ;
- Les données dans la page ne se mettent pas à jour en temps réel ;
- C’est limité à quelques blocs basiques pour le moment ;
- On ne pourra pas faire de logique conditionnelle si la valeur n’est pas présente.
L’interface utilisateur devrait toutefois arriver dans les prochaines versions de WordPress. On remarque des évolutions en ce sens à chaque nouvelle release.
Concernant les blocs compatibles, comme l’indique la documentation WordPress, pour le moment seuls 4 blocs sont compatibles.
| Blocs compatibles | Attributs disponibles |
|---|---|
| Image | url, alt, title |
| Paragraphe | content |
| Titre | content |
| Bouton | url, text, linkTarget, rel |
Mais c’est déjà bien au final. On va déjà pouvoir faire pas mal de choses rien qu’avec ces quelques blocs.
Le dernier souci, c’est que si vous avez besoin d’aller un peu plus loin et appliquer de la logique conditionnelle, ce ne sera pas possible.
Pour reprendre notre bloc rose de tout à l’heure, il pourrait être intéressant qu’il apparaisse uniquement si la distance ou le dénivelé ont été saisis.
Dans ce cas, privilégiez la création de blocs sur-mesure avec ACF. C’est plus simple, plus rapide et surtout plus fiable.
Finalement, le Blocks Bindings est une manière d’afficher des informations dynamiques plus élégante que les shortcodes, que vous pouvez désormais définitivement oublier.
Le bloc binding est très pratique car il est facile à mettre en place et il nous évitera de créer des blocs sur-mesure dans bien des cas.
Dans le prochain cours, on va voir comment hooker les blocs natifs de WordPress pour ajouter des paramètres, ce qui nous évite là aussi de créer des blocs sur-mesure.
0
Questions, réponses et commentaires