[REF] doc: views documentation rework

closes odoo/odoo#44530

Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>
Co-authored-by: Antoine Vandevenne (anv) <anv@odoo.com>

1 files changed, 1124 insertions, 914 deletions

diff --git a/doc/reference/views.rst b/doc/reference/views.rst
index 5638314a68b..6104d6bc692 100644
--- a/doc/reference/views.rst
+++ b/doc/reference/views.rst
@@ -1,101 +1,195 @@
 :banner: banners/views.jpg
 
-.. highlight:: xml
 .. _reference/views:
 
 =====
 Views
 =====
 
+Views are what define how records should be displayed to end-users. They are specified in XML which
+means that they can be edited independently from the models that they represent. They are flexible
+and allow a high level of customization of the screens that they control. There exist various types
+of views. Each of them represents a mode of visualization: *form*, *list*, *kanban*, etc.
+
+.. todo:: Build doc of ir_ui_view.py ?
+
 .. _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 <reference/views/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<reference/controllers>` 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 <link> tag, it will be
-    removed and appended to <head>.
-
-    To interact with the backend you can use <a type="action"> 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:
+Generic structure
+=================
 
-    .. code-block:: xml
+Basic views generally share the common structure defined below. Placeholders are denoted in all
+caps.
+
+.. code-block:: xml
+
+    <record id="MODEL_view_TYPE" model="ir.ui.view">
+      <field name="name">NAME</field>
+      <field name="model">MODEL</field>
+      <field name="arch" type="xml">
+        <VIEW_TYPE>
+          <VIEW_SPECIFICATIONS/>
+        </VIEW_TYPE>
+      </field>
+    </record>
+
+Fields
+======
+
+View objects expose a number of fields. They are optional unless specified otherwise.
+
+* ``name`` (mandatory) :class:`~odoo.fields.Char`
+
+  Only useful as a mnemonic/description of the view when looking for one in a list of some sort.
+
+* ``model`` :class:`~odoo.fields.Char`
+
+  The model linked to the view, if applicable.
+
+* ``priority`` :class:`~odoo.fields.Integer`
+
+  When a view is requested by ``(model, type)``, the view matching the model and
+  the type, with the lowest priority will be returned (it is the default view).
+
+  It also defines the order of views application during :ref:`view
+  inheritance <reference/views/inheritance>`.
+
+* ``groups_id`` :class:`~odoo.fields.Many2many` -> :class:`odoo.addons.base.models.res_users.Groups`
+
+  The groups allowed to use/access the current view.
+
+  If the view extends an existing view, the extension will only be applied
+  for a given user if the user has access to the provided ``groups_id``.
+
+* ``arch`` :class:`~odoo.fields.Text`
+
+  The description of the view layout.
+
+Attributes
+==========
+
+.. todo::
+
+  view attributes & view element attributes
+  attrs & states attributes are missing generic information
+
+The different view types have a wide variety of attributes allowing customizations of
+the generic behaviors. Some main attributes will be explained here. They do not all have
+an impact on all view types.
+
+.. note:: The current context and user access rights may also impact the view abilities.
 
-        <tree banner_route="/module_name/hello" />
+.. todo:: info on create/... in the context ?
 
-    .. code-block:: python
+* ``create``
 
-        class MyController(odoo.http.Controller):
-            @http.route('/module_name/hello', auth='user', type='json')
-            def hello(self):
-                return {
-                    'html': """
-                        <div>
-                            <link href="/module_name/static/src/css/banner.css"
-                                rel="stylesheet">
-                            <h1>hello, world</h1>
-                        </div> """
-                }
+  Disable/enable record creation on the view.
+
+* ``edit`` (``form`` & ``list`` & ``gantt``)
+
+  Disable/enable record edition on the view.
+
+* ``delete`` (``form`` & ``list``)
+
+  Disable/enable record deletion on the view through the **Action** dropdown.
+
+* ``duplicate`` (``form`` & ``list``)
+
+  Disable/enable record duplication on the view through the **Action** dropdown.
+
+* ``decoration-$`` (``list`` & ``gantt``)
+
+  Define a conditional display of a record in 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``).
+
+  .. code-block:: xml
+
+    <tree decoration-info="state == 'draft'"
+      decoration-danger="state == 'help_needed'"
+      decoration-bf="state='busy'">
+      <TREE_VIEW_CONTENT>
+    </tree>
+
+  .. warning::
+     Supported values differ for the two view types. The Gantt view only supports ``success``,
+     ``info``, ``warning``, ``danger`` and ``secondary`` displays. The list view supports ``bf``,
+     ``it``, ``success``, ``info``, ``warning``, ``danger``, ``muted`` and ``primary`` displays.
+
+* ``banner_route``
+  a route address to be fetched and prepended to the view.
+
+  If this attribute is set, the
+  :ref:`controller route url<reference/controllers>` 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 <link> tag, it will be
+  removed and appended to <head>.
+
+  To interact with the backend you can use <a type="action"> 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
+
+      <tree banner_route="/module_name/hello" />
+
+  .. code-block:: python
+
+      class MyController(odoo.http.Controller):
+          @http.route('/module_name/hello', auth='user', type='json')
+          def hello(self):
+              return {
+                  'html': """
+                      <div>
+                          <link href="/module_name/static/src/css/banner.css"
+                              rel="stylesheet">
+                          <h1>hello, world</h1>
+                      </div> """
+              }
+
+.. todo:: Views main content section, with field, group & separator ?
 
 .. _reference/views/inheritance:
 
 Inheritance
 ===========
 
+Inheritance fields
+------------------
+
+The two following :class:`~odoo.addons.base.ir_ui_view.View` fields are used to specify
+inherited views.
+
+* ``inherit_id`` :class:`~odoo.fields.Many2one`
+
+  the current view's parent view, unset by default
+
+* ``mode`` :class:`~odoo.fields.Selection`: `extension / primary`
+
+  inheritance mode, ``extension`` by default if ``inherit_id`` is set,
+  ``primary`` otherwise.
+
 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
+  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
+  *closest* parent with mode ``primary`` is matched.
 
 View resolution
 ---------------
@@ -112,6 +206,8 @@ view:
 
 The result of applying children views yields the final ``arch``
 
+.. todo:: NOTE on fields_view_get and link to ORM ?
+
 Inheritance specs
 -----------------
 
@@ -129,6 +225,20 @@ There are three types of element locators for matching a target element:
 * any other element: the first element with the same name and identical
   attributes (ignoring ``position`` and ``version`` attributes) is matched
 
+.. code-block:: xml
+
+  <xpath expr="page[@name='pg']/group[@name='gp']/field" position="inside">
+    <field name="description"/>
+  </xpath>
+
+  <field name="res_id" position="after"/>
+
+  <div name="name" position="replace">
+    <div name="name2">
+      <field name="name2"/>
+    </div>
+  </div>
+
 The inheritance spec may have an optional ``position`` attribute specifying
 how the matched node should be altered:
 
@@ -156,297 +266,455 @@ how the matched node should be altered:
       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
 
-.. code-block:: xml
+      <field name="sale_information" position="attributes">
+        <attribute name="invisible">0</attribute>
+        <attribute name="attrs">
+          {'invisible': [('sale_ok', '=', False)], 'readonly': [('editable', '=', False)]}
+        </attribute>
+      </field>
 
-    <xpath expr="//@target" position="after">
-        <xpath expr="//@node" position="move"/>
-    </xpath>
+``move``
+  can be used as a direct child of a inheritance spec
+  with a ``inside``, ``replace``, ``after`` or ``before`` ``position`` attribute
+  to move a node.
 
-    <field name="target_field" position="after">
-        <field name="my_field" position="move"/>
-    </field>
+  .. code-block:: xml
+
+      <xpath expr="//@target" position="after">
+          <xpath expr="//@node" position="move"/>
+      </xpath>
+
+      <field name="target_field" position="after">
+          <field name="my_field" position="move"/>
+      </field>
 
 
 A view's specs are applied sequentially.
 
-.. _reference/views/list:
+.. [#hasclass] an extension function is added for simpler matching in QWeb
+               views: ``hasclass(*classes)`` matches if the context node has
+               all the specified classes
 
-Lists
-=====
+.. _reference/views/types:
 
-The root element of list views is ``<tree>``\ [#treehistory]_. The list view's
-root can have the following attributes:
+View types
+==========
 
-``editable``
-    by default, selecting a list view's row opens the corresponding
-    :ref:`form view <reference/views/form>`. The ``editable`` attributes makes
-    the list view itself editable in-place.
+.. _reference/views/activity:
 
-    Valid values are ``top`` and ``bottom``, making *new* records appear
-    respectively at the top or bottom of the list.
+Activity
+--------
 
-    The architecture for the inline :ref:`form view <reference/views/form>` is
-    derived from the list view. Most attributes valid on a :ref:`form view
-    <reference/views/form>`'s fields and buttons are thus accepted by list
-    views although they may not have any meaning if the list view is
-    non-editable
+The Activity view is used to display the activities linked to the records. The
+data are displayed in a chart with the records forming the rows and the activity
+types the columns. The first cell of each row displays a (customizable, see
+``templates``, quite similarly to :ref:`reference/views/kanban`) card representing
+the corresponding record. When clicking on others cells, a detailed description
+of all activities of the same type for the record is displayed.
 
-    .. note:: if the ``edit`` attribute is set to ``false``, the ``editable`` option will be ignored.
+.. warning::
 
-``multi_edit``
-    editable or not editable list can activate the multi-edition feature by defining
-    the multi_edit=1
+   The Activity view is only available when the ``mail`` module is installed,
+   and for the models that inherit from the ``mail.activity.mixin``.
 
-``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:
+The root element of the Activity view is ``<activity>``, it accepts the following
+attributes:
 
-    .. code-block:: xml
+- ``string`` (mandatory)
+    A title, which should describe the view
 
-        <tree default_order="sequence,name desc">
-``decoration-{$name}``
-    allow changing the style of a row's text based on the corresponding
-    record's attributes.
+Possible children of the view element are:
 
-    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``).
+``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.
 
-    ``{$name}`` can be ``bf`` (``font-weight: bold``), ``it``
-    (``font-style: italic``), or any `bootstrap contextual color
-    <https://getbootstrap.com/docs/3.3/components/#available-variations>`_ (``danger``,
-    ``info``, ``muted``, ``primary``, ``success`` or ``warning``).
-``create``, ``edit``, ``delete``, ``duplicate``, ``import``, ``export_xlsx``
-    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 attributes are:
 
