HTML Field in Odoo: Complete Developer and Business Guide

Introduction

Lorsque vous regardez une description de produit dans une boutique e-commerce Odoo, le texte formaté avec des titres en gras, des points de balle et des images est alimenté par un seul type de champ : le champ Html. C'est l'un des champs les plus polyvalents du modèle de données Odoo, et il apparaît dans plus d'endroits que la plupart des utilisateurs ne le réalisent.

Contrairement à un champ de texte simple qui stocke des chaînes simples, le champ Html stocke du contenu riche avec un formatage complet. Cela le rend essentiel partout où les utilisateurs ont besoin d'écrire du texte structuré ou stylisé, que ce soit une description de produit, un modèle d'email, une note interne ou une section de site web.

Ce guide couvre ce qu'est le champ Html, comment il fonctionne dans l'ORM Odoo et la base de données, où il est utilisé dans des flux de travail commerciaux réels, et comment le créer ou le personnaliser en utilisant Odoo Studio ou du code Python. Nous abordons également les erreurs les plus courantes que les gens commettent lorsqu'ils travaillent avec ce type de champ.

Qu'est-ce que le champ Html dans Odoo

Dans l'ORM Odoo, le champ Html est conçu pour stocker du contenu HTML formaté. Il correspond à une colonne TEXT dans PostgreSQL, et la valeur stockée est une chaîne HTML. Odoo gère automatiquement le rendu et la désinfection, donc ce que les utilisateurs voient dans l'interface est un éditeur de texte riche entièrement formaté, et non du code HTML brut.

Du point de vue de l'utilisateur, un champ Html apparaît comme un éditeur WYSIWYG (Ce que vous voyez est ce que vous obtenez). Les utilisateurs peuvent appliquer du gras, de l'italique, des titres, des listes, des liens, des tableaux, et même insérer des images directement dans le champ. Le résultat est enregistré sous forme de HTML structuré en arrière-plan.

Voici à quoi ressemble le champ dans une définition de modèle Python :

from odoo import fields, models

class ProductTemplate(models.Model):
    _inherit = 'product.template'

    x_technical_specs = fields.Html(
        string='Spécifications Techniques',
        sanitize=True,
        sanitize_tags=True,
    )

Le paramètre string définit l'étiquette visible. Le paramètre sanitize contrôle si Odoo supprime le HTML potentiellement dangereux avant d'enregistrer la valeur. Cela est important pour des raisons de sécurité et est activé par défaut.

Dans Odoo Studio, ce type de champ est appelé Html ou Texte Riche. Lorsqu'il est créé via Studio, il obtient un préfixe x_studio_. Lorsqu'il est défini en Python ou via l'API XML-RPC, vous choisissez vous-même le nom technique.

Comment fonctionne le champ

Lorsque vous définissez un champ Html dans Odoo, le framework crée une colonne TEXT dans la base de données PostgreSQL. Il n'y a pas de contrainte de longueur au niveau de la base de données, ce qui le rend adapté au contenu long. Le framework Odoo gère la couche de désinfection avant que la valeur ne soit écrite dans la base de données.

Désinfection et Sécurité

Le comportement le plus distinctif du champ Html par rapport aux autres types de champs est sa couche de désinfection. Par défaut, Odoo supprime tous les tags ou attributs HTML qui pourraient être utilisés pour des attaques de type cross-site scripting (XSS). Cela est contrôlé par un ensemble d'attributs de champ :

sanitize : Lorsque True (la valeur par défaut), Odoo applique le processus de désinfection complet avant d'enregistrer la valeur. Réglez sur False uniquement lorsque vous êtes certain que le contenu provient d'une source de confiance et doit préserver le HTML brut.
sanitize_tags : Lorsque True, Odoo supprime tous les tags HTML qui ne figurent pas sur la liste autorisée. Désactiver cela permet des tags arbitraires mais doit être fait avec prudence.
sanitize_attributes : Contrôle si les attributs sur les tags HTML sont également désinfectés.
sanitize_style : Contrôle si les attributs de style en ligne sont désinfectés. Par défaut, certaines propriétés CSS sont autorisées tandis que celles potentiellement dangereuses sont supprimées.
strip_style : Lorsque True, supprime entièrement tous les attributs de style en ligne.
strip_classes : Lorsque True, supprime tous les attributs de classe CSS du contenu stocké.

Cette sanitation rend le champ Html sûr à utiliser pour le contenu généré par les utilisateurs, c'est pourquoi il apparaît sur les formulaires et les modèles d'e-mail destinés aux clients dans Odoo.

Attributs de champ clés

Au-delà de la sanitation, le champ Html partage de nombreux attributs de champ standard d'Odoo :

