:banner: banners/views.jpg
.. highlight:: xml
.. _reference/views:
=====
Views
=====
.. _reference/views/structure:
Common Structure
================
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 lowest ``priority`` number will be returned (it is
the "default view").
``priority`` also defines the order of application during :ref:`view
inheritance `
``arch``
the description of the view's layout
``groups_id``:class:`~openerp.fields.Many2many` field to the groups allowed to view/use
the current view
``inherit_id``
the current view's parent view, see :ref:`reference/views/inheritance`,
unset by default
``mode``
inheritance mode, see :ref:`reference/views/inheritance`. If
``inherit_id`` is unset the ``mode`` can only be ``primary``. If
``inherit_id`` is set, ``extension`` by default but can be explicitly set
to ``primary````application``
website feature defining togglable views. By default, views are always
applied
.. _reference/views/inheritance:
Inheritance
===========
View matching
-------------
* 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 not ``primary`` its
*closest* parent with mode ``primary`` is matched
View resolution
---------------
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
-----------------
There are three types of inheritance specs:
* An ``xpath`` element with an ``expr`` attribute. ``expr`` is an XPath_
expression\ [#hasclass]_ applied to the current ``arch``, the first node
it finds is the match
* a ``field`` element with a ``name`` attribute, matches the first ``field``
with the same ``name``
* any other element, the first element with the same name and identical
attributes (ignoring ``position``) 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
``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 a ``name`` attribute and an optional body:
* if the ``attribute`` element has a body, a new attributed named
after its ``name`` is created on the matched node with the
``attribute`` element's text as value
* if the ``attribute`` element has no body, the attribute named after
its ``name`` is removed from the matched node. If no such attribute
exists, an error is raised
A view's specs are applied sequentially.
.. _reference/views/list:
Lists
=====
The root element of list views is ````\ [#treehistory]_. The list view's
root can have the following attributes:
``editable``
by default, selecting a list view's row opens the corresponding
:ref:`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 :ref:`form view ` is
derived from the list view. Most attributes valid on a :ref:`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
``default_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:
.. code-block:: xml
``colors``
allows changing the color of a row's text based on the corresponding
record's attributes.
Defined as a mapping of colors to Python expressions. Values are of the
form: :samp:`{color}:{expr}[;...]`. For each record, pairs are tested
in order, the expression is evaluated for the record and if ``true`` the
corresponding color is applied to the row. If no color matches, uses the
default text color (black).
* ``color`` can be any valid `CSS color unit`_.
* ``expr`` should be a Python expression evaluated with the current
record's attributes as context values. 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``)
``fonts``
allows changing a row's font style based on the corresponding record's
attributes.
The format is the same as for ``color``, but the ``color`` of each pair
is replaced by ``bold``, ``italic`` or ``underline``, the expression
evaluating to ``true`` will apply the corresponding style to the row's
text. Contrary to ``colors``, multiple pairs can match each record
``create``, ``edit``, ``delete``
allows *dis*\ abling 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 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.
``string``
alternative translatable label for the view
.. deprecated:: 8.0
not displayed anymore
.. toolbar attribute is for tree-tree views
Possible children elements of the list view are:
.. _reference/views/list/button:
``button``
displays a button in a list cell
``icon``
icon to use to display the button
``string``
* if there is no ``icon``, the button's text
* if there is an ``icon``, ``alt`` text for the icon
``type``
type of button, indicates how it clicking it affects Odoo:
``workflow`` (default)
sends a signal to a workflow. The button's ``name`` is the
workflow signal, the row's record is passed as argument to the
signal
``object``
call a method on the list's model. The button's ``name`` is the
method, which is called with the current row's record id and the
current context.
.. web client also supports a @args, which allows providing
additional arguments as JSON. Should that be documented? Does
not seem to be used anywhere
``action``
load an execute an ``ir.actions``, the button's ``name`` is the
database id of the action. The context is expanded with the list's
model (as ``active_model``), the current row's record
(``active_id``) and all the records currently loaded in the list
(``active_ids``, may be just a subset of the database records
matching the current search)
``name``
see ``type````args``
see ``type````attrs``
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)
``states``
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
``context``
merged into the view's context when performing the button's Odoo call
``confirm``
confirmation message to display (and for the user to accept) before
performing the button's Odoo call
.. declared but unused: help
``field``
defines a column where the corresponding field should be displayed for
each record. Can use the following attributes:
``name``
the name of the field to display in the current model. A given name
can only be used once per view
``string``
the title of the field's column (by default, uses the ``string`` of
the model's field)
``invisible``
fetches and stores the field, but doesn't display the column in the
table. Necessary for fields which shouldn't be displayed but are
used by e.g. ``@colors````groups``
lists the groups which should be able to see the field
``widget``
alternate representations for a field's display. Possible list view
values are:
``progressbar``
displays ``float`` fields as a progress bar.
``many2onebutton``
replaces the m2o field's value by a checkmark if the field is
filled, and a cross if it is not
``handle``
for ``sequence`` fields, instead of displaying the field's value
just displays a dra&drop icon
``sum``, ``avg``
displays the corresponding aggregate at the bottom of the column. The
aggregation is only computed on *currently displayed* records. The
aggregation operation must match the corresponding field's
``group_operator````attrs``
dynamic attributes based on record values. Only effects the current
field, so e.g. ``invisible`` will hide the field but leave the same
field of other records visible, it will not hide the column itself
.. note:: if the list view is ``editable``, any field attribute from the
:ref:`form view ` is also valid and will
be used when setting up the inline form view
.. _reference/views/form:
Forms
=====
Form views are used to display the data from a single record. Their root
element is ``. They are composed of regular HTML_ with additional
structural and semantic components.
Structural 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 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
``newline``
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
title
``sheet``
can be used as a direct child to ``form`` for a narrower and more responsive
form layout
``header``
combined with ``sheet``, provides a full-width location above the sheet
itself, generally used to display workflow buttons and status widgets
Semantic components
-------------------
Semantic components tie into and allow interaction with the Odoo
system. Available semantic components are:
``button``
call into the Odoo system, similar to :ref:`list view buttons
`
``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. :class:`~openerp.fields.Char`,
:class:`~openerp.fields.Many2one`). The ``widget`` attributes allows using
a different rendering method and context.
.. todo:: list of widgets
& options & specific attributes (e.g. widget=statusbar
statusbar_visible statusbar_colors 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
:class:`~openerp.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
.. deprecated:: 8.0
Use :func:`openerp.api.onchange` on the model
``attrs``
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`` element
``placeholder``
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 :class:`~openerp.fields.One2many`, display mode (view type) to use for
the field's linked records. One of ``tree``, ``form``, ``kanban`` or
``graph``. The default is ``tree`` (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 :class:`~openerp.fields.Char` field stores a password and
that its data shouldn't be displayed
.. todo:: classes for forms
.. todo:: widgets?
Business Views guidelines
-------------------------
.. sectionauthor:: Aline Preillon, Raphael Collet
Business views are targeted at regular users, not advanced users. Examples
are: Opportunities, Products, Partners, Tasks, Projects, etc.
.. image:: forms/oppreadonly.png
:class: img-responsive
In general, a business view is composed of
1. a status bar on top (with technical or business flow),
2. a sheet in the middle (the form itself),
3. a bottom part with History and Comments.
Technically, the new form views are structured as follows in XML::
... content of the status bar ... ... content of the sheet ...
... content of the bottom part ...
The Status Bar
''''''''''''''
The purpose of the status bar is to show the status of the current record and
the action buttons.
.. image:: forms/status.png
:class: img-responsive
The Buttons
...........
The order of buttons follows the business flow. For instance, in a sale order,
the logical steps are:
1. Send the quotation
2. Confirm the quotation
3. Create the final invoice
4. 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,
:guilabel:`cancel` buttons *must* remain grey (normal). For instance, in
Invoice the button :guilabel:`Refund` must never be red.
Technically, buttons are highlighted by adding the class "oe_highlight"::
The Status
..........
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.
.. image:: forms/status1.png
:class: img-responsive
.. image:: forms/status2.png
:class: img-responsive
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.
::
statusbar_visible="draft,sent,progress,invoiced,done"
statusbar_colors="{'shipping_except':'red','waiting_date':'blue'}"/>
The Sheet
'''''''''
All business views should look like a printed sheet:
.. image:: forms/sheet.png
:class: img-responsive
1. Elements inside a `` or ```` do not define groups, elements
inside them are laid out according to normal HTML rules. They content can
be explicitly grouped using ```` or regular ``
`` elements.
2. By default, the element ```` 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 ```` element to produce a column of fields.
3. To give a title to a section, add a ``string`` attribute to a ```` element::
this replaces the former use of ````.
4. The ```` element does not produce a label, except as direct children
of a ```` element\ [#backwards-compatibility]_. Use :samp:`
public interface IStack<T> {
//元素出栈，并返回出栈元素
public T pop();
//元素入栈
public void push(T element);
//获取栈顶元素
public T peek();
//判断栈是否为空
public boolean isEmpty