-Possible children elements of the list view are:
+  ``name`` (required)
+    the name of the field to fetch
 
-.. _reference/views/list/button:
+``templates``
+  defines the :ref:`reference/qweb` templates. Cards definition may be
+  split into multiple templates for clarity, but activity views *must* define at
+  least one root template ``activity-box``, which will be rendered once for each
+  record.
 
-``button``
-    displays a button in a list cell
+  The activity view uses mostly-standard :ref:`javascript qweb
+  <reference/qweb/javascript>` and provides the following context variables
+  (see :ref:`reference/views/kanban` for more details):
 
-    ``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:
+  ``widget``
+    the current :js:class:`ActivityRecord`, can be used to fetch some
+    meta-information. These methods are also available directly in the
+    template context and don't need to be accessed via ``widget``
+  ``record``
+    an object with all the requested fields as its attributes. Each field has
+    two attributes ``value`` and ``raw_value``
 
-        ``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.
+.. _reference/views/calendar:
 
-            .. web client also supports a @args, which allows providing
-               additional arguments as JSON. Should that be documented? Does
-               not seem to be used anywhere
+Calendar
+--------
 
-        ``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.
+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:
 
-        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.
+``date_start`` (required)
+    name of the record's field holding the start date for the event
+``date_stop``
+    name of the record's field holding the end date for the event, if
+    ``date_stop`` is provided records become movable (via drag and drop)
+    directly in the calendar
+``date_delay``
+    alternative to ``date_stop``, provides the duration of the event instead of
+    its end date (unit: day)
+``color``
+    name of a record field to use for *color segmentation*. Records in the
+    same color segment are allocated the same highlight color in the calendar,
+    colors are allocated semi-randomly.
+    Displayed the display_name/avatar of the visible record in the sidebar
+``form_view_id``
+    view to open when the user create or edit an event. Note that if this attribute
+    is not set, the calendar view will fall back to the id of the form view in the
+    current action, if any.
+``event_open_popup``
+    If the option 'event_open_popup' is set to true, then the calendar view will
+    open events (or records) in a FormViewDialog. Otherwise, it will open events
+    in a new form view (with a do_action)
+``quick_add``
+    enables quick-event creation on click: only asks the user for a ``name``
+    and tries to create a new event with just that and the clicked event
+    time. Falls back to a full form dialog if the quick creation fails
+``all_day``
+    name of a boolean field on the record indicating whether the corresponding
+    event is flagged as day-long (and duration is irrelevant)
+``mode``
+    Default display mode when loading the calendar.
+    Possible attributes are: ``day``, ``week``, ``month``
 
-        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.
+``<field>``
+  declares fields to aggregate or to use in kanban *logic*. If the field is
+  simply displayed in the calendar cards.
 
-        Makes the button ``invisible`` if the record is *not* in one of the
-        listed states
+  Fields can have additional attributes:
 
-        .. danger::
+  * ``invisible``
+    use "True" to hide the value in the cards
+  * ``avatar_field``
+    only for x2many field, to display the avatar instead of the display_name
+    in the cards
+  * ``write_model`` and ``write_field``
 
-            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
+    you can add a filter and save the result in the defined model, the
+    filter is added in the sidebar
+  * ``filter`` and ``color``
 
-    .. declared but unused: help
+    use "True" to add this field in filter in the sidebar. You can specify
+    a ``color`` field used to colorize the checkbox.
 
-``field``
-    defines a column where the corresponding field should be displayed for
-    each record. Can use the following attributes:
+``templates``
+  defines the :ref:`reference/qweb` template ``calendar-box``. Cards definition
+  may be split into multiple templates for clarity which will be rendered once
+  for each record.
 
-    ``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):
+  The kanban view uses mostly-standard :ref:`javascript qweb
+  <reference/qweb/javascript>` and provides the following context variables:
 
-        ``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`` (for ``editable``)
-        when there is no data in the list, the width of a column can be forced
-        by setting this attribute. The value can be an absolute width (e.g.
-        '100px'), or a relative weight (e.g. '3', meaning that this column will
-        be 3 times larger than the others). Note that when there are records in
-        the list, we let the browser automatically adapt the column's widths
-        according to their content, and this attribute is thus ignored.
+  ``widget``
+    the current :js:class:`KanbanRecord`, can be used to fetch some
+    meta-information. These methods are also available directly in the
+    template context and don't need to be accessed via ``widget``
+    ``getColor`` to convert in a color integer
+    ``getAvatars`` to convert in an avatar image
+    ``displayFields`` list of not invisible fields
+  ``record``
+    an object with all the requested fields as its attributes. Each field has
+    two attributes ``value`` and ``raw_value``
+  ``event``
+    the calendar event object
+  ``format``
+    format method to convert values into a readable string with the user
+    parameters
+  ``fields``
+    definition of all model fields
+    parameters
+  ``user_context``
+    self-explanatory
+  ``read_only_mode``
+    self-explanatory
 
-    .. note::
+.. _reference/views/cohort:
 
-        if the list view is ``editable``, any field attribute from the
-        :ref:`form view <reference/views/form>` is also valid and will
-        be used when setting up the inline form view.
+Cohort
+------
 
-    .. note::
+.. raw:: html
 
