View objects expose a number of fields, they are optional unless specified otherwise)
client programs can request views by id, or by (model, type). For the latter, all the views for the right type and model will be looked for, and the one with the lowest priority number will be returned (it is the “default view”).
priority also defines the order of application during view inheritance
Resolution generates the final arch for a requested/matched primary view:
The result of applying children views yields the final arch
There are three types of inheritance specs:
The inheritance spec may have an optional position attribute specifying how the matched node should be altered:
the content of the inheritance spec should be attribute elements with a name attribute and an optional body:
A view’s specs are applied sequentially.
The root element of list views is <tree>[3]. The list view’s root can have the following attributes:
by default, selecting a list view’s row opens the corresponding form view. The editable attributes makes the list view itself editable in-place.
Valid values are top and bottom, making new records appear respectively at the top or bottom of the list.
The architecture for the inline form view is derived from the list view. Most attributes valid on a form view‘s fields and buttons are thus accepted by list views although they may not have any meaning if the list view is non-editable
overrides the ordering of the view, replacing the model’s default order. The value is a comma-separated list of fields, postfixed by desc to sort in reverse order:
<tree default_order="sequence,name desc">
Deprecated since version 9.0: replaced by decoration-{$name}
Deprecated since version 9.0: replaced by decoration-{$name}
allow changing the style of a row’s text based on the corresponding record’s attributes.
Values are Python expressions. For each record, the expression is evaluated with the record’s attributes as context values and if true, the corresponding style is applied to the row. Other context values are uid (the id of the current user) and current_date (the current date as a string of the form yyyy-MM-dd).
{$name} can be bf (font-weight: bold), it (font-style: italic), or any bootstrap contextual color (danger, info, muted, primary, success or warning).
only makes sense on an editable list. Should be the name of a method on the list’s model. The method will be called with the id of a record after having created or edited that record (in database).
The method should return a list of ids of other records to load or update.
alternative translatable label for the view
Deprecated since version 8.0: not displayed anymore
Possible children elements of the list view are:
displays a button in a list cell
type of button, indicates how it clicking it affects Odoo:
dynamic attributes based on record values.
A mapping of attributes to domains, domains are evaluated in the context of the current row’s record, if True the corresponding attribute is set on the cell.
Possible attributes are invisible (hides the button) and readonly (disables the button but still shows it)
shorthand for invisible attrs: a list of states, comma separated, requires that the model has a state field and that it is used in the view.
Makes the button invisible if the record is not in one of the listed states
defines a column where the corresponding field should be displayed for each record. Can use the following attributes:
alternate representations for a field’s display. Possible list view values are:
Note
if the list view is editable, any field attribute from the form view is also valid and will be used when setting up the inline form view
Form views are used to display the data from a single record. Their root element is <form>. They are composed of regular HTML with additional structural and semantic components.
Structural components provide structure or “visual” features with little logic. They are used as elements or sets of elements in form views.
defines a tabbed section. Each tab is defined through a page child element. Pages can have the following attributes:
used to define column layouts in forms. By default, groups define 2 columns and most direct children of groups take a single column. field direct children of groups display a label by default, and the label and the field itself have a colspan of 1 each.
The number of columns in a group can be customized using the col attribute, the number of columns taken by an element can be customized using colspan.
Children are laid out horizontally (tries to fill the next column before changing row).
Groups can have a string attribute, which is displayed as the group’s title
Semantic components tie into and allow interaction with the Odoo system. Available semantic components are:
renders (and allow edition of, possibly) a single field of the current record. Possible attributes are:
HTML class to set on the generated element, common field classes are:
calls the specified method when this field’s value is edited, can generate update other fields or display warnings for the user
Deprecated since version 8.0: Use openerp.api.onchange() on the model
Business views are targeted at regular users, not advanced users. Examples are: Opportunities, Products, Partners, Tasks, Projects, etc.
In general, a business view is composed of
Technically, the new form views are structured as follows in XML:
<form>
<header> ... content of the status bar ... </header>
<sheet> ... content of the sheet ... </sheet>
<div class="oe_chatter"> ... content of the bottom part ... </div>
</form>
The purpose of the status bar is to show the status of the current record and the action buttons.
The order of buttons follows the business flow. For instance, in a sale order, the logical steps are:
Highlighted buttons (in red by default) emphasize the logical next step, to help the user. It is usually the first active button. On the other hand, cancel buttons must remain grey (normal). For instance, in Invoice the button Refund must never be red.
Technically, buttons are highlighted by adding the class “oe_highlight”:
<button class="oe_highlight" name="..." type="..." states="..."/>
Uses the statusbar widget, and shows the current state in red. States common to all flows (for instance, a sale order begins as a quotation, then we send it, then it becomes a full sale order, and finally it is done) should be visible at all times but exceptions or states depending on particular sub-flow should only be visible when current.
The states are shown following the order used in the field (the list in a selection field, etc). States that are always visible are specified with the attribute statusbar_visible.
statusbar_colors can be used to give a custom color to specific states.
<field name="state" widget="statusbar"
statusbar_visible="draft,sent,progress,invoiced,done"
statusbar_colors="{'shipping_except':'red','waiting_date':'blue'}"/>
All business views should look like a printed sheet:
Elements inside a <form> or <page> do not define groups, elements inside them are laid out according to normal HTML rules. They content can be explicitly grouped using <group> or regular <div> elements.
By default, the element <group> defines two columns inside, unless an attribute col="n" is used. The columns have the same width (1/n th of the group’s width). Use a <group> element to produce a column of fields.
To give a title to a section, add a string attribute to a <group> element:
<group string="Time-sensitive operations">
this replaces the former use of <separator string="XXX"/>.
The <field> element does not produce a label, except as direct children of a <group> element[1]. Use <label for="field_name> to produce a label of a field.
Some sheets have headers with one or more fields, and the labels of those fields are only shown in edit mode.
View mode | Edit mode |
---|---|
Use HTML text, <div>, <h1>, <h2>… to produce nice headers, and <label> with the class oe_edit_only to only display the field’s label in edit mode. The class oe_inline will make fields inline (instead of blocks): content following the field will be displayed on the same line rather than on the line below it. The form above is produced by the following XML:
<label for="name" class="oe_edit_only"/>
<h1><field name="name"/></h1>
<label for="planned_revenue" class="oe_edit_only"/>
<h2>
<field name="planned_revenue" class="oe_inline"/>
<field name="company_currency" class="oe_inline oe_edit_only"/> at
<field name="probability" class="oe_inline"/> % success rate
</h2>
Many relevant actions or links can be displayed in the form. For example, in Opportunity form, the actions “Schedule a Call” and “Schedule a Meeting” take an important place in the use of the CRM. Instead of placing them in the “More” menu, put them directly in the sheet as buttons (on the top) to make them more visible and more easily accessible.
Technically, the buttons are placed inside a <div> to group them as a block on the top of the sheet.
<div class="oe_button_box" name="button_box">
<button string="Schedule/Log Call" name="..." type="action"/>
<button string="Schedule Meeting" name="action_makeMeeting" type="object"/>
</div>
A column of fields is now produced with a <group> element, with an optional title.
<group string="Payment Options">
<field name="writeoff_amount"/>
<field name="payment_option"/>
</group>
It is recommended to have two columns of fields on the form. For this, simply put the <group> elements that contain the fields inside a top-level <group> element.
To make view extension simpler, it is recommended to put a name attribute on <group> elements, so new fields can easily be added at the right place.
Some classes are defined to render subtotals like in invoice forms:
<group class="oe_subtotal_footer">
<field name="amount_untaxed"/>
<field name="amount_tax"/>
<field name="amount_total" class="oe_subtotal_footer_separator"/>
<field name="residual" style="margin-top: 10px"/>
</group>
Sometimes field labels make the form too complex. One can omit field labels, and instead put a placeholder inside the field. The placeholder text is visible only when the field is empty. The placeholder should tell what to place inside the field, it must not be an example as they are often confused with filled data.
One can also group fields together by rendering them “inline” inside an explicit block element like <div>`. This allows grouping semantically related fields as if they were a single (composite) fields.
The following example, taken from the Leads form, shows both placeholders and inline fields (zip and city).
Edit mode | View mode |
---|---|
<group>
<label for="street" string="Address"/>
<div>
<field name="street" placeholder="Street..."/>
<field name="street2"/>
<div>
<field name="zip" class="oe_inline" placeholder="ZIP"/>
<field name="city" class="oe_inline" placeholder="City"/>
</div>
<field name="state_id" placeholder="State"/>
<field name="country_id" placeholder="Country"/>
</div>
</group>
Images, like avatars, should be displayed on the right of the sheet. The product form looks like:
The form above contains a <sheet> element that starts with:
<field name="product_image" widget="image" class="oe_avatar oe_right"/>
Most Many2many fields, like categories, are better rendered as a list of tags. Use the widget many2many_tags for this:
<field name="category_id" widget="many2many_tags"/>
Examples of configuration forms: Stages, Leave Type, etc. This concerns all menu items under Configuration of each application (like Sales/Configuration).
Example: “Schedule a Call” from an opportunity.
Example: Settings / Configuration / Sales.
The graph view is used to visualize aggregations over a number of records or record groups. Its root element is <graph> which can take the following attributes:
The only allowed element within a graph view is field which can have the following attributes:
indicates whether the field should be used as a grouping criteria or as an aggregated value within a group. Possible values are:
Warning
graph view aggregations are performed on database content, non-stored function fields can not be used in graph views
The pivot view is used to visualize aggregations as a pivot table. Its root element is <pivot> which can take the following attributes:
The elements allowed within a pivot view are the same as for the graph view.
The kanban view is a kanban board visualisation: it displays records as “cards”, halfway between a list view and a non-editable form view. Records may be grouped in columns for use in workflow visualisation or manipulation (e.g. tasks or work-progress management), or ungrouped (used simply to visualize records).
The root element of the Kanban view is <kanban>, it can use the following attributes:
whether it should be possible to create records without switching to the form view. By default, quick_create is enabled when the Kanban view is grouped, and disabled when not.
Set to true to always enable it, and to false to always disable it.
Possible children of the view element are:
declares fields to aggregate or to use in kanban logic. If the field is simply displayed in the kanban view, it does not need to be pre-declared.
Possible attributes are:
defines a list of QWeb templates. Cards definition may be split into multiple templates for clarity, but kanban views must define at least one root template kanban-box, which will be rendered once for each record.
The kanban view uses mostly-standard javascript qweb and provides the following context variables:
self-explanatory
buttons and fields
While most of the Kanban templates are standard QWeb, the Kanban view processes field, button and a elements specially:
by default fields are replaced by their formatted value, unless they match specific kanban view widgets
buttons and links with a type attribute become perform Odoo-related operations rather than their standard HTML function. Possible types are:
standard behavior for Odoo buttons, most attributes relevant to standard Odoo buttons can be used.
opens the card’s record in the form view in read-only mode
opens the card’s record in the form view in editable mode
deletes the card’s record and removes the card
Widget() handling the rendering of a single record to a card. Available within its own rendering as widget in the template context.
Converts a color segmentation value to a kanban color class oe_kanban_color_color_index. The built-in CSS provides classes up to a color_index of 9.
Converts a color segmentation value to a color index (between 0 and 9 by default). Color segmentation values can be either numbers or strings.
Generates the URL to the specified field as an image access.
Arguments: |
|
---|---|
Returns: | an image URL |
clips text beyond the specified size and appends an ellipsis to it. Can be used to display the initial part of potentially very long fields (e.g. descriptions) without the risk of unwieldy cards
Calendar views display records as events in a daily, weekly or monthly calendar. Their root element is <calendar>. Available attributes on the calendar view are:
Gantt views appropriately display Gantt charts (for scheduling).
The root element of gantt views is <gantt/>, it has no children but can take the following attributes:
name of the field providing the end duration of the event for each record. Can be replaced by date_delay. One (and only one) of date_stop and date_delay must be provided.
If the field is False for a record, it’s assumed to be a “point event” and the end date will be set to the start date
The diagram view can be used to display directed graphs of records. The root element is <diagram> and takes no attributes.
Possible children of the diagram view are:
Defines the nodes of the graph. Its attributes are:
Defines the directed edges of the graph. Its attributes are:
Search views are a break from previous view types in that they don’t display content: although they apply to a specific model, they are used to filter other view’s content (generally aggregated views e.g. Lists or Graphs). Beyond that difference in use case, they are defined the same way.
The root element of search views is <search>. It takes no attributes.
Possible children elements of the search view are:
fields define domains or contexts with user-provided values. When search domains are generated, field domains are composed with one another and with filters using AND.
Fields can have the following attributes:
by default, fields generate domains of the form [(name, operator, provided_value)] where name is the field’s name and provided_value is the value provided by the user, possibly filtered or transformed (e.g. a user is expected to provide the label of a selection field’s value, not the value itself).
The operator attribute allows overriding the default operator, which depends on the field’s type (e.g. = for float fields but ilike for char fields)
complete domain to use as the field’s search domain, can use a self variable to inject the provided value in the custom domain. Can be used to generate significantly more flexible domains than operator alone (e.g. searches on multiple fields at once)
If both operator and filter_domain are provided, filter_domain takes precedence.
allows adding context keys, including the user-provided value (which as for domain is available as a self variable). By default, fields don’t generate domains.
Note
the domain and context are inclusive and both are generated if if a context is specified. To only generate context values, set filter_domain to an empty list: filter_domain="[]"
a filter is a predefined toggle in the search view, it can only be enabled or disabled. Its main purposes are to add data to the search context (the context passed to the data view for searching/filtering), or to append new sections to the search filter.
Filters can have the following attributes:
an icon to display next to the label, if there’s sufficient space
Deprecated since version 7.0.
Tip
New in version 7.0.
Sequences of filters (without non-filters separating them) are treated as inclusively composited: they will be composed with OR rather than the usual AND, e.g.
<filter domain="[('state', '=', 'draft')]"/>
<filter domain="[('state', '=', 'done')]"/>
if both filters are selected, will select the records whose state is draft or done, but
<filter domain="[('state', '=', 'draft')]"/>
<separator/>
<filter domain="[('delay', '<', 15)]"/>
if both filters are selected, will select the records whose state is draft and delay is below 15.
Search fields and filters can be configured through the action’s context using search_default_name keys. For fields, the value should be the value to set in the field, for filters it’s a boolean value. For instance, assuming foo is a field and bar is a filter an action context of:
{
'search_default_foo': 'acro',
'search_default_bar': 1
}
will automatically enable the bar filter and search the foo field for acro.
QWeb views are standard QWeb templates inside a view’s arch. They don’t have a specific root element.
A QWeb view can only contain a single template[4], and the template’s name must match the view’s complete (including module name) external id.
template should be used as a shortcut to define QWeb views.
[1] | for backwards compatibility reasons |
[2] | an extension function is added for simpler matching in QWeb views: hasclass(*classes) matches if the context node has all the specified classes |
[3] | for historical reasons, it has its origin in tree-type views later repurposed to a more table/list-type display |
[4] | or no template if it’s an inherited view, then it should only contain xpath elements |
odoo docs theme based on Bootstrap 3.2 documentation adapted to Sphinx output with branding and color changes.