: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:`~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 ``colors`` .. deprecated:: 9.0 replaced by ``decoration-{$name}`` ``fonts`` .. deprecated:: 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 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`` allows *dis*\ abling the corresponding action in the view by setting the corresponding attribute to ``false`` ``limit`` the default size of a page. It should be a positive integer ``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: ``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: ``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 drag&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 ``control`` defines custom controls for the current view. This makes sense if the parent ``tree`` view is inside a One2many field. Does not support any attribute, but can have children: ``create`` adds a button to create a new element on the current list. .. note:: If any ``create`` is defined, it will overwrite the default "add a line" button. The following attributes are supported: ``string`` (required) The text displayed on the button. ``context`` This context will be merged into the existing context when retrieving the default value of the new record. For example it can be used to override default values. The following example will override the default "add a line" button by replacing it with 3 new buttons: "Add a product", "Add a section" and "Add a note". "Add a product" will set the field 'display_type' to its default value. The two other buttons will set the field 'display_type' to be respectively 'line_section' and 'line_note'. .. code-block:: xml .. _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 `. In addition, the following attribute can be specified: ``special`` for form views opened in dialogs: ``save`` to save the record and close the dialog, ``cancel`` to close the dialog without saving. ``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:`~odoo.fields.Char`, :class:`~odoo.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 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:`~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 .. deprecated:: 8.0 Use :func:`odoo.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:`~odoo.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:`~odoo.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"::