Pourquoi un field widget custom ?

Odoo 19 embarque une trentaine de field widgets natifs — char, badge, progressbar, many2many_tags, priority, state_selection… La plupart du temps, ils suffisent. Mais dès qu'un client demande une présentation spécifique — un badge SLA avec animation, un sélecteur couleur custom, un sparkline inline — tu rentres dans le territoire des widgets personnalisés.

En v19, un field widget est un composant OWL standard. Pas de classe abstraite à étendre, pas de legacy layer à contourner — juste un Component issu de @odoo/owl, enregistré dans la registry sous la catégorie "fields". Le form renderer l'instancie, lui passe record et name via ses props, et c'est au composant d'afficher ce qu'il veut.

On va construire sla_badge — un widget qui affiche le champ Selection sla_status du mixin SLA (valeurs ok / warning / breach) sous forme de pastille colorée avec icône FontAwesome. Il remplacera le widget="badge" natif déjà en place sur le form du ticket.

2. Le composant OWL

Tout commence par un import depuis @odoo/owl. La classe étend Component, déclare son template en attribut static, ses props (typés avec la syntaxe OWL), et quelques getters qui calculent la classe CSS, l'icône et le label selon la valeur du champ.

/** @odoo-module **/
import { Component } from "@odoo/owl";
import { registry } from "@web/core/registry";
import { standardFieldProps } from "@web/views/fields/standard_field_props";
import { _t } from "@web/core/l10n/translation";

export class SlaBadgeField extends Component {
    static template = "odooskills_helpdesk.SlaBadge";
    static props = {
        ...standardFieldProps,
        icon: { type: Boolean, optional: true },
        compact: { type: Boolean, optional: true },
    };
    static defaultProps = {
        icon: true,
        compact: false,
    };

    get value() {
        return this.props.record.data[this.props.name] || "ok";
    }

    get label() {
        const labels = {
            ok: _t("Dans les temps"),
            warning: _t("Proche échéance"),
            breach: _t("SLA dépassé"),
        };
        return labels[this.value] || this.value;
    }

    get iconClass() {
        const icons = {
            ok: "fa-check-circle",
            warning: "fa-clock-o",
            breach: "fa-exclamation-triangle",
        };
        return icons[this.value] || "fa-circle-o";
    }

    get pillClass() {
        const base = this.props.compact ? "o_sla_pill o_sla_pill--compact" : "o_sla_pill";
        return `${base} o_sla_pill--${this.value}`;
    }
}

Trois choses à noter :

• standardFieldProps est spreadé pour hériter des {id, name, readonly, record} que tout field widget reçoit du renderer — définis en dur dans odoo/addons/web/static/src/views/fields/standard_field_props.js.
• Les props OWL sont typées en objets, pas en chaînes : { type: Boolean, optional: true }, pas { type: "boolean" }. Erreur typique pour qui vient de Vue ou React.
• Les getters sont réactifs — à chaque changement de props.record.data[name], le template se re-rend automatiquement sans qu'on ait à appeler render() ou à trigger quoi que ce soit.

4. Le template OWL

OWL 2 utilise QWeb côté JS — même syntaxe que les templates serveur, exécuté côté client. Le template vit dans un fichier XML qui doit être enveloppé d'un <templates> (et pas <odoo>, piège classique) :

<?xml version="1.0" encoding="UTF-8"?>
<templates xml:space="preserve">
    <t t-name="odooskills_helpdesk.SlaBadge">
        <span t-att-class="pillClass" t-att-title="label">
            <i t-if="props.icon" class="fa" t-att-class="iconClass"
               role="img" aria-hidden="true"/>
            <span class="o_sla_pill__text" t-out="label"/>
        </span>
    </t>
</templates>

Trois bonnes habitudes v19 à graver :

• t-out et pas t-esc. En v19, t-esc est déprécié — voir la liste des breaking changes dans T25 — Migration 18 → 19.
• t-att-class évalue l'expression côté JS et remplace la valeur de class. Utile pour composer des classes dynamiques comme pillClass ci-dessus.
• Le nom du template (odooskills_helpdesk.SlaBadge) doit matcher exactement static template dans le JS, sinon OWL crashe avec Template not found.

6. Intégrer — manifest & vue inherit

Pour que les 3 fichiers statiques soient chargés côté client, on les déclare dans le bundle web.assets_backend du manifest. Bump de version en prime — le registry-loader d'Odoo détecte qu'on est passé de 19.0.1.16.0 à 19.0.1.17.0 et pousse un upgrade du module.

