[IMP] developer/views: apply the new API references style

The documentation of view attributes was lacking visual structure to
help the reader figure out which attribute relates to which parent
element. Since this documentation was relying on RST block quotes to
represent the hierarchy of view attributes, we can apply the same new
styling that was added with commit 934f45cf and designed for autodoc,
and which relies on the exact same HTML structure as block quotes.

task-2755298

closes odoo/documentation#2324

Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>
This commit is contained in:
Antoine Vandevenne (anv) 2022-06-21 12:45:35 +00:00
parent 934f45cf4d
commit 120ae78553
2 changed files with 182 additions and 65 deletions

View File

@ -258,6 +258,8 @@ There are three types of element locators for matching a target element:
The inheritance spec may have an optional ``position`` attribute specifying
how the matched node should be altered:
.. rst-class:: o-definition-list
``inside`` (default)
the content of the inheritance spec is appended to the matched node
``replace``
@ -343,12 +345,16 @@ attributes:
Possible children of the view element are:
.. rst-class:: o-definition-list
``field``
declares fields to use in activity *logic*. If the field is simply displayed
in the activity view, it does not need to be pre-declared.
Possible attributes are:
.. rst-class:: o-definition-list
``name`` (required)
the name of the field to fetch
@ -362,6 +368,8 @@ Possible children of the view element are:
<reference/qweb/javascript>` and provides the following context variables
(see :ref:`reference/views/kanban` for more details):
.. rst-class:: o-definition-list
``widget``
the current :js:class:`ActivityRecord`, can be used to fetch some
meta-information. These methods are also available directly in the
@ -379,6 +387,8 @@ 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:
.. rst-class:: o-definition-list
``date_start`` (required)
name of the record's field holding the start date for the event
``date_stop``
@ -458,34 +468,35 @@ For example, here is a very simple cohort view:
The root element of the Cohort view is <cohort>, it accepts the following
attributes:
.. rst-class:: o-definition-list
- ``string`` (mandatory)
``string`` (mandatory)
A title, which should describe the view
- ``date_start`` (mandatory)
``date_start`` (mandatory)
A valid date or datetime field. This field is understood by the view as the
beginning date of a record
- ``date_stop`` (mandatory)
``date_stop`` (mandatory)
A valid date or datetime field. This field is understood by the view as the
end date of a record. This is the field that will determine the churn.
- ``mode`` (optional)
``mode`` (optional)
A string to describe the mode. It should be either 'churn' or
'retention' (default). Churn mode will start at 0% and accumulate over time
whereas retention will start at 100% and decrease over time.
- ``timeline`` (optional)
``timeline`` (optional)
A string to describe the timeline. It should be either 'backward' or 'forward' (default).
Forward timeline will display data from date_start to date_stop, whereas backward timeline
will display data from date_stop to date_start (when the date_start is in future / greater
than date_stop).
- ``interval`` (optional)
``interval`` (optional)
A string to describe a time interval. It should be 'day', 'week', 'month''
(default) or 'year'.
- ``measure`` (optional)
``measure`` (optional)
A field that can be aggregated. This field will be used to compute the values
for each cell. If not set, the cohort view will count the number of occurrences.
@ -524,19 +535,23 @@ attributes.
There are 5 possible type of tags in a dashboard view:
.. rst-class:: o-definition-list
``view``
declares a sub view.
Admissible attributes are:
- ``type`` (mandatory)
.. rst-class:: o-definition-list
``type`` (mandatory)
The type of the sub view. For example, *graph* or *pivot*.
- ``ref`` (optional)
``ref`` (optional)
An xml id for a view. If not given, the default view for the model will
be used.
- ``name`` (optional)
``name`` (optional)
A string which identifies this element. It is mostly
useful to be used as a target for an xpath.
@ -546,13 +561,15 @@ There are 5 possible type of tags in a dashboard view:
Admissible attributes are:
- ``string`` (optional)
.. rst-class:: o-definition-list
``string`` (optional)
A description which will be displayed as a group title.
- ``colspan`` (optional)
``colspan`` (optional)
The number of subcolumns in this group tag. By default, 6.
- ``col`` (optional)
``col`` (optional)
The number of columns spanned by this group tag (only makes sense inside
another group). By default, 6.
@ -566,31 +583,35 @@ There are 5 possible type of tags in a dashboard view:
Admissible attributes are:
- ``field`` (mandatory)
.. rst-class:: o-definition-list
``field`` (mandatory)
The field name to use for computing the aggregate. Possible field types
are:
- ``integer`` (default group operator is sum)
- ``float`` (default group operator is sum)
- ``many2one`` (default group operator is count distinct)
.. rst-class:: o-definition-list
- ``name`` (mandatory)
``integer`` (default group operator is sum)
``float`` (default group operator is sum)
``many2one`` (default group operator is count distinct)
``name`` (mandatory)
A string to identify this aggregate (useful for formulas)
- ``string`` (optional)
``string`` (optional)
A short description that will be displayed above the value. If not
given, it will fall back to the field string.
- ``domain`` (optional)
``domain`` (optional)
An additional restriction on the set of records that we want to aggregate.
This domain will be combined with the current domain.
- ``domain_label`` (optional)
``domain_label`` (optional)
When the user clicks on an aggregate with a domain, it will be added to
the search view as a facet. The string displayed for this facet can
be customized with this attribute.
- ``group_operator`` (optional)
``group_operator`` (optional)
A valid postgreSQL aggregate function identifier to use when aggregating
values (see https://www.postgresql.org/docs/9.5/static/functions-aggregate.html).
If not provided, By default, the group_operator from the field definition is used.
@ -604,18 +625,18 @@ There are 5 possible type of tags in a dashboard view:
- ``col`` (optional)
``col`` (optional)
The number of columns spanned by this tag (only makes sense inside a
group). By default, 1.
- ``widget`` (optional)
``widget`` (optional)
A widget to format the value (like the widget attribute for fields).
For example, monetary.
- ``help`` (optional)
``help`` (optional)
A help message to dipslay in a tooltip (equivalent of help for a field in python)
- ``measure`` (optional)
``measure`` (optional)
This attribute is the name of a field describing the measure that has to be used
in the graph and pivot views when clicking on the aggregate.
The special value __count__ can be used to use the count measure.
@ -624,12 +645,12 @@ There are 5 possible type of tags in a dashboard view:
<aggregate name="total_ojects" string="Total Objects" field="id" group_operator="count" measure="__count__"/>
- ``clickable`` (optional)
``clickable`` (optional)
A boolean indicating if this aggregate should be clickable or not (default to true).
Clicking on a clickable aggregate will change the measures used by the subviews
and add the value of the domain attribute (if any) to the search view.
- ``value_label`` (optional)
``value_label`` (optional)
A string put on the right of the aggregate value.
For example, it can be useful to indicate the unit of measure
of the aggregate value.
@ -642,30 +663,32 @@ There are 5 possible type of tags in a dashboard view:
Admissible attributes are:
- ``value`` (mandatory)
.. rst-class:: o-definition-list
``value`` (mandatory)
A string expression that will be evaluated, with the builtin python
evaluator (in the web client). Every aggregate can be used in the
context, in the ``record`` variable. For example,
``record.price_total / record.order_id``.
- ``name`` (optional)
``name`` (optional)
A string to identify this formula
- ``string`` (optional)
``string`` (optional)
A short description that will be displayed above the formula.
- ``col`` (optional)
``col`` (optional)
The number of columns spanned by this tag (only makes sense inside a
group). By default, 1.
- ``widget`` (optional)
``widget`` (optional)
A widget to format the value (like the widget attribute for fields).
For example, monetary. By default, it is 'float'.
- ``help`` (optional)
``help`` (optional)
A help message to dipslay in a tooltip (equivalent of help for a field in python)
- ``value_label`` (optional)
``value_label`` (optional)
A string put on the right of the formula value.
For example, it can be useful to indicate the unit of measure
of the formula value.
@ -676,11 +699,13 @@ There are 5 possible type of tags in a dashboard view:
Admissible attributes are:
- ``name`` (mandatory)
.. rst-class:: o-definition-list
``name`` (mandatory)
A string to identify which widget should be instantiated. The view will
look into the ``widget_registry`` to get the proper class.
- ``col`` (optional)
``col`` (optional)
The number of columns spanned by this tag (only makes sense inside a
group). By default, 1.
@ -698,9 +723,13 @@ element is ``<diagram>`` and takes no attributes.
Possible children of the diagram view are:
.. rst-class:: o-definition-list
``node`` (required, 1)
Defines the nodes of the graph. Its attributes are:
.. rst-class:: o-definition-list
``object``
the node's Odoo model
``shape``
@ -711,9 +740,12 @@ Possible children of the diagram view are:
same as ``shape``, but conditionally maps a background color for
nodes. The default background color is white, the only valid alternative
is ``grey``.
``arrow`` (required, 1)
Defines the directed edges of the graph. Its attributes are:
.. rst-class:: o-definition-list
``object`` (required)
the edge's Odoo model
``source`` (required)
@ -747,15 +779,19 @@ Structural components
Structural components provide structure or "visual" features with little
logic. They are used as elements or sets of elements in form views.
.. rst-class:: o-definition-list
``notebook``
defines a tabbed section. Each tab is defined through a ``page`` child
element. Pages can have the following attributes:
* ``string`` (required)
.. rst-class:: o-definition-list
``string`` (required)
the title of the tab
* ``accesskey``
``accesskey``
an HTML accesskey_
* ``attrs``
``attrs``
standard dynamic attributes based on record values
.. note:: Note that ``notebook`` should not be placed within ``group``
@ -795,11 +831,15 @@ Semantic components
Semantic components tie into and allow interaction with the Odoo
system. Available semantic components are:
.. rst-class:: o-definition-list
``button``
call into the Odoo system, similar to :ref:`list view buttons
<reference/views/list/button>`. In addition, the following attribute can be
specified:
.. rst-class:: o-definition-list
``special``
for form views opened in dialogs: ``save`` to save the record and close the
dialog, ``cancel`` to close the dialog without saving.
@ -814,6 +854,8 @@ system. Available semantic components are:
the behavior is not guaranteed when several fields exist with different values
for modifier 'required'. Possible attributes of the field node are:
.. rst-class:: o-definition-list
``name`` (mandatory)
the name of the field to render
``widget``
@ -832,6 +874,8 @@ system. Available semantic components are:
``class``
HTML class to set on the generated element, common field classes are:
.. rst-class:: o-definition-list
``oe_inline``
prevent the usual line break following fields
``oe_left``, ``oe_right``
@ -938,6 +982,8 @@ 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:
.. rst-class:: o-definition-list
``date_start`` (required)
name of the field providing the start datetime of the event for each
record.
@ -998,27 +1044,27 @@ take the following attributes:
``precision``
JSON object specifying snapping precisions for the pills in each scale.
* Possible values for scale ``day`` are (default: ``hour``):
Possible values for scale ``day`` are (default: ``hour``):
``hour``: records times snap to full hours (ex: 7:12 becomes 8:00)
- ``hour``: records times snap to full hours (ex: 7:12 becomes 8:00)
``hour:half``: records times snap to half hours (ex: 7:12 becomes 7:30)
- ``hour:half``: records times snap to half hours (ex: 7:12 becomes 7:30)
``hour:quarter``: records times snap to half hours (ex: 7:12 becomes 7:15)
- ``hour:quarter``: records times snap to half hours (ex: 7:12 becomes 7:15)
* Possible values for scale ``week`` are (default: ``day:half``):
Possible values for scale ``week`` are (default: ``day:half``):
``day``: records times snap to full days (ex: 7:28 AM becomes 11:59:59 PM of the previous day, 10:32 PM becomes 12:00 PM of the current day)
- ``day``: records times snap to full days (ex: 7:28 AM becomes 11:59:59 PM of the previous day, 10:32 PM becomes 12:00 PM of the current day)
``day:half``: records times snap to half hours (ex: 7:28 AM becomes 12:00 PM)
- ``day:half``: records times snap to half hours (ex: 7:28 AM becomes 12:00 PM)
* Possible values for scale ``month`` are (default: ``day:half``):
Possible values for scale ``month`` are (default: ``day:half``):
``day``: records times snap to full days (ex: 7:28 AM becomes 11:59:59 PM of the previous day, 10:32 PM becomes 12:00 PM of the current day)
- ``day``: records times snap to full days (ex: 7:28 AM becomes 11:59:59 PM of the previous day, 10:32 PM becomes 12:00 PM of the current day)
``day:half``: records times snap to half hours (ex: 7:28 AM becomes 12:00 PM)
- ``day:half``: records times snap to half hours (ex: 7:28 AM becomes 12:00 PM)
* Scale ``year`` always snap to full day.
Scale ``year`` always snap to full day.
Example of precision attribute: ``{"day": "hour:quarter", "week": "day:half", "month": "day"}``
``total_row``
@ -1050,6 +1096,8 @@ take the following attributes:
The gantt view uses mostly-standard :ref:`javascript qweb
<reference/qweb/javascript>` and provides the following context variables:
.. rst-class:: o-definition-list
``widget``
the current :js:class:`GanttRow`, can be used to fetch some
meta-information. The ``getColor`` method to convert in a color integer is
@ -1092,6 +1140,8 @@ 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:
.. rst-class:: o-definition-list
``type``
one of ``bar`` (default), ``pie`` and ``line``, the type of graph to use
``stacked``
@ -1101,6 +1151,8 @@ attributes:
The only allowed element within a graph view is ``field`` which can have the
following attributes:
.. rst-class:: o-definition-list
``name`` (required)
the name of a field to use in the view. If used for grouping (rather
than aggregating)
@ -1112,6 +1164,8 @@ following attributes:
indicates whether the field should be used as a grouping criteria or as an
aggregated value within a group. Possible values are:
.. rst-class:: o-definition-list
``row`` (default)
groups by the specified field. All graph types support at least one level
of grouping, some may support more.
@ -1152,6 +1206,8 @@ 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:
.. rst-class:: o-definition-list
``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
@ -1187,12 +1243,16 @@ attributes:
Possible children of the view element are:
.. rst-class:: o-definition-list
``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:
.. rst-class:: o-definition-list
``name`` (required)
the name of the field to fetch
@ -1201,6 +1261,8 @@ Possible children of the view element are:
Possible attributes are:
.. rst-class:: o-definition-list
``field`` (required)
the name of the field whose values are used to subgroup column's records in
the progressbar
@ -1223,6 +1285,8 @@ Possible children of the view element are:
The kanban view uses mostly-standard :ref:`javascript qweb
<reference/qweb/javascript>` and provides the following context variables:
.. rst-class:: o-definition-list
``widget``
the current :js:class:`KanbanRecord`, can be used to fetch some
meta-information. These methods are also available directly in the
@ -1258,6 +1322,8 @@ Possible children of the view element are:
behavior depends on the corresponding widget. Possible values are (among
others):
.. rst-class:: o-definition-list
``handle``
for ``sequence`` (or ``integer``) fields by which records are
sorted, allows to drag&drop records to reorder them.
@ -1267,6 +1333,8 @@ Possible children of the view element are:
* buttons and links with a ``type`` attribute become perform Odoo-related
operations rather than their standard HTML function. Possible types are:
.. rst-class:: o-definition-list
``action``, ``object``
standard behavior for :ref:`Odoo buttons
<reference/views/list/button>`, most attributes relevant to standard
@ -1291,6 +1359,8 @@ List
The root element of list views is ``<tree>``\ [#treehistory]_. The list view's
root can have the following attributes:
.. rst-class:: o-definition-list
``editable``
by default, selecting a list view's row opens the corresponding
:ref:`form view <reference/views/form>`. The ``editable`` attributes makes
@ -1343,9 +1413,13 @@ Possible children elements of the list view are:
.. _reference/views/list/button:
.. rst-class:: o-definition-list
``button``
displays a button in a list cell
.. rst-class:: o-definition-list
``icon``
icon to use to display the button
``string``
@ -1354,6 +1428,8 @@ Possible children elements of the list view are:
``type``
type of button, indicates how it clicking it affects Odoo:
.. rst-class:: o-definition-list
``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
@ -1403,6 +1479,8 @@ Possible children elements of the list view are:
defines a column where the corresponding field should be displayed for
each record. Can use the following attributes:
.. rst-class:: o-definition-list
``name``
the name of the field to display in the current model. A given name
can only be used once per view
@ -1419,6 +1497,8 @@ Possible children elements of the list view are:
alternate representations for a field's display. Possible list view
values are (among others):
.. rst-class:: o-definition-list
``progressbar``
displays ``float`` fields as a progress bar.
``handle``
@ -1472,6 +1552,8 @@ Possible children elements of the list view are:
`groupby` which can be used for modifiers. These fields thus belong on the
many2one comodel. These extra fields will be fetched in batch.
.. rst-class:: o-definition-list
``name``
the name of a many2one field (on the current model). Custom header will be
displayed when grouping the view on this field name.
@ -1494,14 +1576,20 @@ Possible children elements of the list view are:
Does not support any attribute, but can have children:
.. rst-class:: o-definition-list
``create``
adds a button to create a new element on the current list.
.. rst-class:: o-definition-list
.. note:: If any ``create`` is defined, it will overwrite the default
"add a line" button.
The following attributes are supported:
.. rst-class:: o-definition-list
``string`` (required)
The text displayed on the button.
@ -1571,6 +1659,9 @@ Structural components
The view's root element is ``<map>`` multiple attributes are allowed
.. rst-class:: o-definition-list
``res_partner``
Contains the res.partner many2one. If not provided the view will resort to create an empty map.
``default_order``
@ -1580,6 +1671,8 @@ The view's root element is ``<map>`` multiple attributes are allowed
The only element allowed within the ``<map>`` element is the ``<marker-popup>``. This element is able to contain multiple ``<field>`` elements. Each of these elements will be interpreted as a line in the marker's popup. The field's attributes are the following:
.. rst-class:: o-definition-list
``name``
The field to display.
``string``
@ -1604,6 +1697,8 @@ Pivot
The pivot view is used to visualize aggregations as a `pivot table`_. Its root
element is ``<pivot>`` which can take the following attributes:
.. rst-class:: o-definition-list
``disable_linking``
Set to ``True`` to remove table cell's links to list view.
``display_quantity``
@ -1621,6 +1716,8 @@ element is ``<pivot>`` which can take the following attributes:
The only allowed element within a pivot view is ``field`` which can have the
following attributes:
.. rst-class:: o-definition-list
``name`` (required)
the name of a field to use in the view. If used for grouping (rather
than aggregating)
@ -1633,6 +1730,8 @@ following attributes:
indicates whether the field should be used as a grouping criteria or as an
aggregated value within a group. Possible values are:
.. rst-class:: o-definition-list
``row`` (default)
groups by the specified field, each group gets its own row.
``col``
@ -1699,6 +1798,8 @@ The main additions of qweb-as-view to the basic qweb-as-template are:
* qweb-as-view rendering adds several items to the standard qweb rendering
context:
.. rst-class:: o-definition-list
``model``
the model to which the qweb view is bound
``domain``
@ -1734,6 +1835,8 @@ The root element of search views is ``<search>``. It takes no attributes.
Possible children elements of the search view are:
.. rst-class:: o-definition-list
``field``
fields define domains or contexts with user-provided values. When search
domains are generated, field domains are composed with one another and
@ -1741,6 +1844,8 @@ Possible children elements of the search view are:
Fields can have the following attributes:
.. rst-class:: o-definition-list
``name``
the name of the field to filter on
``string``
@ -1792,6 +1897,8 @@ Possible children elements of the search view are:
Filters can have the following attributes:
.. rst-class:: o-definition-list
``string`` (required)
the label of the filter
``domain`` (optional)
@ -1926,16 +2033,23 @@ Possible children elements of the search view are:
By default, the list and kanban views have the searchpanel enabled.
The search panel can be activated on other views with the attribute:
* ``view_types`` a comma separated list of view types on which to enable the search panel
.. rst-class:: o-definition-list
``view_types``
a comma separated list of view types on which to enable the search panel
default: 'tree,kanban'
This tool allows to quickly filter data on the basis of given fields. The fields
are specified as direct children of the ``searchpanel`` with tag name ``field``,
and the following attributes:
* ``name`` (mandatory) the name of the field to filter on
.. rst-class:: o-definition-list
* ``select`` determines the behavior and display. Possible values are
``name`` (mandatory)
the name of the field to filter on
``select``
determines the behavior and display. Possible values are
* ``one`` (default) at most one value can be selected. Supported field types are
many2one and selection.
@ -1953,7 +2067,10 @@ Possible children elements of the search view are:
Additional optional attributes are available in the ``multi`` case:
* ``domain``: determines conditions that the comodel records have to satisfy.
.. rst-class:: o-definition-list
``domain``:
determines conditions that the comodel records have to satisfy.
A domain might be used to express a dependency on another field (with select="one")
of the search panel. Consider

View File

@ -666,7 +666,7 @@ header {
@extend code;
}
dl.py, dl.js {
dl.py, dl.js, dl.o-definition-list {
> dd {
border-left: 3px solid $gray-lighter;
margin: 0;