translate : Lorsqu'il est défini sur True, le contenu du champ peut être traduit par langue. Odoo stocke une version distincte de l'HTML pour chaque langue active dans la base de données.
required : Rend le champ obligatoire. Notez qu'un champ Html contenant uniquement des espaces vides ou des balises vides apparaîtra toujours comme non vide pour l'interface, donc la validation requise fonctionne mieux sur des valeurs véritablement vides.
default : Définit une valeur HTML par défaut pour les nouveaux enregistrements. Utile pour pré-remplir les modèles d'e-mail ou les descriptions de produits avec un texte standard.
compute : Lie une méthode Python qui construit dynamiquement le contenu HTML. Avec store=True, le résultat est conservé dans la base de données.
copy : Contrôle si le contenu HTML est dupliqué lors de la copie d'un enregistrement. Par défaut, c'est True.

Comment cela apparaît dans les vues

Dans les vues de formulaire, un champ Html se rend sous la forme de l'éditeur de texte enrichi d'Odoo. Les utilisateurs obtiennent une barre d'outils avec des options de formatage et la zone de contenu gère le texte stylé, les images et les liens. Dans les vues de liste, Odoo affiche généralement un aperçu en texte brut avec les balises HTML supprimées, pour garder la liste lisible.

L'attribut widget dans les vues XML vous permet de contrôler le rendu. Le widget par défaut pour les champs Html est l'éditeur de texte enrichi. Vous pouvez également rendre un champ Html en tant que sortie HTML en lecture seule en utilisant le widget html, ce qui est utile dans les vues de rapport ou sur les pages de portail où vous souhaitez afficher du contenu formaté sans une barre d'outils modifiable.

Interaction avec l'ORM Odoo

D'un point de vue développement, la lecture d'un champ Html renvoie une chaîne contenant le balisage HTML brut. L'écriture attend également une chaîne HTML. La désinfection se produit au niveau de l'ORM avant que l'écriture n'atteigne la base de données, donc même les valeurs écrites via l'API XML-RPC passent par le même processus de nettoyage lorsque sanitize=True.

Une implication pratique : si vous devez stocker et récupérer du contenu qui inclut des balises ou des attributs HTML personnalisés non présents dans la liste autorisée d'Odoo, vous devrez définir sanitize=False ou ajuster les indicateurs de désinfection dans la définition du champ. C'est un cas d'utilisation avancé qui nécessite une attention particulière aux implications de sécurité dans votre déploiement.

Cas d'utilisation commerciale

Le champ Html apparaît dans de nombreux domaines d'une implémentation Odoo. Voici cinq exemples concrets issus de flux de travail commerciaux courants.

Inventaire et E-commerce : Descriptions de produits

Le champ Html le plus utilisé dans Odoo est le champ description_sale sur product.template. C'est la description du produit que les clients voient sur le site web et dans les lignes de commande de vente. L'utilisation d'un champ Html ici permet aux équipes de merchandising d'écrire un contenu produit structuré avec des points de balle, des titres et des images intégrées, ce qui se traduit directement par de meilleures conversions e-commerce. Le même enregistrement de produit alimente à la fois le back-office et la vitrine, donc il n'y a pas de duplication de contenu entre les systèmes.

Marketing par e-mail : Corps de modèles

Les modèles d'e-mail d'Odoo s'appuient fortement sur les champs Html. Le champ body_html sur mail.template stocke l'intégralité du corps de l'e-mail en tant que HTML, y compris la mise en page, les images et les espaces réservés dynamiques qui sont remplacés par de vraies valeurs au moment de l'envoi. Les équipes marketing peuvent concevoir un contenu d'e-mail riche directement dans Odoo sans avoir besoin d'un outil de conception d'e-mail externe. Le contenu est versionné et réutilisable à travers les campagnes, les devis et les flux de travail automatisés.

CRM : Notes et descriptions d'opportunités

Les équipes de vente ont souvent besoin de capturer un contexte détaillé sur un prospect ou une affaire. Les champs Html sur les pistes et opportunités CRM permettent aux représentants d'écrire des notes structurées avec mise en forme, listes et liens intégrés vers des documents ou propositions externes. Cela est plus utile que les champs de texte brut lorsque les notes doivent être partagées au sein d'une équipe ou incluses dans des rapports imprimés, car la mise en forme survit dans tous ces contextes.

Comptabilité : Termes et conditions de facturation

De nombreuses entreprises incluent des conditions de paiement, des clauses légales ou des informations sur la garantie en bas des factures et des bons de commande. Le champ note sur les bons de commande et les factures est un champ Html, permettant aux équipes financières et opérationnelles de structurer ces termes de manière appropriée. Le contenu apparaît proprement sur les documents PDF imprimés, avec des sauts de ligne et des mises en évidence préservés exactement comme saisis.

RH : Descriptions de postes