-        In case of list sub-views (One2many/Many2many display in a form view),
-        The attribute ``column_invisible`` can be useful to hide a column
-        depending on the parent object.
+   <span class="badge" style="background-color:#AD5E99">Enterprise feature</span>
+
+The cohort view is used to display and understand the way some data changes over
+a period of time.  For example, imagine that for a given business, clients can
+subscribe to some service.  The cohort view can then display the total number
+of subscriptions each month, and study the rate at which client leave the service
+(churn). When clicking on a cell, the cohort view will redirect you to a new action
+in which you will only see the records contained in the cell's time interval;
+this action contains a list view and a form view.
+
+.. note:: By default the cohort view will use the same list and form views as those
+   defined on the action. You can pass a list view and a form view
+   to the context of the action in order to set/override the views that will be
+   used (the context keys to use being `form_view_id` and `list_view_id`)
+
+For example, here is a very simple cohort view:
+
+.. code-block:: xml
+
+    <cohort string="Subscription" date_start="date_start" date_stop="date" interval="month"/>
+
+The root element of the Cohort view is <cohort>, it accepts the following
+attributes:
+
+
+- ``string`` (mandatory)
+    A title, which should describe the view
+
+- ``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)
+    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)
+    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)
+    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)
+    A string to describe a time interval. It should be 'day', 'week', 'month''
+    (default) or 'year'.
+
+- ``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.
+
+.. _reference/views/dashboard:
+
+Dashboard
+---------
+
+.. raw:: html
+
+   <span class="badge" style="background-color:#AD5E99">Enterprise feature</span>
+
+Like pivot and graph view, The dashboard view is used to display aggregate data.
+However, the dashboard can embed sub views, which makes it possible to have a
+more complete and interesting look on a given dataset.
+
+The dashboard view can display sub views, aggregates for some fields (over a
+domain), or even *formulas* (expressions which involves one or more aggregates).
+For example, here is a very simple dashboard:
+
+.. code-block:: xml
+
+    <dashboard>
+        <view type="graph" ref="sale_report.view_order_product_graph"/>
+        <group string="Sale">
+            <aggregate name="price_total" field="price_total" widget="monetary"/>
+            <aggregate name="order_id" field="order_id" string="Orders"/>
+            <formula name="price_average" string="Price Average"
+                value="record.price_total / record.order_id" widget="percentage"/>
+        </group>
+        <view type="pivot" ref="sale_report.view_order_product_pivot"/>
+    </dashboard>
+
+The root element of the Dashboard view is <dashboard>, it does not accept any
+attributes.
+
+There are 5 possible type of tags in a dashboard view:
+
+``view``
+    declares a sub view.
+
+    Admissible attributes are:
+
+    - ``type`` (mandatory)
+        The type of the sub view.  For example, *graph* or *pivot*.
+
+    - ``ref`` (optional)
+        An xml id for a view. If not given, the default view for the model will
+        be used.
+
+    - ``name`` (optional)
+        A string which identifies this element.  It is mostly
+        useful to be used as a target for an xpath.
+
+``group``
+    defines a column layout.  This is actually very similar to the group element
+    in a form view.
+
+    Admissible attributes are:
+
+    - ``string`` (optional)
+        A description which will be displayed as a group title.
+
+    - ``colspan`` (optional)
+        The number of subcolumns in this group tag. By default, 6.
+
+    - ``col`` (optional)
+        The number of columns spanned by this group tag (only makes sense inside
+        another group). By default, 6.
+
+
+``aggregate``
+    declares an aggregate.  This is the value of an aggregate for a given field
+    over the current domain.
+
+    Note that aggregates are supposed to be used inside a group tag (otherwise
+    the style will not be properly applied).
+
+    Admissible attributes are:
+
+    - ``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)
+
+    - ``name`` (mandatory)
+        A string to identify this aggregate (useful for formulas)
+
+    - ``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)
+        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)
+        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)
+        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.
+        Note that no aggregation of field values is achieved if the group_operator value is "".
+
+        .. note:: The special aggregate function ``count_distinct`` (defined in odoo) can also be used here
 
         .. code-block:: xml
 
-           <field name="product_is_late" attrs="{'column_invisible': [('parent.has_late_products', '=', False)]}"/>
+          <aggregate name="price_total_max" field="price_total" group_operator="max"/>
 
-    .. note:: When a list view is grouped, numeric fields are aggregated and
-              displayed for each group.  Also, if there are too many records in
-              a group, a pager will appear on the right of the group row. For
-              this reason, it is not a good practice to have a numeric field in
-              the last column, when the list view is in a situation where it can
-              be grouped (it is however fine for x2manys field in a form view:
-              they cannot be grouped).
 
-``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.
+    - ``col`` (optional)
+        The number of columns spanned by this tag (only makes sense inside a
+        group). By default, 1.
 
-  .. code-block:: xml
+    - ``widget`` (optional)
+        A widget to format the value (like the widget attribute for fields).
+        For example, monetary.
 
-    <groupby name="partner_id">
-      <field name="name"/> <!-- name of partner_id -->
-        <button type="edit" name"edit" string="Edit/>
-        <button type="object" name="my_method" string="Button1"
-          attrs="{'invisible': [('name', '=', 'Georges')]}"/>
-    </groupby>
+    - ``help`` (optional)
+        A help message to dipslay in a tooltip (equivalent of help for a field in python)
 
-  A special button (`type="edit"`) can be defined to open the many2one form view.
+    - ``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.
 
-``control``
-  defines custom controls for the current view.
+        .. code-block:: xml
 
-  This makes sense if the parent ``tree`` view is inside a One2many field.
+          <aggregate name="total_ojects" string="Total Objects" field="id" group_operator="count" measure="__count__"/>
 
-  Does not support any attribute, but can have children:
+    - ``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.
 
-  ``create``
-    adds a button to create a new element on the current list.
+    - ``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.
 
-    .. note:: If any ``create`` is defined, it will overwrite the default
-              "add a line" button.
+``formula``
+    declares a derived value.  Formulas are values computed from aggregates.
 
-    The following attributes are supported:
+    Note that like aggregates, formulas are supposed to be used inside a group
+    tag (otherwise the style will not be properly applied).
 
-    ``string`` (required)
-      The text displayed on the button.
+    Admissible attributes are:
 
-    ``context``
-      This context will be merged into the existing context
-      when retrieving the default value of the new record.
+    - ``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``.
 
-      For example it can be used to override default values.
+    - ``name`` (optional)
+        A string to identify this formula
 
+    - ``string`` (optional)
+        A short description that will be displayed above the formula.
 
-  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".
+    - ``col`` (optional)
+        The number of columns spanned by this tag (only makes sense inside a
+        group). By default, 1.
 
-  "Add a product" will set the field 'display_type' to its default value.
+    - ``widget`` (optional)
+        A widget to format the value (like the widget attribute for fields).
+        For example, monetary. By default, it is 'float'.
 
-  The two other buttons will set the field 'display_type'
-  to be respectively 'line_section' and 'line_note'.
+    - ``help`` (optional)
+        A help message to dipslay in a tooltip (equivalent of help for a field in python)
 
-  .. code-block:: xml
+    - ``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.
 
-    <control>
-      <create
-        string="Add a product"
-      />
-      <create
-        string="Add a section"
-        context="{'default_display_type': 'line_section'}"
-      />
-      <create
-        string="Add a note"
-        context="{'default_display_type': 'line_note'}"
-      />
-    </control>
+``widget``
+    Declares a specialized widget to be used to display the information. This is
+    a mechanism similar to the widgets in the form view.
+
+    Admissible attributes are:
+
+    - ``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)
+        The number of columns spanned by this tag (only makes sense inside a
+        group). By default, 1.
 
 .. _reference/views/form:
 
-Forms
-=====
+Form
+----
 
 Form views are used to display the data from a single record. Their root
 element is ``<form>``. 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.
@@ -455,11 +723,11 @@ logic. They are used as elements or sets of elements in form views.
   defines a tabbed section. Each tab is defined through a ``page`` child
   element. Pages can have the following attributes:
 
-  ``string`` (required)
+  * ``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``
@@ -494,7 +762,7 @@ logic. They are used as elements or sets of elements in form views.
   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:
@@ -588,14 +856,210 @@ system. Available semantic components are:
     for opening specific kanban view when selecting records from m2o/m2m in mobile
     environment
 
+Generic structure
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: xml
+
+  <form>
+    <sheet>
+      <header>
+        <field name="state"  widget="statusbar"/>
+      </header>
+      <div class="oe_button_box">
+        <BUTTONS/>
+      </div>
+      <group>
+        <group>
+          <field name="fname"/>
+        </group>
+      </group>
+      <notebook>
+        <page string="Page1">
+          <group>
+            <CONTENT/>
+          </group>
+        </page>
+        <page string="Page2">
+          <group>
+            <CONTENT/>
+          </group>
+        </page>
+      </notebook>
+    </sheet>
+  </form>
+
 .. todo:: classes for forms
 
 .. todo:: widgets?
 
