Les hooks du Divi Builder : et_builder_ready et le traitement des champs

Personnaliser un site construit avec Divi se heurte rapidement à une limite : les modules du constructeur produisent leur propre balisage, et modifier ce balisage sans toucher aux fichiers du thème demande de passer par les points d'accroche que l'extension expose. Ces points existent, ils sont nombreux, et leur documentation officielle reste sommaire. La conséquence est que beaucoup d'interventions se font en modifiant directement les fichiers du thème, avec la certitude de perdre le travail à la première mise à jour. Nous présentons ici les points d'accroche les plus utiles, le moment exact où ils se déclenchent et la façon de les employer dans un thème enfant.

Comprendre le cycle de vie du constructeur

Le constructeur fonctionne en deux temps distincts, et confondre ces deux temps explique la plupart des échecs de personnalisation. Le mécanisme général des points d'accroche dans cet environnement est présenté dans notre article sur les actions et les hooks.

L'enregistrement des modules

Au chargement de la page d'administration ou du site public, l'extension enregistre l'ensemble de ses modules et leurs champs. Cette phase se produit très tôt et elle constitue le moment où un module personnalisé doit être déclaré. Intervenir plus tard signifie que le module n'existera pas pour le constructeur. Un point d'accroche dédié signale la fin de cette phase et il constitue l'emplacement approprié pour toute déclaration. Se brancher trop tôt produit une erreur, les classes de base n'étant pas encore chargées. Ce timing est la première difficulté rencontrée par ceux qui abordent le sujet.

Le traitement des champs saisis

Lorsqu'une page est affichée, le contenu enregistré est analysé pour en extraire les modules et leurs paramètres. Un point d'accroche permet d'intervenir sur ces paramètres avant leur exploitation, ce qui ouvre la possibilité de modifier une valeur sans toucher au contenu enregistré. Cette intervention convient bien aux corrections globales, comme forcer un réglage sur toutes les instances d'un module. Elle s'applique à chaque module rencontré, ce qui impose de vérifier le type avant d'agir. Une modification appliquée à tous les modules produit des effets inattendus. Le filtrage sur le type est donc systématique.

La production du balisage

Chaque module produit ensuite son code, et un point d'accroche permet de le transformer avant son envoi au navigateur. C'est l'emplacement adapté pour ajouter une classe, envelopper le contenu ou insérer un élément. Manipuler du balisage sous forme de chaîne reste fragile et il constitue souvent la seule voie disponible. Utiliser une expression suffisamment spécifique évite les remplacements accidentels. Cette technique doit rester exceptionnelle et elle rend de grands services sur les cas simples. Elle survit aux mises à jour tant que la structure produite ne change pas.

L'initialisation du constructeur visuel

Dans l'interface d'édition, le constructeur est une application qui se charge dans le navigateur. Un événement signale qu'il est prêt et que l'on peut interagir avec lui depuis un script. Ce point est indispensable pour toute personnalisation de l'interface d'édition, un script exécuté trop tôt ne trouvant rien. Il permet par exemple de masquer des options, de préremplir des champs ou d'ajouter un contrôle. Ces interventions restent limitées et fragiles, l'interface évoluant d'une version à l'autre. Elles doivent être vérifiées après chaque mise à jour majeure.

Les feuilles de style générées

Le constructeur produit une feuille de style spécifique à chaque page, contenant les réglages visuels saisis. Cette génération intervient tard et elle peut être filtrée pour ajouter ou modifier des règles. Cette possibilité est méconnue et elle évite d'ajouter une feuille supplémentaire, avec les problèmes de priorité que cela entraîne. Elle convient aux ajustements dépendant du contenu de la page. Pour des styles constants, une feuille du thème enfant reste plus simple. Le choix dépend donc de la nature du besoin.

Le cache du constructeur

Divi conserve en cache le résultat de plusieurs traitements, ce qui produit un effet déroutant : une modification de code semble sans effet jusqu'à ce que le cache soit vidé. Ce comportement fait perdre un temps considérable à qui l'ignore. Vider le cache du constructeur depuis les réglages, ou désactiver temporairement ce cache pendant le développement, évite cette confusion. Les interactions avec les extensions de cache externes ajoutent une couche supplémentaire, comme le détaille notre article sur les réglages de cache compatibles avec le Visual Builder. Ce point doit être vérifié avant tout diagnostic.

Les interventions les plus utiles

Quelques besoins reviennent constamment et se traitent proprement avec les points d'accroche disponibles.

Ajouter une classe à un module

Le besoin le plus fréquent consiste à marquer certains modules pour les cibler ensuite en style. Le champ de classe personnalisée disponible dans l'interface répond au cas ponctuel, et une intervention par code convient mieux lorsque la règle est systématique. Le filtre sur le balisage produit permet d'ajouter la classe selon des conditions, comme le type de page ou la position du module. Cette approche évite de demander aux rédacteurs de saisir une classe à chaque fois. Elle garantit la cohérence sur l'ensemble du site. Elle demande une dizaine de lignes.