Lorsque les équipes RH publient des offres d'emploi via Odoo Recruitment, la description du poste est stockée dans un champ Html sur les modèles hr.job et hr.applicant. Cela permet des annonces de poste structurées avec des sections claires pour les responsabilités, les exigences et les avantages, exactement le type de contenu formaté qui a l'air professionnel sur une page carrières et aide à attirer les bons candidats.

Créer ou personnaliser le champ Html

Il existe trois principales façons d'ajouter un champ Html à un modèle Odoo, en fonction de votre configuration technique et de votre approche de déploiement.

Utilisation d'Odoo Studio (sans code)

Odoo Studio facilite l'ajout d'un champ Html à tout formulaire existant sans écrire de code :

Ouvrez Odoo Studio depuis le menu principal.
Naviguez jusqu'au formulaire où vous souhaitez ajouter le champ.
Depuis la barre latérale, faites glisser un champ Html ou Rich Text sur le formulaire.
Définissez l'étiquette et toutes les autres options dans le panneau des propriétés du champ.
Enregistrez et fermez Studio.

Studio crée automatiquement le champ avec un préfixe x_studio_, l'ajoute à la vue et gère la colonne de la base de données. Aucune étape de migration ou de déploiement n'est nécessaire de votre part. Le champ est immédiatement disponible pour la saisie de données dans l'ensemble de l'instance.

Utiliser Python dans un module personnalisé

Pour les développeurs construisant des modules Odoo, les champs Html sont définis dans des fichiers de modèle Python. Cette approche est recommandée pour toute personnalisation qui doit être contrôlée par version et déployée à travers des environnements de staging et de production :

from odoo import fields, models

class SaleOrder(models.Model):
    _inherit = 'sale.order'

    x_delivery_instructions = fields.Html(
        string='Instructions de livraison',
        sanitize=True,
        translate=True,
    )

Après avoir défini le champ dans le modèle, ajoutez-le au fichier XML de vue pertinent afin qu'il apparaisse dans l'interface. Odoo gère automatiquement la création de la colonne TEXT dans la base de données lorsque vous installez ou mettez à jour le module. Le champ sera rendu comme un éditeur de texte enrichi dans la vue de formulaire sans aucune configuration de widget supplémentaire.

Utiliser l'API XML-RPC

Si vous gérez les personnalisations Odoo de manière programmatique dans le cadre d'un pipeline de déploiement ou d'un script de configuration à distance, vous pouvez créer des champs Html via l'API XML-RPC :

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_custom_notes',
        'field_description': 'Notes personnalisées',
        'model_id': model_id,
        'ttype': 'html',
        'state': 'manual',
    }]
)

La valeur ttype: html indique à Odoo de créer un champ Html. Le paramètre state: manual le marque comme un champ créé par l'utilisateur plutôt que défini par un module. C'est la même approche que Dasolo utilise pour la création de champs à distance dans des environnements clients, dans le cadre de carnets de configuration automatisés qui peuvent être exécutés et suivis sans accès direct au serveur.

Notez que les options de désinfection (sanitize, sanitize_tags, etc.) ne peuvent pas être définies via l'API sur ir.model.fields de la même manière qu'elles le sont en Python. Le comportement de désinfection par défaut s'applique lors de la création de champs via l'API.

Meilleures pratiques

1. Gardez la désinfection activée à moins que vous n'ayez une bonne raison de ne pas le faire

Le comportement de désinfection par défaut existe pour protéger votre instance Odoo contre les vulnérabilités de script intersite. La plupart des cas d'utilisation fonctionnent parfaitement avec la désinfection activée. Désactivez-la uniquement lorsque vous stockez du contenu généré par un processus interne entièrement de confiance, tel qu'un pipeline de rendu côté serveur, et jamais lorsque le contenu provient d'une entrée utilisateur ou de sources externes.

2. Utilisez translate=True pour le contenu produit multilingue

Si votre instance Odoo prend en charge plusieurs langues, les champs Html affichés sur le site Web ou sur les documents destinés aux clients doivent avoir translate=True. Cela permet à votre équipe de maintenir un contenu HTML distinct pour chaque langue, garantissant que les clients voient toujours des descriptions et des termes dans leur propre langue plutôt que dans une langue de secours.

3. Évitez de stocker le contenu des champs Html qui dépend de ressources externes

L'intégration d'images ou de scripts externes dans un champ Html crée des dépendances qui peuvent se briser silencieusement lorsque ces URL externes changent ou deviennent inaccessibles. Utilisez le système de pièces jointes d'Odoo pour héberger les images en interne et faites-y référence avec des URL relatives. Cela maintient votre contenu portable et résilient lors des migrations de base de données et des changements de serveur.

4. Utilisez des champs Html calculés pour le contenu dynamique des documents