+.. _reference/views/gantt:
+
+Gantt
+-----
+
+.. raw:: html
+
+   <span class="badge" style="background-color:#AD5E99">Enterprise feature</span>
+
+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:
+
+``date_start`` (required)
+  name of the field providing the start datetime of the event for each
+  record.
+``date_stop`` (required)
+  name of the field providing the end duration of the event for each
+  record.
+``color``
+  name of the field used to color the pills according to its value
+``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 one of the following `bootstrap contextual color`_ (``danger``,
+    ``info``, ``secondary``, ``success`` or ``warning``).
+``default_group_by``
+  name of a field to group tasks by
+``consolidation``
+  field name to display consolidation value in record cell
+``consolidation_max``
+  dictionnary with the "group by" field as key and the maximum consolidation
+  value that can be reached before displaying the cell in red
+  (e.g. ``{"user_id": 100}``)
+``consolidation_exclude``
+  name of the field that describes if the task has to be excluded
+  from the consolidation
+  if set to true it displays a striped zone in the consolidation line
+``create``, ``edit``, ``delete``, ``plan``
+    allows *dis*\ abling the corresponding action in the view by setting the
+    corresponding attribute to ``false``.
+
+    * ``create``: If enabled, a "**+**" button will be displayed
+      while hovering on a time slot to create a new record in that slots.
+    * ``edit``: If enabled, the opened records will be in edit mode (thus editable).
+    * ``plan``: If enabled and ``edit`` enabled, a "magnifying glass" button will be displayed
+      on time slots to plan unassigned records into that time slot.
+
+    .. admonition:: Example
+
+        When you do not want to create records on the gantt view and the beginning and end
+        dates are required on the model, the planning feature should be disabled
+        because no record will ever be found.
+``offset``
+  Depending on the scale, the number of units to add to today to compute the
+  default period. Examples: An offset of +1 in default_scale week will open the
+  gantt view for next week, and an offset of -2 in default_scale month will open
+  the gantt view of 2 months ago.
+``progress``
+  name of a field providing the completion percentage for the record's event,
+  between 0 and 100
+``string``
+  title of the gantt view
+``precision``
+  JSON object specifying snapping precisions for the pills in each scale.
+
+  * Possible values for scale ``day`` are (default: ``hour``):
+
+    ``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:quarter``: records times snap to half hours (ex: 7:12 becomes 7:15)
+
+  * 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:half``: records times snap to half hours (ex: 7:28 AM becomes 12:00 PM)
+
+  * 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:half``: records times snap to half hours (ex: 7:28 AM becomes 12:00 PM)
+
+  * Scale ``year`` always snap to full day.
+
+  Example of precision attribute: ``{"day": "hour:quarter", "week": "day:half", "month": "day"}``
+``total_row``
+  boolean to control whether the row containing the total count of records should
+  be displayed. (default: ``false``)
+``collapse_first_level``
+  boolean to control whether it is possible to collapse each row if grouped by
+  one field. (default: ``false``, the collapse starts when grouping by two fields)
+``display_unavailability``
+  boolean to mark the dates returned by the ``gantt_unavailability`` function of
+  the model as available inside the gantt view. Records can still be scheduled
+  in them, but their unavailability is visually displayed. (default: ``false``)
+``default_scale``
+  default scale when rendering the view. Possible values are (default: ``month``):
+
+  * ``day``
+  * ``week``
+  * ``month``
+  * ``year``
+
+``scales``
+  comma-separated list of allowed scales for this view. By default, all scales
+  are allowed. For possible scale values to use in this list, see ``default_scale``.
+
+``templates``
+  defines the :ref:`reference/qweb` template ``gantt-popover`` which is used
+  when the user hovers over one of the records in the gantt view.
+
+  The gantt view uses mostly-standard :ref:`javascript qweb
+  <reference/qweb/javascript>` and provides the following context variables:
+
+  ``widget``
+    the current :js:class:`GanttRow`, can be used to fetch some
+    meta-information. The ``getColor`` method to convert in a color integer is
+    also available directly in the template context without using ``widget``.
+
+  ``on_create``
+  If specified when clicking the add button on the view, instead of opening a generic dialog, launch a client action.
+  this should hold the xmlid of the action (eg: ``on_create="%(my_module.my_wizard)d"``
+
+``form_view_id``
+  view to open when the user create or edit a record. Note that if this attribute
+  is not set, the gantt view will fall back to the id of the form view in the
+  current action, if any.
+
+``dynamic_range``
+  if set to true, the gantt view will start at the first record,
+  instead of starting at the beginning of the year/month/day.
+
+``thumbnails``
+  This allows to display a thumbnail next to groups name if the group is a relationnal field.
+  This expects a python dict which keys are the name of the field on the active model.
+  Values are the names of the field holding the thumbnail on the related model.
+
+  Example: tasks have a field user_id that reference res.users. The res.users model has a field image that holds the avatar,
+  then:
+
+  .. code-block:: xml
+
+     <gantt
+        date_start="date_start"
+        date_stop="date_stop"
+        thumbnails="{'user_id': 'image_128'}"
+      >
+      </gantt>
+
+  will display the users avatars next to their names when grouped by user_id.
+
 .. _reference/views/graph:
 
-Graphs
-======
+Graph
+-----
 
 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
@@ -643,86 +1107,10 @@ sorted on the string of the field.
    graph view aggregations are performed on database content, non-stored
    function fields can not be used in graph views
 
-
-.. _reference/views/pivot:
-
-Pivots
-======
-
-The pivot view is used to visualize aggregations as a `pivot table`_. Its root
-element is ``<pivot>`` which can take the following attributes:
-
-``disable_linking``
-  Set to ``True`` to remove table cell's links to list view.
-``display_quantity``
-  Set to ``true`` to display the Quantity column by default.
-``default_order``
-  The name of the measure and the order (asc or desc) to use as default order
-  in the view.
-
-  .. code-block:: xml
-
-     <pivot default_order="foo asc">
-        <field name="foo" type="measure"/>
-     </pivot>
-
-The only allowed element within a pivot view is ``field`` which can have the
-following attributes:
-
-``name`` (required)
-  the name of a field to use in the view. If used for grouping (rather
-  than aggregating)
-
-``string``
-  the name that will be used to display the field in the pivot view,
-  overrides the default python String attribute of the field.
-
-``type``
-  indicates whether the field should be used as a grouping criteria or as an
-  aggregated value within a group. Possible values are:
-
-  ``row`` (default)
-    groups by the specified field, each group gets its own row.
-  ``col``
-    creates column-wise groups
-  ``measure``
-    field to aggregate within a group
-  ``interval``
-    on date and datetime fields, groups by the specified interval (``day``,
-    ``week``, ``month``, ``quarter`` or ``year``) instead of grouping on the
-    specific datetime (fixed second resolution) or date (fixed day resolution).
-
-``invisible``
-  if true, the field will not appear either in the active measures nor in the
-  selectable measures (useful for fields that do not make sense aggregated,
-  such as fields in different units, e.g. € and $).
-
-The measures are automatically generated from the model fields; only the
-aggregatable fields are used. Those measures are also alphabetically
-sorted on the string of the field.
-
-.. warning::
-
-    like the graph view, the pivot aggregates data on database content
-    which means that non-stored function fields can not be used in pivot views
-
-
-In Pivot view a ``field`` can have a ``widget`` attribute to dictate its format.
-The widget should be a field formatter, of which the most interesting are
-``date``, ``datetime``, ``float_time``, and ``monetary``.
-
-For instance a timesheet pivot view could be defined as::
-
-    <pivot string="Timesheet">
-        <field name="employee_id" type="row"/>
-        <field name="date" interval="month" type="col"/>
-        <field name="unit_amount" type="measure" widget="float_time"/>
-    </pivot>
-
 .. _reference/views/kanban:
 
 Kanban
-======
+------
 
 The kanban view is a `kanban board`_ visualisation: it displays records as
 "cards", halfway between a :ref:`list view <reference/views/list>` and a
@@ -761,14 +1149,15 @@ attributes:
   whether it should be possible to create records without switching to the
   form view. By default, ``quick_create`` is enabled when the Kanban view is
   grouped by many2one, selection, char or boolean fields, and disabled when not.
-``create``, ``edit``, ``delete``
-  allows *dis*\ abling the corresponding action in the view by setting the
-  corresponding attribute to ``false``
+``quick_create_view``
+  ``form`` view reference, specifying the view used for records quick creation.
 ``records_draggable``
   whether it should be possible to drag records when kanban is grouped. Default: true.
 
   Set to ``true`` to always enable it, and to ``false`` to always disable it.
 
+.. todo:: VFE missing information on on_create attribute of kanban views.
+
 Possible children of the view element are:
 
 ``field``
@@ -869,10 +1258,8 @@ Possible children of the view element are:
 
 If you need to extend the Kanban view, see :js:class::`the JS API <KanbanRecord>`.
 
-.. _reference/views/calendar:
-
 Calendar
-========
+~~~~~~~~
 
 Calendar views display records as events in a daily, weekly or monthly
 calendar. Their root element is ``<calendar>``. Available attributes on the
@@ -910,524 +1297,456 @@ calendar view are:
 ``mode``
     Default display mode when loading the calendar.
     Possible attributes are: ``day``, ``week``, ``month``
-``create``
-    allows *dis*\ abling the corresponding action in the view by setting the
-    corresponding attribute to ``false``
-``delete``
+``create``, ``delete``
     allows *dis*\ abling the corresponding action in the view by setting the
     corresponding attribute to ``false``
 ``<field>``
   declares fields to aggregate or to use in kanban *logic*. If the field is
   simply displayed in the calendar cards.
 
-  Fields can have additional attributes:
+.. _reference/views/list:
 
-    ``invisible``
-        use "True" to hide the value in the cards
-    ``avatar_field``
-        only for x2many field, to display the avatar instead the display_name
-        in the cards
-    ``write_model`` and ``write_field``
-        you can add a filter and save the result in the defined model, the
-        filter is added in the sidebar
-    ``filter`` and ``color``
-        use "True" to add this field in filter in the sidebar. You can specify
-        a color field used to colorize the checkbox.
+List
+----
 
-``templates``
-  defines the :ref:`reference/qweb` template ``calendar-box``. Cards definition
-  may be split into multiple templates for clarity which will be rendered once
-  for each record.
+The root element of list views is ``<tree>``\ [#treehistory]_. The list view's
+root can have the following attributes:
 
-  The kanban view uses mostly-standard :ref:`javascript qweb
-  <reference/qweb/javascript>` and provides the following context variables:
+``editable``
+    by default, selecting a list view's row opens the corresponding
+    :ref:`form view <reference/views/form>`. The ``editable`` attributes makes
+    the list view itself editable in-place.
 
-  ``widget``
-    the current :js:class:`KanbanRecord`, can be used to fetch some
-    meta-information. These methods are also available directly in the
-    template context and don't need to be accessed via ``widget``
-    ``getColor`` to convert in a color integer
-    ``getAvatars`` to convert in an avatar image
-    ``displayFields`` list of not invisible fields
-  ``record``
-    an object with all the requested fields as its attributes. Each field has
-    two attributes ``value`` and ``raw_value``
-  ``event``
-    the calendar event object
-  ``format``
-    format method to convert values into a readable string with the user
-    parameters
-  ``fields``
-    definition of all model fields
-    parameters
-  ``user_context``
-    self-explanatory
-  ``read_only_mode``
-    self-explanatory
+    Valid values are ``top`` and ``bottom``, making *new* records appear
+    respectively at the top or bottom of the list.
 
-.. _reference/views/gantt:
+    The architecture for the inline :ref:`form view <reference/views/form>` is
+    derived from the list view. Most attributes valid on a :ref:`form view
+    <reference/views/form>`'s fields and buttons are thus accepted by list
+    views although they may not have any meaning if the list view is
+    non-editable
 
-Gantt
-=====
+    .. note:: if the ``edit`` attribute is set to ``false``, the ``editable`` option will be ignored.
 
-Gantt views appropriately display Gantt charts (for scheduling).
+``multi_edit``
+    editable or not editable list can activate the multi-edition feature by defining
+    the `multi_edit=1`
 
-The root element of gantt views is ``<gantt/>``, it has no children but can
-take the following attributes:
+``default_order``
+    overrides the ordering of the view, replacing the model's order (:attr:`~odoo.models.BaseModel._order` model attribute).
+    The value is a comma-separated list of fields, postfixed by ``desc`` to
+    sort in reverse order:
+
+    .. code-block:: xml
+
+        <tree default_order="sequence,name desc">
 
-``date_start`` (required)
-  name of the field providing the start datetime of the event for each
-  record.
-``date_stop`` (required)
-  name of the field providing the end duration of the event for each
-  record.
-``color``
-  name of the field used to color the pills according to its value
 ``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 any `bootstrap contextual color
-    <https://getbootstrap.com/docs/3.3/components/#available-variations>`_ (``danger``,
+    ``{$name}`` can be ``bf`` (``font-weight: bold``), ``it``
+    (``font-style: italic``), or any `bootstrap contextual color`_ (``danger``,
     ``info``, ``muted``, ``primary``, ``success`` or ``warning``).
-``default_group_by``
-  name of a field to group tasks by
-``consolidation``
-  field name to display consolidation value in record cell
-``consolidation_max``
-  dictionnary with the "group by" field as key and the maximum consolidation
-  value that can be reached before displaying the cell in red
-  (e.g. ``{"user_id": 100}``)
-``consolidation_exclude``
-  name of the field that describes if the task has to be excluded
-  from the consolidation
-  if set to true it displays a striped zone in the consolidation line
-``create``, ``edit``, ``delete``, ``plan``
+``create``, ``edit``, ``delete``, ``duplicate``, ``import``, ``export_xlsx``
     allows *dis*\ abling the corresponding action in the view by setting the
-    corresponding attribute to ``false``. If ``create`` is enabled, a "+" button
-    will be displayed while hovering each time slot to create a new record in
-    that slot, and if ``edit`` is enabled, a "magnifying glass" button will be
-    displayed to plan records into that time slot.
-``offset``
-  Depending on the scale, the number of units to add to today to compute the
-  default period. Examples: An offset of +1 in default_scale week will open the
-  gantt view for next week, and an offset of -2 in default_scale month will open
-  the gantt view of 2 months ago.
-``progress``
-  name of a field providing the completion percentage for the record's event,
-  between 0 and 100
-``string``
-  title of the gantt view
-``precision``
-  JSON object specifying snapping precisions for the pills in each scale.
-
-  * Possible values for scale ``day`` are (default: ``hour``):
-
-    ``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:quarter``: records times snap to half hours (ex: 7:12 becomes 7:15)
-
-  * 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:half``: records times snap to half hours (ex: 7:28 AM becomes 12:00 PM)
-
-  * 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)
+    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)
 
-    ``day:half``: records times snap to half hours (ex: 7:28 AM becomes 12:00 PM)
+Possible children elements of the list view are:
 
-  * Scale ``year`` always snap to full day.
+.. _reference/views/list/button:
 
-  Example of precision attribute: ``{"day": "hour:quarter", "week": "day:half", "month": "day"}``
-``total_row``
-  boolean to control whether the row containing the total count of records should
-  be displayed. (default: ``false``)
-``collapse_first_level``
-  boolean to control whether it is possible to collapse each row if grouped by
-  one field. (default: ``false``, the collapse starts when grouping by two fields)
-``display_unavailability``
-  boolean to mark the dates returned by the ``gantt_unavailability`` function of
-  the model as available inside the gantt view. Records can still be scheduled
-  in them, but their unavailability is visually displayed. (default: ``false``)
-``default_scale``
-  default scale when rendering the view. Possible values are (default: ``month``):
+``button``
+    displays a button in a list cell
 
-  * ``day``
-  * ``week``
-  * ``month``
-  * ``year``
-``scales``
-  comma-separated list of allowed scales for this view. By default, all scales
-  are allowed. For possible scale values to use in this list, see ``default_scale``.
+    ``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:
 
-``templates``
-  defines the :ref:`reference/qweb` template ``gantt-popover`` which is used
-  when the user hovers over one of the records in the gantt view.
+        ``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.
 
-  The gantt view uses mostly-standard :ref:`javascript qweb
-  <reference/qweb/javascript>` and provides the following context variables:
+            .. web client also supports a @args, which allows providing
+               additional arguments as JSON. Should that be documented? Does
+               not seem to be used anywhere
 
-  ``widget``
-    the current :js:class:`GanttRow`, can be used to fetch some
-    meta-information. The ``getColor`` method to convert in a color integer is
-    also available directly in the template context without using ``widget``.
+        ``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.
 
-  ``on_create``
-  If specified when clicking the add button on the view, instead of opening a generic dialog, launch a client action.
-  this should hold the xmlid of the action (eg: ``on_create="%(my_module.my_wizard)d"``
+        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.
 
-``form_view_id``
-  view to open when the user create or edit a record. Note that if this attribute
-  is not set, the gantt view will fall back to the id of the form view in the
-  current action, if any.
+        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.
 
-``dynamic_range``
-  if set, the gantt view will start at the first record, instead of starting
-  at the beginning of the year/month/day.
+        Makes the button ``invisible`` if the record is *not* in one of the
+        listed states
 
-``thumbnails``
-  This allows to display a thumbnail next to groups name if the group is a relationnal field.
-  This expects a python dict which keys are the name of the field on the active model.
-  Values are the names of the field holding the thumbnail on the related model.
+        .. danger::
 
-  Example: tasks have a field user_id that reference res.users. The res.users model has a field image that holds the avatar,
-  then:
+            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
 
-  .. code-block:: xml
+    .. todo:: declared but unused: help
 
-     <gantt
-        date_start="date_start"
-        date_stop="date_stop"
-        thumbnails="{'user_id': 'image_128'}"
-      >
-      </gantt>
+``field``
+    defines a column where the corresponding field should be displayed for
+    each record. Can use the following attributes:
 
-  will display the users avatars next to their names when grouped by user_id.
+    ``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):
 
-.. _reference/views/dashboard:
+        ``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`` (for ``editable``)
+        when there is no data in the list, the width of a column can be forced
+        by setting this attribute. The value can be an absolute width (e.g.
+        '100px'), or a relative weight (e.g. '3', meaning that this column will
+        be 3 times larger than the others). Note that when there are records in
+        the list, we let the browser automatically adapt the column's widths
+        according to their content, and this attribute is thus ignored.
 
-Dashboard
-=========
+    .. note::
 
-Like pivot and graph view, The dashboard view is used to display aggregate data.
-However, the dashboard can embed sub views, which makes it possible to have a
-more complete and interesting look on a given dataset.
+        if the list view is ``editable``, any field attribute from the
+        :ref:`form view <reference/views/form>` is also valid and will
+        be used when setting up the inline form view.
 
-.. warning::
+    .. note::
 
-   The Dashboard view is only available in Odoo Enterprise.
+        In case of list sub-views (One2many/Many2many display in a form view),
+        The attribute ``column_invisible`` can be useful to hide a column
+        depending on the parent object.
 
-The dashboard view can display sub views, aggregates for some fields (over a
-domain), or even *formulas* (expressions which involves one or more aggregates).
-For example, here is a very simple dashboard:
+        .. code-block:: xml
 
-.. code-block:: xml
+           <field name="product_is_late" attrs="{'column_invisible': [('parent.has_late_products', '=', False)]}"/>
 
-    <dashboard>
-        <view type="graph" ref="sale_report.view_order_product_graph"/>
-        <group string="Sale">
-            <aggregate name="price_total" field="price_total" widget="monetary"/>
-            <aggregate name="order_id" field="order_id" string="Orders"/>
-            <formula name="price_average" string="Price Average"
-                value="record.price_total / record.order_id" widget="percentage"/>
-        </group>
-        <view type="pivot" ref="sale_report.view_order_product_pivot"/>
-    </dashboard>
+    .. note:: When a list view is grouped, numeric fields are aggregated and
+              displayed for each group.  Also, if there are too many records in
+              a group, a pager will appear on the right of the group row. For
+              this reason, it is not a good practice to have a numeric field in
+              the last column, when the list view is in a situation where it can
+              be grouped (it is however fine for x2manys field in a form view:
+              they cannot be grouped).
 
-The root element of the Dashboard view is <dashboard>, it does not accept any
-attributes.
+``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.
 
-There are 5 possible type of tags in a dashboard view:
+  ``name``
+      the name of a many2one field (on the current model). Custom header will be
+      displayed when grouping the view on this field name.
 
-``view``
-    declares a sub view.
+  .. code-block:: xml
 
-    Admissible attributes are:
+    <groupby name="partner_id">
+      <field name="name"/> <!-- name of partner_id -->
+        <button type="edit" name"edit" string="Edit/>
+        <button type="object" name="my_method" string="Button1"
+          attrs="{'invisible': [('name', '=', 'Georges')]}"/>
+    </groupby>
 
-    - ``type`` (mandatory)
-        The type of the sub view.  For example, *graph* or *pivot*.
+  A special button (`type="edit"`) can be defined to open the many2one form view.
 
-    - ``ref`` (optional)
-        An xml id for a view. If not given, the default view for the model will
-        be used.
+``control``
+  defines custom controls for the current view.
 
-    - ``name`` (optional)
-        A string which identifies this element.  It is mostly
-        useful to be used as a target for an xpath.
+  This makes sense if the parent ``tree`` view is inside a One2many field.
 
-``group``
-    defines a column layout.  This is actually very similar to the group element
-    in a form view.
+  Does not support any attribute, but can have children:
 
-    Admissible attributes are:
+  ``create``
+    adds a button to create a new element on the current list.
 
-    - ``string`` (optional)
-        A description which will be displayed as a group title.
+    .. note:: If any ``create`` is defined, it will overwrite the default
+              "add a line" button.
 
-    - ``colspan`` (optional)
-        The number of subcolumns in this group tag. By default, 6.
+    The following attributes are supported:
 
-    - ``col`` (optional)
-        The number of columns spanned by this group tag (only makes sense inside
-        another group). By default, 6.
+    ``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.
 
-``aggregate``
-    declares an aggregate.  This is the value of an aggregate for a given field
-    over the current domain.
+      For example it can be used to override default values.
 
-    Note that aggregates are supposed to be used inside a group tag (otherwise
-    the style will not be properly applied).
 
-    Admissible attributes are:
+  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".
 
-    - ``field`` (mandatory)
-        The field name to use for computing the aggregate. Possible field types
-        are:
+  "Add a product" will set the field 'display_type' to its default value.
 
-        - ``integer`` (default group operator is sum)
-        - ``float``  (default group operator is sum)
-        - ``many2one`` (default group operator is count distinct)
+  The two other buttons will set the field 'display_type'
+  to be respectively 'line_section' and 'line_note'.
 
-    - ``name`` (mandatory)
-        A string to identify this aggregate (useful for formulas)
+  .. code-block:: xml
 
-    - ``string`` (optional)
-        A short description that will be displayed above the value. If not
-        given, it will fall back to the field string.
+    <control>
+      <create
+        string="Add a product"
+      />
+      <create
+        string="Add a section"
+        context="{'default_display_type': 'line_section'}"
+      />
+      <create
+        string="Add a note"
+        context="{'default_display_type': 'line_note'}"
+      />
+    </control>
 
-    - ``domain`` (optional)
-        An additional restriction on the set of records that we want to aggregate.
-        This domain will be combined with the current domain.
+.. [#treehistory] for historical reasons, it has its origin in tree-type views
+                  later repurposed to a more table/list-type display
 
-    - ``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.
+.. _reference/views/map:
 
-    - ``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.
-        Note that no aggregation of field values is achieved if the group_operator value is "".
+Map
+---
 
-        .. note:: The special aggregate function ``count_distinct`` (defined in odoo) can also be used here
+.. raw:: html
 
-        .. code-block:: xml
+   <span class="badge" style="background-color:#AD5E99">Enterprise feature</span>
 
-          <aggregate name="price_total_max" field="price_total" group_operator="max"/>
+This view is able to display records on a map and the routes between them. The record are represented by pins. It also allows the visualization of fields from the model in a popup tied to the record's pin.
 
+.. note::
 
+    The model on which the view is applied should contains a res.partner many2one since the view relies on the res.partner's address and coordinates fields to localize the records.
 
-    - ``col`` (optional)
-        The number of columns spanned by this tag (only makes sense inside a
-        group). By default, 1.
+.. _reference/views/map/api:
 
-    - ``widget`` (optional)
-        A widget to format the value (like the widget attribute for fields).
-        For example, monetary.
+Api
+~~~
 
-    - ``help`` (optional)
-        A help message to dipslay in a tooltip (equivalent of help for a field in python)
+The view uses location data platforms' api to fetch the tiles (the map's background), do the geoforwarding (converting addresses to a set of coordinates) and fetch the routes.
+The view implements two api, the default one, openstreet map is able to fetch `tiles`_ and do `geoforwarding`_. This api does not require a token.
+As soon as a valid `MapBox`_ token is provided in the general settings the view switches to the Mapbox api. This api is faster and allows the computation of routes. The token are available by `signing up`_ to MapBox
 
-    - ``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.
+.. _reference/views/structural components:
 
-        .. code-block:: xml
+Structural components
+~~~~~~~~~~~~~~~~~~~~~
 
-          <aggregate name="total_ojects" string="Total Objects" field="id" group_operator="count" measure="__count__"/>
+The view's root element is ``<map>`` multiple attributes are allowed
 
-    - ``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.
+``res_partner``
+    Contains the res.partner many2one. If not provided the view will resort to create an empty  map.
+``default_order``
+    If a field is provided the view will override the model's default order. The field must be part of the model on which the view is applied not from res.partner
+``routing``
+    if ``true`` the routes between the records will be shown. The view still needs a valid MapBox token and at least two located records. (i.e the records has a res.partner many2one and the partner has a address or valid coordinates)
+``hide_name``
+    if ``true`` hide a name from the marker's popup (default: false)
+``hide_address``
+    if ``true`` hide a address from the marker's popup (default: false)
 
-    - ``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.
+The ``<map>`` element can contain multiple ``<field>`` elements. Each ``<field>`` element will be interpreted as a line in the marker's popup. The field's attributes are the following:
 
-``formula``
-    declares a derived value.  Formulas are values computed from aggregates.
+``name``
+    The field to display.
+``string``
+    This string will be displayed before the field's content. It Can be used as a description.
 
-    Note that like aggregates, formulas are supposed to be used inside a group
-    tag (otherwise the style will not be properly applied).
+No attribute or element is mandatory but as stated above if no res.partner many2one is provided the view won't be able to locate records.
 
-    Admissible attributes are:
+For example here is a map:
+    .. code-block:: xml
 
-    - ``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``.
+        <map res_partner="partner_id" default_order="date_begin" routing="true" hide_name="true">
+            <field name="partner_id" string="Customer Name"/>
+        </map>
 
-    - ``name`` (optional)
-        A string to identify this formula
+.. _reference/views/pivot:
 
-    - ``string`` (optional)
-        A short description that will be displayed above the formula.
+Pivot
+-----
 
-    - ``col`` (optional)
-        The number of columns spanned by this tag (only makes sense inside a
-        group). By default, 1.
+The pivot view is used to visualize aggregations as a `pivot table`_. Its root
+element is ``<pivot>`` which can take the following attributes:
 
-    - ``widget`` (optional)
-        A widget to format the value (like the widget attribute for fields).
-        For example, monetary. By default, it is 'float'.
+``disable_linking``
+  Set to ``True`` to remove table cell's links to list view.
+``display_quantity``
+  Set to ``true`` to display the Quantity column by default.
+``default_order``
+  The name of the measure and the order (asc or desc) to use as default order
+  in the view.
 
-    - ``help`` (optional)
-        A help message to dipslay in a tooltip (equivalent of help for a field in python)
+  .. code-block:: xml
 
-    - ``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.
+     <pivot default_order="foo asc">
+        <field name="foo" type="measure"/>
+     </pivot>
 
-``widget``
-    Declares a specialized widget to be used to display the information. This is
-    a mechanism similar to the widgets in the form view.
+The only allowed element within a pivot view is ``field`` which can have the
+following attributes:
 
-    Admissible attributes are:
+``name`` (required)
+  the name of a field to use in the view. If used for grouping (rather
+  than aggregating)
 
-    - ``name`` (mandatory)
-        A string to identify which widget should be instantiated. The view will
-        look into the ``widget_registry`` to get the proper class.
+``string``
+  the name that will be used to display the field in the pivot view,
+  overrides the default python String attribute of the field.
 
-    - ``col`` (optional)
-        The number of columns spanned by this tag (only makes sense inside a
-        group). By default, 1.
+``type``
+  indicates whether the field should be used as a grouping criteria or as an
+  aggregated value within a group. Possible values are:
 
-.. _reference/views/cohort:
+  ``row`` (default)
+    groups by the specified field, each group gets its own row.
+  ``col``
+    creates column-wise groups
+  ``measure``
+    field to aggregate within a group
+  ``interval``
+    on date and datetime fields, groups by the specified interval (``day``,
+    ``week``, ``month``, ``quarter`` or ``year``) instead of grouping on the
+    specific datetime (fixed second resolution) or date (fixed day resolution).
 
-Cohort
-=========
+``invisible``
+  if true, the field will not appear either in the active measures nor in the
+  selectable measures (useful for fields that do not make sense aggregated,
+  such as fields in different units, e.g. € and $).
 
-The cohort view is used to display and understand the way some data changes over
-a period of time.  For example, imagine that for a given business, clients can
-subscribe to some service.  The cohort view can then display the total number
-of subscriptions each month, and study the rate at which client leave the service
-(churn). When clicking on a cell, the cohort view will redirect you to a new action
-in which you will only see the records contained in the cell's time interval;
-this action contains a list view and a form view.
+The measures are automatically generated from the model fields; only the
+aggregatable fields are used. Those measures are also alphabetically
+sorted on the string of the field.
 
 .. warning::
 
-   The Cohort view is only available in Odoo Enterprise.
-
-.. note:: By default the cohort view will use the same list and form views as those
-   defined on the action. You can pass a list view and a form view
-   to the context of the action in order to set/override the views that will be
-   used (the context keys to use being `form_view_id` and `list_view_id`)
-
-For example, here is a very simple cohort view:
-
-.. code-block:: xml
-
-    <cohort string="Subscription" date_start="date_start" date_stop="date" interval="month"/>
-
-The root element of the Cohort view is <cohort>, it accepts the following
-attributes:
-
-
-- ``string`` (mandatory)
-    A title, which should describe the view
-
-- ``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)
-    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)
-    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)
-    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)
-    A string to describe a time interval. It should be 'day', 'week', 'month''
-    (default) or 'year'.
-
-- ``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.
-
-.. _reference/views/activity:
+    like the graph view, the pivot aggregates data on database content
+    which means that non-stored function fields can not be used in pivot views
 
