EventMailTemplateReferenceField

Event communication lines in Odoo let an organizer schedule mails or SMS around an event: a reminder three days before, a follow-up after. Each line stores which template to send in template_ref, a reference field that can point at a mail template, an SMS template, or whatever other template models are installed. This widget renders that field.

A reference widget is really two controls in one: a model selector and a record picker. The stock version starts with the model selector empty, which is one click of friction on every new line and a source of half-filled rows. The event variant's entire setup override is choosing a default: it reads the field's selection list and preselects the first model, so a new communication line starts on Mail Template and the user goes straight to picking which template.

Beyond that it makes two presentation calls: an envelope icon appears beside the value when the chosen model is mail.template, and in readonly contexts the many2one refuses to open the template, so a list of scheduler lines reads as text instead of a row of internal links.

Event communication is one of the highest-leverage automations in Odoo events: registration confirmations, reminders, and post-event follow-ups run themselves once the schedule is right. The template picker is where that setup succeeds or silently fails, because a scheduler line without a template does nothing.

The widget's small defaults matter operationally. Preselecting the mail model means the common case, an email reminder, is two clicks: pick template, set trigger. The readonly no-open rule matters for the people reviewing rather than editing: an events manager scanning the communication list of twenty events is not accidentally navigated into template forms mid-review.

The part the widget does not solve is template hygiene. The picker shows whatever templates the filter context allows, and core scopes it to event-appropriate templates with filter_template_on_event. If your team clones templates per event, the list grows until picking the right one is the slow step. A naming convention, or a custom filter mirroring core's context trick, keeps the picker useful at scale.

As core uses it on scheduler lines

<field name="template_ref"
       widget="EventMailTemplateReferenceField"
       options="{'no_quick_create': True}"
       context="{'filter_template_on_event': True, 'default_model': 'event.registration'}"/>

The context keys do the template scoping server-side; the option removes inline creation. Note the exact CamelCase widget name.

Hiding the model selector entirely

<field name="template_ref"
       widget="EventMailTemplateReferenceField"
       options="{'hide_model': True}"/>

Useful when only one template model is installed anyway; the preselected first model then does all the work and users see a single picker.

Three source details are worth pinning down.

The default model is positional, not named. The setup override takes this.selection?.[0][0], the first entry of the field's selection, whatever it is. On a stock database that is the mail template model, but the selection is built server-side from installed template models, so installing a module that reorders or prepends to that selection changes the default silently. If a customization depends on "mail is the default", it is depending on selection order.

Readonly kills opening, deliberately. The m2oProps getter checks props.readonly and forces canOpen = false, with a source comment explaining that m2o values in list views are expected to read as plain strings. This is the opposite default from the base many2one, where readonly values render as links.

The envelope is a template inheritance, not component logic. The widget's XML inherits the base reference template and injects an icon block rendered only when relation === 'mail.template'. There is no icon mapping to configure; other models simply get nothing, so an SMS line is distinguished by its model name, not an icon.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. These notes come from the public development branch, which is unstable until feature freeze; we re-verify this page against the shipped release.

The widget's file is byte-identical on master: same setup override, same readonly rule, same registration. The base reference widget it extends shows only Odoo's framework-wide props-validation migration, with the hide_model and model_field options intact. Barring late changes, this page should apply to Odoo 20 as written, and we will confirm that after release.