Forcer un réglage par défaut

Modifier les valeurs par défaut d'un module s'obtient en filtrant les champs avant leur traitement. Cette technique permet par exemple d'imposer une taille de police ou un espacement conforme à la charte, sans compter sur la discipline des contributeurs. Les modules déjà créés conservent leurs valeurs enregistrées, seul le comportement des nouveaux étant affecté. Cette distinction doit être expliquée aux équipes, faute de quoi le résultat paraît incohérent. Une reprise des modules existants demande une intervention en base. Elle mérite d'être évaluée avant de généraliser la règle.

Restreindre les options offertes

Sur un site où plusieurs personnes éditent, limiter les options disponibles évite les dérives de mise en page. Certaines options se masquent par un filtre côté serveur, d'autres uniquement par un script agissant après l'initialisation de l'interface. Cette seconde méthode est fragile et elle rend service en pratique. Elle doit être combinée à une véritable restriction de droits lorsque l'enjeu est réel, un masquage visuel n'empêchant rien. Cette distinction entre confort et contrôle reste valable ici comme ailleurs. Elle détermine la solution appropriée.

Injecter du contenu dynamique

Afficher une donnée calculée dans un module texte, comme un prix ou un décompte, se traite par un filtre sur le contenu produit. Un marqueur placé dans le texte par le rédacteur est remplacé par la valeur au moment de l'affichage. Cette technique donne une grande souplesse et elle suppose de documenter les marqueurs disponibles. Elle doit prévoir le cas où la donnée n'existe pas, sous peine d'afficher un marqueur brut aux visiteurs. Un filtrage de sécurité sur la valeur insérée reste indispensable. Ce mécanisme se code en quelques dizaines de lignes.

Créer un module personnalisé

Lorsque le besoin dépasse l'ajustement, déclarer un module complet reste possible en étendant la classe de base fournie. Le module apparaît alors dans l'interface avec ses propres champs et son propre rendu. Cette voie est la plus propre et elle demande un investissement initial de quelques jours pour comprendre la structure attendue. Elle produit un résultat maintenable et pleinement intégré. Elle se justifie dès qu'un même besoin se répète sur plusieurs projets. Sur un besoin unique, un module texte accompagné d'un traitement suffit généralement.

Intervenir sur les modèles

Les modèles construits avec le constructeur de thème obéissent aux mêmes mécanismes, avec des conditions d'affichage propres. Leur fonctionnement d'ensemble est détaillé dans notre article constituant un guide complet du Theme Builder de Divi. Les points d'accroche présentés ici s'appliquent également aux modules placés dans ces modèles. Il faut simplement tenir compte du contexte, un module dans un modèle d'archive ne disposant pas des mêmes données qu'un module dans un article. Cette différence produit des erreurs difficiles à diagnostiquer. La vérifier explicitement fait gagner du temps.

Diagnostiquer quand rien ne se passe

La situation la plus fréquente en abordant ces points d'accroche est celle où le code semble n'avoir aucun effet, sans erreur ni message.

Vérifier que le code est bien chargé

La première hypothèse à écarter est la plus banale : le fichier n'est pas inclus, le thème enfant n'est pas activé, ou une erreur de syntaxe empêche son exécution. Placer une écriture dans le journal en tout début de fichier confirme immédiatement le chargement. Cette vérification élémentaire évite des heures de recherche sur un code parfaitement correct qui n'était simplement jamais exécuté. Elle doit être le premier réflexe, avant toute lecture attentive du code. Elle prend trente secondes. Le nombre de diagnostics qu'elle abrège est considérable.

Contrôler le moment d'accroche

Un filtre déclaré après le déclenchement de l'événement visé ne s'exécutera jamais. Ce cas se produit lorsque le code est placé dans un fichier chargé tardivement, ou branché sur un événement qui survient trop tard. Journaliser le moment d'exécution de chaque étape permet de reconstituer l'ordre réel. Cet ordre diffère parfois de ce que la documentation laisse entendre, notamment lorsque des extensions modifient les priorités. La priorité déclarée sur l'accroche offre un levier de réglage. Une valeur élevée place l'exécution après celle des autres intervenants.

Vérifier le nom exact du point d'accroche

Les noms internes évoluent d'une version à l'autre, et un point d'accroche renommé cesse silencieusement de fonctionner. Une recherche du nom dans les fichiers de l'extension confirme son existence dans la version installée. Cette vérification prend deux minutes avec un outil de recherche dans le code. Elle constitue le contrôle à mener en priorité lorsqu'une personnalisation cesse de fonctionner après une mise à jour. Elle révèle également les points d'accroche voisins qui pourraient convenir. La lecture du code de l'extension reste la documentation la plus fiable disponible.

Écarter le cache