-Activity
-========
 
-The Activity view is used to display the activities linked to the records. The
-data are displayed in a chart with the records forming the rows and the activity
-types the columns. The first cell of each row displays a (customizable, see
-``templates``, quite similarly to :ref:`reference/views/kanban`) card representing
-the corresponding record. When clicking on others cells, a detailed description
-of all activities of the same type for the record is displayed.
+In Pivot view a ``field`` can have a ``widget`` attribute to dictate its format.
+The widget should be a field formatter, of which the most interesting are
+``date``, ``datetime``, ``float_time``, and ``monetary``.
 
-.. warning::
+For instance a timesheet pivot view could be defined as::
 
-   The Activity view is only available when the ``mail`` module is installed,
-   and for the models that inherit from the ``mail.activity.mixin``.
+    <pivot string="Timesheet">
+        <field name="employee_id" type="row"/>
+        <field name="date" interval="month" type="col"/>
+        <field name="unit_amount" type="measure" widget="float_time"/>
+    </pivot>
 
-The root element of the Activity view is ``<activity>``, it accepts the following
-attributes:
+.. _reference/views/qweb:
 
-- ``string`` (mandatory)
-    A title, which should describe the view
+QWeb
+----
 
-Possible children of the view element are:
+QWeb views are standard :ref:`reference/qweb` templates inside a view's
+``arch``. They don't have a specific root element. Because QWeb views don't
+have a specific root element, their type must be specified explicitly (it can
+not be inferred from the root element of the ``arch`` field).
 
