- banner
banners/views.jpg
xml
View objects expose a number of fields, they are optional unless specified otherwise.
name
(mandatory)only useful as a mnemonic/description of the view when looking for one in a list of some sort
model
the model linked to the view, if applicable (it doesn't for QWeb views)
priority
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 searched, and the one with the lowestpriority
number will be returned (it is the "default view").priority
also defines the order of application duringview inheritance <reference/views/inheritance>
arch
the description of the view's layout
groups_id
~odoo.fields.Many2many
field to the groups allowed to view/use the current viewinherit_id
the current view's parent view, see
reference/views/inheritance
, unset by defaultmode
inheritance mode, see
reference/views/inheritance
. Ifinherit_id
is unset themode
can only beprimary
. Ifinherit_id
is set,extension
by default but can be explicitly set toprimary
application
website feature defining togglable views. By default, views are always applied
- if a view is requested by
(model, type)
, the view with the right model and type,mode=primary
and the lowest priority is matched - when a view is requested by
id
, if its mode is notprimary
its closest parent with modeprimary
is matched
Resolution generates the final arch
for a requested/matched primary
view:
- if the view has a parent, the parent is fully resolved then the current view's inheritance specs are applied
- if the view has no parent, its
arch
is used as-is - the current view's children with mode
extension
are looked up and their inheritance specs are applied depth-first (a child view is applied, then its children, then its siblings)
The result of applying children views yields the final arch
Inheritance specs are comprised of an element locator, to match the inherited element in the parent view, and children element that will be used to modify the inherited element.
There are three types of element locators for matching a target element:
- An
xpath
element with anexpr
attribute.expr
is an XPath expression1 applied to the currentarch
, the first node it finds is the match - a
field
element with aname
attribute, matches the firstfield
with the samename
. All other attributes are ignored during matching - any other element: the first element with the same name and identical attributes (ignoring
position
andversion
attributes) is matched
The inheritance spec may have an optional position
attribute specifying how the matched node should be altered:
inside
(default)the content of the inheritance spec is appended to the matched node
replace
the content of the inheritance spec replaces the matched node. Any text node containing only
$0
within the contents of the spec will be replaced by a complete copy of the matched node, effectively wrapping the matched node.after
the content of the inheritance spec is added to the matched node's parent, after the matched node
before
the content of the inheritance spec is added to the matched node's parent, before the matched node
attributes
the content of the inheritance spec should be
attribute
elements with aname
attribute and an optional body:- if the
attribute
element has a body, a new attributed named after itsname
is created on the matched node with theattribute
element's text as value - if the
attribute
element has no body, the attribute named after itsname
is removed from the matched node. If no such attribute exists, an error is raised
- if the
A view's specs are applied sequentially.
The root element of list views is <tree>
2. The list view's root can have the following attributes:
editable
by default, selecting a list view's row opens the corresponding
form view <reference/views/form>
. Theeditable
attributes makes the list view itself editable in-place.Valid values are
top
andbottom
, making new records appear respectively at the top or bottom of the list.The architecture for the inline
form view <reference/views/form>
is derived from the list view. Most attributes valid on aform view <reference/views/form>
's fields and buttons are thus accepted by list views although they may not have any meaning if the list view is non-editabledefault_order
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">
colors
9.0 replaced by
decoration-{$name}
fonts
9.0 replaced by
decoration-{$name}
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 areuid
(the id of the current user) andcurrent_date
(the current date as a string of the formyyyy-MM-dd
).{$name}
can bebf
(font-weight: bold
),it
(font-style: italic
), or any bootstrap contextual color (danger
,info
,muted
,primary
,success
orwarning
).create
,edit
,delete
allows disabling the corresponding action in the view by setting the corresponding attribute to
false
on_write
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 theid
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.
string
alternative translatable label for the view
8.0
not displayed anymore
Possible children elements of the list view are:
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.
notebook
defines a tabbed section. Each tab is defined through a
page
child element. Pages can have the following attributes:string
(required)the title of the tab
accesskey
an HTML accesskey
attrs
standard dynamic attributes based on record values
group
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 thecol
attribute, the number of columns taken by an element can be customized usingcolspan
.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 titlenewline
only useful within
group
elements, ends the current row early and immediately switches to a new row (without filling any remaining column beforehand)separator
small horizontal spacing, with a
string
attribute behaves as a section titlesheet
can be used as a direct child to
form
for a narrower and more responsive form layoutheader
combined with
sheet
, provides a full-width location above the sheet itself, generally used to display workflow buttons and status widgets
Semantic components tie into and allow interaction with the Odoo system. Available semantic components are:
button
call into the Odoo system, similar to
list view buttons <reference/views/list/button>
field
renders (and allow edition of, possibly) a single field of the current record. Possible attributes are:
name
(mandatory)the name of the field to render
widget
fields have a default rendering based on their type (e.g.
~odoo.fields.Char
,~odoo.fields.Many2one
). Thewidget
attributes allows using a different rendering method and context.list of widgets
& options & specific attributes (e.g. widget=statusbar statusbar_visible clickable)
options
JSON object specifying configuration option for the field's widget (including default widgets)
class
HTML class to set on the generated element, common field classes are:
oe_inline
prevent the usual line break following fields
oe_left
,oe_right
floats the field to the corresponding direction
oe_read_only
,oe_edit_only
only displays the field in the corresponding form mode
oe_no_button
avoids displaying the navigation button in a
~odoo.fields.Many2one
oe_avatar
for image fields, displays images as "avatar" (square, 90x90 maximum size, some image decorations)
groups
only displays the field for specific users
on_change
calls the specified method when this field's value is edited, can generate update other fields or display warnings for the user
8.0
Use
odoo.api.onchange
on the modelattrs
dynamic meta-parameters based on record values
domain
for relational fields only, filters to apply when displaying existing records for selection
context
for relational fields only, context to pass when fetching possible values
readonly
display the field in both readonly and edition mode, but never make it editable
required
generates an error and prevents saving the record if the field doesn't have a value
nolabel
don't automatically display the field's label, only makes sense if the field is a direct child of a
group
elementplaceholder
help message to display in empty fields. Can replace field labels in complex forms. Should not be an example of data as users are liable to confuse placeholder text with filled fields
mode
for
~odoo.fields.One2many
, display mode (view type) to use for the field's linked records. One oftree
,form
,kanban
orgraph
. The default istree
(a list display)help
tooltip displayed for users when hovering the field or its label
filename
for binary fields, name of the related field providing the name of the file
password
indicates that a
~odoo.fields.Char
field stores a password and that its data shouldn't be displayed
classes for forms
widgets?
Aline Preillon, Raphael Collet
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
- a status bar on top (with technical or business flow),
- a sheet in the middle (the form itself),
- a bottom part with History and Comments.
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:
- Send the quotation
- Confirm the quotation
- Create the final invoice
- Send the goods
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
.
<field name="state" widget="statusbar"
statusbar_visible="draft,sent,progress,invoiced,done" />
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 attributecol="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>
element3. 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" have 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 <reference/views/inheritance>
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 ~odoo.fields.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).
- no header (because no state, no workflow, no button)
- no sheet
Example: "Schedule a Call" from an opportunity.
- avoid separators (the title is already in the popup title bar, so another separator is not relevant)
- avoid cancel buttons (user generally close the popup window to get the same effect)
- action buttons must be highlighted (red)
- when there is a text area, use a placeholder instead of a label or a separator
- like in regular form views, put buttons in the <header> element
Example: Settings / Configuration / Sales.
- always in line (no popup)
- no sheet
- keep the cancel button (users cannot close the window)
- the button "Apply" must be red
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:
type
one of
bar
(default),pie
andline
, the type of graph to usestacked
only used for
bar
charts. If present and set toTrue
, stacks bars within a group
The only allowed element within a graph view is field
which can have the following attributes:
name
(required)the name of a field to use in a graph view. If used for grouping (rather than aggregating)
type
indicates whether the field should be used as a grouping criteria or as an aggregated value within a group. Possible values are:
row
(default)groups by the specified field. All graph types support at least one level of grouping, some may support more. For pivot views, each group gets its own row.
col
only used by pivot tables, creates column-wise groups
measure
field to aggregate within a group
interval
on date and datetime fields, groups by the specified interval (
day
,week
,month
,quarter
oryear
) instead of grouping on the specific datetime (fixed second resolution) or date (fixed day resolution).
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:
disable_linking
Set to
True
to remove table cell's links to list view.display_quantity
Set to
true
to display the Quantity column by default.
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 <reference/views/list>
and a non-editable form view <reference/views/form>
. 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:
default_group_by
whether the kanban view should be grouped if no grouping is specified via the action or the current search. Should be the name of the field to group by when no grouping is otherwise specified
default_order
cards sorting order used if the user has not already sorted the records (via the list view)
class
adds HTML classes to the root HTML element of the Kanban view
group_create
whether the "Add a new column" bar is visible or not. Default: true.
group_delete
whether groups can be deleted via the context menu. Default: true.
group_edit
whether groups can be edited via the context menu. Default: true.
quick_create
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 tofalse
to always disable it.
Possible children of the view element are:
field
declares fields 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:
name
(required)the name of the field to fetch
templates
defines a list of
reference/qweb
templates. Cards definition may be split into multiple templates for clarity, but kanban views must define at least one root templatekanban-box
, which will be rendered once for each record.The kanban view uses mostly-standard
javascript qweb <reference/qweb/javascript>
and provides the following context variables:instance
the current
reference/javascript/client
instancewidget
the current :js
KanbanRecord
, can be used to fetch some meta-information. These methods are also available directly in the template context and don't need to be accessed viawidget
record
an object with all the requested fields as its attributes. Each field has two attributes
value
andraw_value
, the former is formatted according to current user parameters, the latter is the direct value from a~odoo.models.Model.read
(except for date and datetime fields that are formatted according to user's locale)formats
the :js
web.formats
module to manipulate and convert valuesread_only_mode
self-explanatory
buttons and fields
While most of the Kanban templates are standard
reference/qweb
, the Kanban view processesfield
,button
anda
elements specially:by default fields are replaced by their formatted value, unless they match specific kanban view widgets
list widgets?
- buttons and links with a
type
attribute become perform Odoo-related operations rather than their standard HTML function. Possible types are:action
,object
standard behavior for
Odoo buttons <reference/views/list/button>
, most attributes relevant to standard Odoo buttons can be used.open
opens the card's record in the form view in read-only mode
edit
opens the card's record in the form view in editable mode
delete
deletes the card's record and removes the card
- kanban-specific CSS
- kanban structures/widgets (vignette, details, ...)
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:
date_start
(required)name of the record's field holding the start date for the event
date_stop
name of the record's field holding the end date for the event, if
date_stop
is provided records become movable (via drag and drop) directly in the calendardate_delay
alternative to
date_stop
, provides the duration of the event instead of its end datewhat's the unit? Does it allow moving the record?
color
name of a record field to use for color segmentation. Records in the same color segment are allocated the same highlight color in the calendar, colors are allocated semi-randomly.
event_open_popup
opens the event in a dialog instead of switching to the form view, disabled by default
quick_add
enables quick-event creation on click: only asks the user for a
name
and tries to create a new event with just that and the clicked event time. Falls back to a full form dialog if the quick creation failsdisplay
format string for event display, field names should be within brackets
[
and]
all_day
name of a boolean field on the record indicating whether the corresponding event is flagged as day-long (and duration is irrelevant)
mode
Default display mode when loading the calendar. Possible attributes are:
day
,week
,month
what's the purpose of <field>
inside a calendar view?
calendar code is an unreadable mess, no idea what these things are:
attendee
avatar_model
use_contacts
calendar code also seems to refer to multiple additional attributes of unknown purpose
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:
date_start
(required)name of the field providing the start datetime of the event for each record.
date_stop
name of the field providing the end duration of the event for each record. Can be replaced by
date_delay
. One (and only one) ofdate_stop
anddate_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 datedate_delay
name of the field providing the duration of the event
duration_unit
one of
minute
,hour
(default),day
,week
,month
,year
default_group_by
name of a field to group tasks by
type
gantt
classic gantt view (default)consolidate
values of the first children are consolidated in the gantt's taskplanning
children are displayed in the gantt's taskconsolidation
field name to display consolidation value in record cell
consolidation_max
dictionary with the "group by" field as key and the maximum consolidation value that can be reached before displaying the cell in red (e.g.
{"user_id": 100}
)Warning
The dictionnary definition must use double-quotes,
{'user_id': 100}
is not a valid valuestring
string to display next to the consolidation value, if not specified, the label of the consolidation field will be used
fold_last_level
If a value is set, the last grouping level is folded
round_dnd_dates
enables rounding the task's start and end dates to the nearest scale marks
drag_resize
resizing of the tasks, default is
true
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:
node
(required, 1)Defines the nodes of the graph. Its attributes are:
object
the node's Odoo model
shape
conditional shape mapping similar to colors and fonts in
the list view <reference/views/list>
. The only valid shape isrectangle
(the default shape is an ellipsis)bgcolor
same as
shape
, but conditionally maps a background color for nodes. The default background color is white, the only valid alternative isgrey
.
arrow
(required, 1)Defines the directed edges of the graph. Its attributes are:
object
(required)the edge's Odoo model
source
(required)~odoo.fields.Many2one
field of the edge's model pointing to the edge's source node recorddestination
(required)~odoo.fields.Many2one
field of the edge's model pointing to the edge's destination node recordlabel
Python list of attributes (as quoted strings). The corresponding attributes's values will be concatenated and displayed as the edge's label
label
Explanatory note for the diagram, the
string
attribute defines the note's content. Eachlabel
is output as a paragraph in the diagram header, easily visible but without any special emphasis.
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. reference/views/list
or reference/views/graph
). 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:
field
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:
name
the name of the field to filter on
string
the field's label
operator
by default, fields generate domains of the form
[({name}, {operator}, {provided_value})]
wherename
is the field's name andprovided_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 butilike
for char fields)filter_domain
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 thanoperator
alone (e.g. searches on multiple fields at once)If both
operator
andfilter_domain
are provided,filter_domain
takes precedence.context
allows adding context keys, including the user-provided value (which as for
domain
is available as aself
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, setfilter_domain
to an empty list:filter_domain="[]"
groups
make the field only available to specific users
widget
use specific search widget for the field (the only use case in standard Odoo 8.0 is a
selection
widget for~odoo.fields.Many2one
fields)domain
if the field can provide an auto-completion (e.g.
~odoo.fields.Many2one
), filters the possible completion results.
filter
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:
string
(required)the label of the filter
domain
an Odoo
domain <reference/orm/domains>
, will be appended to the action's domain as part of the search domaincontext
a Python dictionary, merged into the action's domain to generate the search domain
name
logical name for the filter, can be used to
enable it by default <reference/views/search/defaults>
, can also be used asinheritance hook <reference/views/inheritance>
help
a longer explanatory text for the filter, may be displayed as a tooltip
groups
makes a filter only available to specific users
Tip
7.0
Sequences of filters (without non-filters separating them) are treated as inclusively composited: they will be composed with
OR
rather than the usualAND
, e.g.<filter domain="[('state', '=', 'draft')]"/> <filter domain="[('state', '=', 'done')]"/>
if both filters are selected, will select the records whose
state
isdraft
ordone
, but<filter domain="[('state', '=', 'draft')]"/> <separator/> <filter domain="[('delay', '<', 15)]"/>
if both filters are selected, will select the records whose
state
isdraft
anddelay
is below 15.separator
can be used to separates groups of filters in simple search views
group
can be used to separate groups of filters, more readable than
separator
in complex search views
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 reference/qweb
templates inside a view's arch
. They don't have a specific root element.
A QWeb view can only contain a single template4, and the template's name must match the view's complete (including module name) external id
.
reference/data/template
should be used as a shortcut to define QWeb views.
an extension function is added for simpler matching in QWeb views:
hasclass(*classes)
matches if the context node has all the specified classes↩for historical reasons, it has its origin in tree-type views later repurposed to a more table/list-type display↩
for backwards compatibility reasons↩
or no template if it's an inherited view, then
it should only contain xpath elements <reference/views/inheritance>
↩