Le cache du constructeur, celui d'une extension de performance et celui du navigateur peuvent chacun masquer l'effet d'une modification. Le contrôle consiste à vider les trois et à tester en navigation privée. Cette étape doit précéder toute conclusion sur l'inefficacité d'un code. Elle est régulièrement omise et elle explique une part notable des faux diagnostics. Désactiver temporairement les caches pendant la phase de développement supprime le problème à la racine. Cette désactivation doit évidemment être annulée avant la mise en production.

Observer ce que reçoit le filtre

Un filtre reçoit des données dont la structure n'est pas toujours celle que l'on imagine. Journaliser le contenu reçu, sur une seule exécution, révèle immédiatement la forme réelle. Cette observation vaut mieux que toute supposition, la structure interne n'étant pas documentée. Il faut prendre soin de limiter cette journalisation, un filtre appelé cent fois par page produisant un journal illisible. Une condition sur le type de module suffit à cibler l'observation. Cette technique est la plus efficace pour comprendre un mécanisme non documenté.

Isoler dans un environnement propre

Lorsque rien ne fonctionne malgré ces contrôles, une installation neuve avec le thème et le code seuls permet de savoir si une autre extension interfère. Ce test tranche entre un problème de code et un conflit. Il demande vingt minutes avec un environnement conteneurisé et bien davantage sans. La réponse oriente complètement la suite de l'investigation. Ce réflexe est celui qui distingue un diagnostic méthodique d'une succession d'essais. Il mérite d'être adopté tôt plutôt que tard dans la recherche.

Travailler proprement

Quelques règles évitent que ces personnalisations ne deviennent un fardeau à la première mise à jour.

Toujours passer par un thème enfant

Aucune modification ne doit être écrite dans les fichiers du thème parent, qui seront écrasés à la prochaine mise à jour. Le thème enfant se crée en quelques minutes et il constitue le seul emplacement acceptable. Ses fichiers doivent être versionnés, au même titre que le reste du code du projet. Cette règle est connue et elle continue d'être violée régulièrement, souvent pour une modification jugée provisoire. Ces modifications provisoires sont celles qui disparaissent le plus douloureusement. Il n'existe aucune bonne raison d'y déroger.

Vérifier l'existence avant d'appeler

Les classes et fonctions de l'extension ne sont pas toujours disponibles, notamment si le thème est désactivé ou en cours de mise à jour. Un appel à une fonction inexistante produit une erreur fatale et un site blanc. Vérifier l'existence de la fonction ou de la classe avant de l'utiliser transforme cette panne en simple absence de fonctionnalité. Cette précaution tient en une ligne et elle évite une indisponibilité complète. Elle doit être systématique sur tout code dépendant d'une extension tierce. Elle vaut particulièrement dans cet environnement où les noms internes changent d'une version à l'autre.

Documenter chaque intervention

Un commentaire indiquant l'objectif, la version de l'extension au moment de l'écriture et le comportement attendu permet de reprendre le code plus tard. Sans cette trace, une intervention devenue inutile sera conservée indéfiniment par prudence. Ce commentaire tient en trois lignes et il change la maintenabilité du projet. Il facilite également le travail d'un autre prestataire. Cette discipline vaut pour toute personnalisation, elle est particulièrement utile ici en raison de la documentation officielle limitée. Elle constitue en pratique la documentation du projet.

Tester après chaque mise à jour

Les points d'accroche non documentés peuvent disparaître ou changer de signature sans avertissement. Une liste des personnalisations en place, avec la page à vérifier pour chacune, transforme ce contrôle en une routine de dix minutes. Effectuer ce contrôle sur un environnement de test avant de mettre à jour la production évite les mauvaises surprises. Cette pratique est particulièrement recommandée sur les mises à jour majeures. Elle demande de disposer d'un environnement de copie, investissement modeste au regard du risque. Elle constitue la contrepartie de toute personnalisation avancée.

Préférer le style au code

Beaucoup de besoins présentés comme nécessitant du code se traitent en réalité par une simple règle de style. Ajouter une feuille dans le thème enfant est plus robuste, plus simple à diagnostiquer et sans risque de casse fonctionnelle. La question à se poser avant toute intervention par code est donc : le résultat visé est-il purement visuel. Une réponse positive oriente vers le style. Cette hiérarchie économise beaucoup de complexité inutile. Elle est fréquemment ignorée par réflexe technique.

Mesurer l'effet sur les performances

Un filtre appliqué à chaque module d'une page riche s'exécute des dizaines de fois par affichage. Un traitement coûteux à cet endroit dégrade sensiblement le temps de réponse. Les opérations lourdes doivent être mises en cache ou déplacées hors de la boucle d'affichage. Mesurer le temps de génération avant et après l'ajout d'un filtre prend deux minutes. Cette vérification est rarement faite et elle révèle parfois un coût inattendu. Sur un site déjà lourd, chaque milliseconde compte. La mesure se prend sur une page représentative et non sur la page d'accueil, généralement mise en cache et donc peu sensible aux traitements ajoutés à la génération.