-``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.
+QWeb views have two use cases:
 
-  Possible attributes are:
+* they can be used as frontend templates, in which case
+  :ref:`reference/data/template` should be used as a shortcut.
+* they can be used as actual qweb views (opened inside an action), in which
+  case they should be defined as regular view with an explicit ``type`` (it
+  can not be inferred) and a model.
 
-  ``name`` (required)
-    the name of the field to fetch
+The main additions of qweb-as-view to the basic qweb-as-template are:
 
-``templates``
-  defines the :ref:`reference/qweb` templates. Cards definition may be
-  split into multiple templates for clarity, but activity views *must* define at
-  least one root template ``activity-box``, which will be rendered once for each
-  record.
+* qweb-as-view has a special case for a ``<nav>`` element bearing the CSS
+  class ``o_qweb_cp_buttons``: its contents should be buttons and will be
+  extracted and moved to the control panel's button area, the ``<nav>`` itself
+  will be removed, this is a work-around to control panel views not existing
+  yet
+* qweb-as-view rendering adds several items to the standard qweb rendering
+  context:
 
-  The activity view uses mostly-standard :ref:`javascript qweb
-  <reference/qweb/javascript>` and provides the following context variables
-  (see :ref:`reference/views/kanban` for more details):
+  ``model``
+    the model to which the qweb view is bound
+  ``domain``
+    the domain provided by the search view
+  ``context``
+    the context provided by the search view
+  ``records``
+    a lazy proxy to ``model.search(domain)``, this can be used if you just
+    want to iterate the records and not perform more complex operations
+    (e.g. grouping)
+* qweb-as-view also provides additional rendering hooks:
 
