Utiliser les champs personnalisés dans les templates HTML

Découvrez comment afficher les informations des champs personnalisés dans les templates HTML, à la fois avec les variables classiques et à l'intérieur des boucles Jinja.

Les champs personnalisés vous permettent de stocker dans Ezus des informations spécifiques à votre compte et à votre façon de travailler.

Vous pouvez afficher ces informations dans un template HTML, mais la syntaxe dépend de l'endroit où vous utilisez le champ personnalisé.

Il existe deux cas principaux :

En dehors d'une boucle : utilisez la variable classique du champ personnalisé disponible dans le Variable Drawer.
À l'intérieur d'une boucle Jinja : récupérez le champ personnalisé depuis les custom_fields de l'objet actuel.

💡 Avant d'ajouter un champ personnalisé à votre template HTML, identifiez l'endroit où le champ est configuré et l'objet auquel il appartient. Un champ personnalisé de projet et un champ personnalisé d'activité n'utilisent pas le même contexte.

1. Trouver le nom technique du champ personnalisé

Les champs personnalisés possèdent un nom technique utilisé pour les identifier dans les templates.

Le nom technique est particulièrement important lorsque vous récupérez un champ personnalisé depuis un objet à l'intérieur d'une boucle Jinja.

Par exemple, imaginez que vous avez un champ personnalisé appelé :

Additional information

avec le nom technique :

additional_information

La valeur que vous devez utiliser dans le HTML est le nom technique, qui n'est pas nécessairement identique au nom visible du champ personnalisé.

💡 Copiez directement le nom technique depuis la configuration du champ personnalisé. Cela permet d'éviter les erreurs liées aux espaces, à la ponctuation ou aux différences entre le nom visible et le nom technique.

2. Utiliser un champ personnalisé en dehors d'une boucle

Lorsque le champ personnalisé est disponible en tant que variable Ezus standard, recherchez-le dans le Variable Drawer.

Dans le HTML, les champs personnalisés classiques utilisent une syntaxe spécifique.

Par exemple, au lieu de :

$$project.{{description}}$$

utilisez :

$$project.__description__$$

Ici, description est le nom technique du champ personnalisé.

Cette syntaxe est utilisée lorsque vous travaillez avec une variable Ezus classique plutôt qu'avec un objet actuel à l'intérieur d'une boucle Jinja.

💡 Si le champ personnalisé est disponible dans le Variable Drawer, copiez-le depuis celui-ci plutôt que de reconstruire la variable manuellement.

3. Utiliser un champ personnalisé à l'intérieur d'une boucle

À l'intérieur d'une boucle Jinja, le champ personnalisé appartient à l'objet actuel.

Par exemple, si vous parcourez des activités :

{% for activity in activities %}   {{ activity.custom_fields.additional_information }} {% endfor %}

Dans cet exemple :

activity est l'activité actuelle dans la boucle.
custom_fields donne accès à ses champs personnalisés.
additional_information est le nom technique du champ personnalisé.

Si chaque activité contient une valeur différente pour Additional information, Ezus récupère la valeur correspondante pour chaque activité au fur et à mesure de la génération de la boucle.

Le même principe s'applique aux autres objets qui donnent accès aux champs personnalisés, notamment :

Steps
Accommodations
Transport
Travellers
Suppliers
Products
Packages

Par exemple, à l'intérieur de la boucle correspondante, la structure suit la même logique :

{{ step.custom_fields.technical_name }} {{ accom.custom_fields.technical_name }} {{ transp.custom_fields.technical_name }} {{ supplier.custom_fields.technical_name }} {{ product.custom_fields.technical_name }}

Remplacez technical_name par le nom technique du champ personnalisé que vous souhaitez afficher.

🔭 Consultez Utiliser les boucles dans les templates HTML pour découvrir comment créer et utiliser du contenu répété.

4. Champs personnalisés avec des caractères spéciaux

Certains noms techniques contiennent des signes de ponctuation ou d'autres caractères spéciaux.

Dans ce cas, la notation avec un point peut ne pas fonctionner correctement.

Au lieu de :

{{ activity.custom_fields.technical_name }}

utilisez des crochets et des guillemets :

{{ activity.custom_fields["technical_name"] }}

Par exemple, si le nom technique est :