Pour le contenu qui doit être construit de manière programmatique, comme un résumé formaté des lignes de commande ou une clause de garantie dynamique, un champ Html calculé avec store=True est une solution propre. La logique de calcul se trouve à un seul endroit, la sortie est stockée dans la base de données pour un accès rapide, et le champ s'affiche correctement à la fois dans l'interface et dans les rapports PDF.

5. Considérez le contexte de rendu lors du choix entre Html et Texte

Si le contenu n'apparaîtra jamais que dans le backend Odoo dans un contexte où les utilisateurs le lisent comme du texte brut, un champ Texte peut suffire. Utilisez Html lorsque le formatage est réellement important pour le lecteur, comme sur une page Web, un document imprimé ou un e-mail. Ajouter un champ Html là où un champ Texte simple suffirait introduit une complexité inutile pour les utilisateurs qui doivent interagir avec un éditeur de texte enrichi pour de simples prises de notes.

Pièges courants

Désactiver la désinfection et l'oublier

Définir sanitize=False sur un champ que les utilisateurs peuvent éditer directement représente un risque de sécurité. Il est facile de faire cela pendant le développement pour débloquer une exigence de formatage, puis d'oublier de le revoir avant de passer en production. Documentez toujours pourquoi la désinfection est désactivée et planifiez une révision avant le déploiement.

Coller du contenu provenant de sources externes avec du HTML cassé

Lorsque les utilisateurs collent du contenu provenant de documents Word, de Google Docs ou de sites Web dans un champ Html, le résultat contient souvent du HTML désordonné ou non standard. Cela peut entraîner un rendu incohérent, des caractères invisibles qui cassent les recherches, ou des valeurs de champ gonflées qui ralentissent le chargement des pages. Encouragez les utilisateurs à utiliser d'abord l'option "Coller en tant que texte brut" puis à réappliquer le formatage dans l'éditeur Odoo.

Confondre le champ Html avec le contenu du constructeur de site Web

Le constructeur de site web d'Odoo utilise des blocs de construction et des composants Owl pour créer le contenu des pages. Le HTML stocké par le constructeur de site web dans les vues de page n'est pas le même que celui que vous mettriez dans un champ Html standard. Essayer de copier un HTML complexe du constructeur de site web dans un champ Html sur un modèle ne s'affichera généralement pas correctement et peut être supprimé par le nettoyeur.

Oublier de traduire lors des déploiements multilingues

Dans une instance Odoo multilingue, un champ Html sans translate=True affiche le même contenu aux utilisateurs de toutes les langues. Cela convient pour les champs internes, mais devient un problème pour les descriptions de produits, les modèles d'e-mails et tout contenu qui atteint des contacts externes. Omettre ce paramètre est facile à négliger lors de la configuration initiale et difficile à corriger rétroactivement une fois que le contenu a été saisi dans une seule langue.

Utiliser des champs Html dans des endroits où du texte brut est attendu

Certaines parties d'Odoo, comme les sujets d'e-mail, les titres de rapport ou les réponses d'API externes, s'attendent à des chaînes de texte brut. Si vous stockez une valeur de champ Html dans un contexte où les balises HTML ne sont pas supprimées, vos utilisateurs verront du balisage brut comme <p>Bonjour</p> au lieu d'un texte propre. Vérifiez toujours comment et où la valeur du champ sera consommée avant de choisir Html plutôt que Char ou Text.

Conclusion

Le champ Html est l'un des types de champs les plus puissants dans le modèle de données Odoo. Il se trouve discrètement derrière les descriptions de produits, les modèles d'e-mails, les offres d'emploi et les notes de factures, rendant le contenu formaté possible dans tout le système sans aucun outil supplémentaire.

Comprendre comment cela fonctionne, en particulier la couche de nettoyage, le support de traduction et son comportement dans différents contextes de rendu, vous aide à prendre de meilleures décisions lors de la conception ou de la personnalisation d'une instance Odoo. Que vous utilisiez Odoo Studio pour ajouter un champ de texte enrichi à un formulaire, que vous le définissiez en Python dans le cadre d'un module personnalisé, ou que vous le créiez à distance via l'API, les principes abordés dans ce guide s'appliquent aux trois approches.

Comme la plupart des choses dans Odoo, le champ lui-même est simple une fois que vous savez ce qu'il fait en coulisses. La valeur vient de son utilisation dans les bons endroits, avec les bons paramètres, pour le bon type de contenu.

Chez Dasolo, nous aidons les entreprises à mettre en œuvre, personnaliser et optimiser Odoo dans tous les départements. Que vous ayez besoin d'aide pour concevoir un modèle de données propre, ajouter des champs personnalisés à vos flux de travail, ou construire des modules Odoo complets adaptés à votre entreprise, notre équipe est là. Contactez-nous et parlons de votre projet Odoo.

Champ HTML dans Odoo : Le Guide Complet