-  ``widget``
-    the current :js:class:`ActivityRecord`, can be used to fetch some
-    meta-information. These methods are also available directly in the
-    template context and don't need to be accessed via ``widget``
-  ``record``
-    an object with all the requested fields as its attributes. Each field has
-    two attributes ``value`` and ``raw_value``
+  - ``_qweb_prepare_context(view_id, domain)`` prepares the rendering context
+    specific to qweb-as-view
+  - ``qweb_render_view(view_id, domain)`` is the method called by the client
+    and will call the context-preparation methods and ultimately
+    ``env['ir.qweb'].render()``.
 
 .. _reference/views/search:
 
 Search
-======
+------
 
 Search views are a break from previous view types in that they don't display
 *content*: although they apply to a specific model, they are used to filter
@@ -1560,12 +1879,11 @@ Possible children elements of the search view are:
         search domain
 
         The key ``group_by`` can be used to define a groupby available in the
-        'Group By' menu.
-        The 'group_by' value can be a valid field name.
+        'Group By' menu. The 'group_by' value can be a valid field name.
 
         .. code-block:: xml
 
-          <filter name="groupby_category" string="Category" context = {'group_by': 'category_id'}/>
+           <filter name="groupby_category" string="Category" context = {'group_by': 'category_id'}/>
 
         The groupby defined above allows to group data by category.
 
