: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"::