: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 ``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:`~odoo.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 ``banner_route`` a route address to be fetched and prepended to the view. If this attribute is set, the :ref:`controller route url` will be fetched and displayed above the view. The json response from the controller should contain an "html" key. If the html contains a stylesheet tag, it will be removed and appended to . To interact with the backend you can use tags. Please take a look at the documentation of the _onActionClicked method of AbstractController (*addons/web/static/src/js/views/abstract_controller.js*) for more details. Only views extending AbstractView and AbstractController can use this attribute, like :ref:`reference/views/form`, :ref:`reference/views/kanban`, :ref:`reference/views/list`, ... Example: .. code-block:: xml .. code-block:: python class MyController(odoo.http.Controller): @http.route('/module_name/hello', auth='user', type='json') def hello(self): return { 'html': """

hello, world

""" } .. _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 ----------------- 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 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``. All other attributes are ignored during matching * any other element: the first element with the same name and identical attributes (ignoring ``position`` and ``version`` 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 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 Additionally, the ``position`` ``move`` can be used as a direct child of a spec with a ``inside``, ``replace``, ``after`` or ``before`` ``position`` attribute to move a node. .. code-block:: xml 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 ``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``). ``create``, ``edit``, ``delete``, ``duplicate``, ``import`` allows *dis*\ abling the corresponding action in the view by setting the corresponding attribute to ``false`` ``limit`` the default size of a page. It must be a positive integer ``groups_limit`` when the list view is grouped, the default number of groups of a page. It must be a position integer ``expand`` when the list view is grouped, automatically open the first level of groups if set to true (default: false) 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: ``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 attribute is ``invisible`` (hides the button). ``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 .. danger:: Using ``states`` in combination with ``attrs`` may lead to unexpected results as domains are combined with a logical AND. ``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 (among others): ``progressbar`` displays ``float`` fields as a progress bar. ``handle`` for ``sequence`` (or ``integer``) fields by which records are sorted, instead of displaying the field's value just displays a drag&drop icon to reorder records. ``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 ``width_factor`` (for ``editable``) the column relative width (as the layout is fixed) ``width`` (for ``editable``) the column width (as the layout is fixed) .. 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 ``groupby`` defines custom headers (with buttons) for the current view when grouping records on many2one fields. It is also possible to add `field`, inside the `groupby` which can be used for modifiers. These fields thus belong on the many2one comodel. These extra fields will be fetched in batch. ``name`` the name of a many2one field (on the current model). Custom header will be displayed when grouping the view on this field name (only for first level). .. code-block:: xml