_01_-additional-information--_

utilisez :

{{ activity.custom_fields["_01_-additional-information--_"] }}

💡 Si un champ personnalisé ne s'affiche pas alors qu'il contient des informations, vérifiez d'abord son nom technique. S'il contient des signes de ponctuation ou des caractères spéciaux, essayez la notation avec des crochets et des guillemets.

5. Conserver les sauts de ligne dans les champs personnalisés multilignes

Un champ personnalisé peut contenir plusieurs lignes de texte, mais le HTML ne conserve pas nécessairement ces sauts de ligne lors de la génération de la page web.

Si un champ personnalisé multiligne apparaît sous la forme d'une seule ligne continue, utilisez du CSS pour conserver les sauts de ligne.

Par exemple :

white-space: pre-line;

Vous pouvez appliquer cette propriété à l'élément HTML qui affiche le champ personnalisé.

Par exemple :

<p style="white-space: pre-line;">   {{ activity.custom_fields.additional_information }} </p>

Si vous souhaitez également conserver les espaces en plus des sauts de ligne, utilisez :

white-space: pre-wrap;

Vous pouvez également appliquer la règle globalement aux éléments de paragraphe :

<style>   p {     white-space: pre-line;   } </style>

⚠️ Une règle CSS globale s'applique à tous les éléments correspondants du template. Si vous appliquez white-space: pre-line; à tous les éléments <p>, vérifiez l'ensemble de la page web générée afin de vous assurer que les autres paragraphes ne sont pas affectés de manière inattendue.

6. Ajouter un lien cliquable dans un champ personnalisé

Si le contenu d'un champ personnalisé doit inclure un lien cliquable, utilisez un lien HTML :

<a href="https://example.com" target="_blank">Text to show</a>

Par exemple :

<a href="https://example.com" target="_blank">View more information</a>

L'URL doit commencer par :

https://

Cela permet d'ouvrir le lien lorsque le contenu est affiché dans la page web générée.

7. Résoudre les problèmes liés à un champ personnalisé

Si un champ personnalisé ne s'affiche pas correctement, vérifiez les points suivants :

Le champ personnalisé contient-il une valeur ?
Vérifiez les informations sources dans Ezus.
Faites-vous référence au bon objet ?
Un champ personnalisé d'activité doit être récupéré dans le contexte de l'activité, un champ personnalisé de produit dans le contexte du produit, et ainsi de suite.
Le nom technique est-il correct ?
Comparez le nom utilisé dans votre HTML avec le nom technique configuré dans Ezus.
Le nom technique contient-il des caractères spéciaux ?
Si c'est le cas, utilisez la notation avec des crochets :

{{ activity.custom_fields["technical_name"] }}

Utilisez-vous la bonne syntaxe pour le contexte ?
Un champ personnalisé classique provenant du Variable Drawer et un champ personnalisé utilisé à l'intérieur d'une boucle Jinja n'utilisent pas la même syntaxe.
Un champ multiligne a-t-il perdu ses sauts de ligne ?
Utilisez white-space: pre-line; ou white-space: pre-wrap;.

⚠️ Un résultat vide ne signifie pas nécessairement que la syntaxe HTML est incorrecte. Vérifiez que le champ personnalisé est bien renseigné sur l'objet spécifique utilisé pour générer la page web avant de modifier le template.

8. Tester votre champ personnalisé

Après avoir ajouté un champ personnalisé à un template HTML :

Enregistrez le template.
Générez la page web avec un projet dans lequel le champ personnalisé contient des informations.
Vérifiez que la valeur attendue apparaît.
Si le champ personnalisé se trouve dans une boucle, vérifiez plusieurs éléments générés et pas uniquement le premier.
Testez le même template avec un champ personnalisé vide afin de vous assurer que la mise en page environnante fonctionne toujours correctement.
Si le champ contient plusieurs lignes, des caractères spéciaux ou des liens, vérifiez également ces éléments dans la page web générée.

💡 Pour les champs personnalisés à l'intérieur de boucles, effectuez le test avec plusieurs objets contenant des valeurs différentes. Cela permet de vérifier plus facilement que le template récupère bien le champ personnalisé de l'objet actuel, au lieu d'afficher les mêmes informations de manière répétée.