@@ -1580,7 +1898,12 @@ Possible children elements of the search view are:
 
         .. code-block:: xml
 
-          <filter name="groupby_create_date" string="Creation Date" context = {'group_by': 'create_date:week'}/>
+           <filter name="groupby_create_date" string="Creation Date" context = {'group_by': 'create_date:week'}/>
+
+        .. note::
+           The results of read_groups grouped on a field may be influenced by its group_expand attribute,
+           allowing to display empty groups when needed.  For more information, please refer to
+           :class:`~odoo.fields.Field` attributes documentation.
 
     ``name``
         logical name for the filter, can be used to :ref:`enable it by default
@@ -1619,17 +1942,18 @@ Possible children elements of the search view are:
 
 ``separator``
     can be used to separates groups of filters in simple search views
+
 ``group``
     can be used to separate groups of filters, more readable than
     ``separator`` in complex search views
+
 ``searchpanel``
   allows to display a search panel on the left of any multi records view.
   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
-
-      default: 'tree,kanban'
+    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``,
@@ -1639,11 +1963,11 @@ Possible children elements of the search view are:
 
   * ``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.
+    * ``one`` (default) at most one value can be selected. Supported field types are
+      many2one and selection.
 
-      ``multi`` several values can be selected (checkboxes). Supported field
-        types are many2one, many2many and selection.
+    * ``multi`` several values can be selected (checkboxes). Supported field
+      types are many2one, many2many and selection.
 
   * ``groups``: restricts to specific users
 
@@ -1682,7 +2006,7 @@ Possible children elements of the search view are:
 .. _reference/views/search/defaults:
 
 Search defaults
----------------
+~~~~~~~~~~~~~~~
 
 Search fields and filters can be configured through the action's ``context``
 using :samp:`search_default_{name}` keys. For fields, the value should be the
@@ -1711,131 +2035,17 @@ For instance if ``foo`` and ``bar`` refer to two groupbys
 
 has the effect to activate first ``bar`` then ``foo``.
 
-.. _reference/views/map:
-
-Map
-===
-
-This view is able to display records on a map and the routes between them. The record are represented by pins. It also allows the visualization of fields from the model in a popup tied to the record's pin.
-
-.. note::
-
-    The model on which the view is applied should contains a res.partner many2one since the view relies on the res.partner's address and coordinates fields to localize the records.
-
-.. warning::
-
-   The Map view is only available in Odoo Enterprise
-
-.. _reference/views/map/api:
-
-Api
----
-
-The view uses location data platforms' api to fetch the tiles (the map's background), do the geoforwarding (converting addresses to a set of coordinates) and fetch the routes.
-The view implements two api, the default one, openstreet map is able to fetch `tiles`_ and do `geoforwarding`_. This api does not require a token.
-As soon as a valid `MapBox`_ token is provided in the general settings the view switches to the Mapbox api. This api is faster and allows the computation of routes. The token are available by `signing up`_ to MapBox
-
-
-
-.. _reference/views/structural components:
-
-Structural components
----------------------
-
-The view's root element is ``<map>`` multiple attributes are allowed
-
-``res_partner``
-    Contains the res.partner many2one. If not provided the view will resort to create an empty  map.
-``default_order``
-    If a field is provided the view will override the model's default order. The field must be apart of the model on which the view is applied not from res.partner
-``routing``
-    if ``true`` the routes between the records will be shown. The view still needs a valid MapBox token and at least two located records. (i.e the records has a res.partner many2one and the partner has a address or valid coordinates)
-``hide_name``
-    if ``true`` hide a name from the marker's popup (default: false)
-``hide_address``
-    if ``true`` hide a address from the marker's popup (default: false)
-
-The ``<map>`` element can contain multiple ``<field>`` elements. Each ``<field>`` element will be interpreted as a line in the marker's popup. The field's attributes are the following:
-
-``name``
-    The field to display.
-``string``
-    This string will be displayed before the field's content. It Can be used as a description.
-
-No attribute or element is mandatory but as stated above if no res.partner many2one is provided the view won't be able to locate records.
-
-For example here is a map:
-    .. code-block:: xml
-
-        <map res_partner="partner_id" default_order="date_begin" routing="true" hide_name="true">
-            <field name="partner_id" string="Customer Name"/>
-        </map>
-
-.. _reference/views/qweb:
-
-QWeb
-====
-
-QWeb views are standard :ref:`reference/qweb` templates inside a view's
-``arch``. They don't have a specific root element. Because QWeb views don't
-have a specific root element, their type must be specified explicitly (it can
-not be inferred from the root element of the ``arch`` field).
-
-QWeb views have two use cases:
-
-* they can be used as frontend templates, in which case
-  :ref:`reference/data/template` should be used as a shortcut.
-* they can be used as actual qweb views (opened inside an action), in which
-  case they should be defined as regular view with an explicit ``type`` (it
-  can not be inferred) and a model.
-
-The main additions of qweb-as-view to the basic qweb-as-template are:
-
-* qweb-as-view has a special case for a ``<nav>`` element bearing the CSS
-  class ``o_qweb_cp_buttons``: its contents should be buttons and will be
-  extracted and moved to the control panel's button area, the ``<nav>`` itself
-  will be removed, this is a work-around to control panel views not existing
-  yet
-* qweb-as-view rendering adds several items to the standard qweb rendering
-  context:
-
-  ``model``
-    the model to which the qweb view is bound
-  ``domain``
-    the domain provided by the search view
-  ``context``
-    the context provided by the search view
-  ``records``
-    a lazy proxy to ``model.search(domain)``, this can be used if you just
-    want to iterate the records and not perform more complex operations
-    (e.g. grouping)
-* qweb-as-view also provides additional rendering hooks:
-
-  - ``_qweb_prepare_context(view_id, domain)`` prepares the rendering context
-    specific to qweb-as-view
-  - ``qweb_render_view(view_id, domain)`` is the method called by the client
-    and will call the context-preparation methods and ultimately
-    ``env['ir.qweb'].render()``.
-
-.. [#backwards-compatibility] for backwards compatibility reasons
-.. [#hasclass] an extension function is added for simpler matching in QWeb
-               views: ``hasclass(*classes)`` matches if the context node has
-               all the specified classes
-.. [#treehistory] for historical reasons, it has its origin in tree-type views
-                  later repurposed to a more table/list-type display
-.. [#template_inherit] or no template if it's an inherited view, then :ref:`it
-                       should only contain xpath elements
-                       <reference/views/inheritance>`
+.. todo:: View Grid
 
+.. _bootstrap contextual color: https://getbootstrap.com/docs/3.3/components/#available-variations
 .. _geoforwarding: https://nominatim.org/release-docs/develop/
 .. _tiles: https://wiki.openstreetmap.org/wiki/Tile_data_server
 .. _MapBox: https://docs.mapbox.com/api/
 .. _signing up: https://account.mapbox.com/auth/signup/
-.. _accesskey: http://www.w3.org/TR/html5/editing.html#the-accesskey-attribute
-.. _CSS color unit: http://www.w3.org/TR/css3-color/#colorunits
+.. _accesskey: https://www.w3.org/TR/html5/editing.html#the-accesskey-attribute
 .. _floats: https://developer.mozilla.org/en-US/docs/Web/CSS/float
-.. _HTML: http://en.wikipedia.org/wiki/HTML
-.. _kanban board: http://en.wikipedia.org/wiki/Kanban_board
-.. _pivot table: http://en.wikipedia.org/wiki/Pivot_table
-.. _XPath: http://en.wikipedia.org/wiki/XPath
+.. _HTML: https://en.wikipedia.org/wiki/HTML
+.. _kanban board: https://en.wikipedia.org/wiki/Kanban_board
+.. _pivot table: https://en.wikipedia.org/wiki/Pivot_table
+.. _XPath: https://en.wikipedia.org/wiki/XPath
 .. _KanbanExamplesRegistry: https://github.com/odoo/odoo/blob/99821fdcf89aa66ac9561a972c6823135ebf65c0/addons/web/static/src/js/views/kanban/kanban_examples_registry.js