# addons/odooskills-blog/modules/odooskills_helpdesk/__manifest__.py
{
    'name': 'OdooSkills Helpdesk',
    'version': '19.0.1.17.0',
    # ...
    'data': [
        # ... (les vues existantes)
        'views/helpdesk_ticket_views_t26.xml',   # ← nouvelle vue inherit
    ],
    'assets': {
        'web.assets_backend': [
            'odooskills_helpdesk/static/src/views/fields/sla_badge/sla_badge.js',
            'odooskills_helpdesk/static/src/views/fields/sla_badge/sla_badge.xml',
            'odooskills_helpdesk/static/src/views/fields/sla_badge/sla_badge.scss',
        ],
    },
    'installable': True,
    'application': True,
}

Ensuite la vue inherit. L'astuce v19 ici, c'est qu'on veut remplacer le widget natif (widget="badge") par le nôtre, mais aussi vider les attributs decoration-* hérités de la vue de base. Sans ça, les deux systèmes de coloration se battent et tu obtiens une pastille hybride, souvent incohérente. XPath position="attributes" avec un <attribute> de contenu vide supprime l'attribut ciblé — c'est le comportement documenté dans odoo/tools/template_inheritance.py:303-309.

<?xml version="1.0" encoding="utf-8"?>
<odoo>
  <record id="view_helpdesk_ticket_form_t26_sla_badge" model="ir.ui.view">
    <field name="name">helpdesk.ticket.form.t26.sla_badge</field>
    <field name="model">helpdesk.ticket</field>
    <field name="inherit_id" ref="view_helpdesk_ticket_form"/>
    <field name="arch" type="xml">
      <xpath expr="//field[@name='sla_status']" position="attributes">
        <attribute name="widget">sla_badge</attribute>
        <attribute name="options">{'icon': True, 'compact': False}</attribute>
        <attribute name="decoration-success"/>
        <attribute name="decoration-warning"/>
        <attribute name="decoration-danger"/>
      </xpath>
    </field>
  </record>
</odoo>

Deux détails importants :

• Le xpath cible par @name, jamais par @string. @string n'est pas un attribut XML valide en v19 — voir T09 — Héritage de vues pour les 5 positions et leurs pièges.
• Le contenu vide d'<attribute> signifie « supprime cet attribut ». Un null ou un espace ne marchent pas — l'élément doit être self-closing ou contenir une chaîne vide explicite.

8. Vérifier le rendu

Après -u odooskills_helpdesk --stop-after-init local puis rsync VPS, on recharge un ticket dont le SLA est dans les temps, un proche de l'échéance, et un dépassé. Les trois captures ci-dessous sont réelles — capturées par Playwright sur l'instance de démo odooskills_demo_v19.

Un test TransactionCase côté serveur (voir T24 — Tests automatisés) suffit à valider la partie Python — le widget lui-même n'a pas besoin de test unitaire JS puisqu'il est testé visuellement par Odoo.sh / CI en amont du déploiement.

from odoo.tests import TransactionCase, tagged


@tagged('post_install', '-at_install')
class TestSlaBadgeRegistration(TransactionCase):
    def test_inherit_view_loads(self):
        view = self.env.ref(
            'odooskills_helpdesk.view_helpdesk_ticket_form_t26_sla_badge'
        )
        self.assertEqual(view.model, 'helpdesk.ticket')
        self.assertIn('sla_badge', view.arch)

    def test_manifest_declares_assets(self):
        from odoo.modules.module import get_manifest
        backend = get_manifest('odooskills_helpdesk')['assets']['web.assets_backend']
        paths = [p if isinstance(p, str) else p[1] for p in backend]
        self.assertTrue(any('sla_badge.js' in p for p in paths))
        self.assertTrue(any('sla_badge.xml' in p for p in paths))
        self.assertTrue(any('sla_badge.scss' in p for p in paths))

10. Pièges à éviter

À retenir

• Un field widget v19 = 3 fichiers statiques + 1 vue inherit. Pas de classe abstraite à étendre, pas de legacy layer à contourner — juste un Component de @odoo/owl.
• Le descriptor est la source de vérité — {component, displayName, supportedTypes, supportedOptions, extractProps} suffit pour que le renderer et Studio sachent tout ce qu'ils ont besoin.
• extractProps est la fonction charnière entre les options="{…}" XML et les props OWL typés. La traiter comme une interface stricte, pas comme un dépotoir.
• XPath position="attributes" avec <attribute> self-closing est la manière propre de remplacer un widget natif sans laisser des decoration-* fantômes.
• Les patterns legacy sont morts — odoo.define, AbstractField, this.$el, _render(), trigger_up. Si ton tuto les contient, il est pré-v16.