pengyuthon/odoo_source
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[MOV] documentation: move grid view documentation from enterprise

Browse Source 
As we were introducing changes in web_grid (enterprise) we realized that no documentation
on the grid view was yet available in the community documentation. This commit moves the
the existing documentation from enterprise to the community doc repository and adds the
new attributes introduced in the realte enterprise PR.

task-2271628
Closes #65081

Related: odoo/enterprise#12127
Signed-off-by: Yannick Tivisse (yti) <yti@odoo.com>
This commit is contained in:
Laurent Stukkens (LTU)
2021-01-27 20:55:22 +00:00
parent 0f2f8c562d
commit 218ca8dbf7
1 changed files with 260 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/reference/views.rst
+260 -2
View File
@@ -1174,6 +1174,266 @@ 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/grid:
Grid
----
.. raw:: html
<span class="badge" style="background-color:#AD5E99">Enterprise feature</span>
Limitations
~~~~~~~~~~~
This view is a work in progress and may have to be expanded or altered.
* only ``date`` column fields have been tested, ``selection`` and ``many2one``
are nominally implemented and supported but have not been tested,
``datetime`` is not implemented at all.
* column cells are hardly configurable and must be numerical
* cell adjustment is disabled by default and must be configured to be enabled
* ``create``, ``edit`` and ``delete`` ACL metadata doesn't get automatically
set on the view root due to limitations in ``fields_view_get``
post-processing (there's a fixed explicit list of the view types getting
those attributes)
Schema
~~~~~~
The grid view has its own schema and additional validation in this module. The
view architecture is:
``<grid>`` (1)
architecture root element
* mandatory ``string`` attribute
* optional ``create``, ``edit`` and ``delete`` attributes
* optional ``adjustment`` and ``adjust_name`` attributes
``adjustment`` can be either ``object`` or ``action`` to indicate
whether a cell's adjustment should be performed through a method call
or an action execution. ``adjust_name`` provides respectively the method
name and the action id.
In both cases, the adjustment parameters are provided as a
``grid_adjust`` context member, in the ``object`` case, the parameters
are also provided as positional function parameters (next to an empty
list of ids):
``row_domain``
the domain matching the entire row of the adjusted cell
``column_field``
the name of the column for the adjusted cell
``column_value``
the value of the column for the adjusted cell
``cell_field``
the measure field of the adjusted cell
``change``
the difference between the old value of the cell and the adjusted one,
may be possitive or negative
* optional ``hide_line_total`` and ``hide_column_total`` attributes
``hide_line_total``
set to true to hide total line (default false)
``hide_column_total``
set to true to hide total column (default false)
* optional ``barchart_total`` attribute
``barchart_total``
set to ``true`` in order to display a bar chart at the bottom of the grid, based on
the totals of the columns (default false).
* optional ``create_inline`` and ``display_empty`` attributes
``create_inline``
set to ``true`` in order to display an additional row at bottom of the grid with an
``Add a line`` button (default false). When this option is set to ``true``, the ``Add a line`` button
from the control panel is hidden. When no data is available and when ``display_empty`` is
not set (so when the help content is displayed), the the ``Add a line`` button from the
control panel is shown in order to let the user create a first record.
``display_empty``
set to ``true`` in order to keep displaying the grid when there is no data (default false). This can
be useful when you want the user to be able to keep track of the current period (as dates
are displayed in the columns headers). As a reminder, when no data are present and when this
attribute is no set, the help content is displayed instead of the grid.
``<button>`` (0+)
Regular Odoo action buttons, displayed in the view header
* mandatory ``string`` attribute (the button label)
* mandatory ``type`` attribute, either ``object`` or ``action``
.. note:: workflow buttons are not supported
* mandatory ``name`` attribute, either the name of the method to call, or
the ID of the action to execute
* optional ``context``
The server callback is provided with all the record ids displayed in the
view, either as the ids passed to the method (``object`` button) or as
the context's ``active_ids`` (``action`` buttons)
``<field type="row">`` (1+)
Row grouping fields, will be replaced by the search view's groupby filter
if any.
The order of ``row`` fields in the view provides their grouping depth:
if the first field is ``school`` and the second is ``age`` the records
will be grouped by ``school`` first and by ``age`` within each school.
``<field type="col">`` (1)
Column grouping field.
The col field can contain 0+ ``<range>`` elements which specify
customisable column ranges. ``range`` elements have the following
mandatory attributes
``name``
can be used to override the default range (the first one by default)
through the ``grid_range`` context value
``string``
the range button's label (user-visible)
``span``
symbolic name of the span of all columns to display at once in the
view, may trigger pagination.
For ``date`` fields, valid spans are currently ``week`` and ``month``.
``step``
symbolic name of the step between one column and the previous/next
For ``date`` fields, the only valid span is currently ``day``.
``<field type="measure">`` (1)
Cell field, automatically accumulated (by ``read_group``).
The measure field can take a ``widget`` attribute to customise its
display.
Server interactions
~~~~~~~~~~~~~~~~~~~
Aside from optional buttons, the grid view currently calls two methods:
* ``read_grid`` (provided on all models by the module) returns almost the
entirety of the grid's content as a dict:
* the row titles is a list of dictionaries with the following keys:
``values`` (required)
this maps to a dictionary with a key per ``row`` field, the values are
*always* of the form ``[value, label]``.
``domain`` (required)
the domain of any record at the source of this row, in case it's
necessary to copy a record during cell adjustment
* the column titles is a list of dictionaries with at least one key:
``values`` (required)
see row title values
``domain`` (required)
see column domain value
``current`` (optional)
boolean, marks/highlights a column
* the grid data as a list (of rows) of list (of cells) of cell dicts each
with the following keys:
``value``
the numeric value associated with the cell
``domain``
the domain matching the cell's records (should be assumed opaque)
``size``
the number of records grouped in the cell
``readonly`` (optional)
a boolean indicating that this specific cell should not be
client-editable
``classes`` (optional)
a list of classes (as strings) to add on the cell's container (between
the cell's TD and the cell's potentially-editable element).
In case of conflicts between this list and the base classes (prefixed
with ``o_grid_cell_``), the classes in this list are ignored.
Note that the grid data is *dense*, if querying the database yields no
group matching a cell a cell will generate an "empty" cell with default
values for required keys.
* ``prev`` and ``next`` which can be either falsy (no pagination) or a
context item to merge into the view's own context to ``read_grid`` the
previous or next page, it should be assumed to be opaque
* ``read_grid_domain(field, range)`` (provided on al models by the module)
returns the domain matching the current configured "span" of the grid. This
is also done internally by ``read_grid``, but can be useful or necessary to
call independently to use with separate e.g. ``search_count`` or
``read_group``.
* ``adjust_grid``, for which there currently isn't a blanket implementation
and whose semantics are likely to evolve with time and use cases
Server Hooks
~~~~~~~~~~~~
``read_grid`` calls a number of hooks allowing the customisation of its
operations from within without having to override the entire method:
``_grid_format_cell(group, cell_field)``
converts the output of a read_group (group-by-group) into cells in the
format described above (as part of "the grid data")
``_grid_make_empty_cell(row_domain, column_domain, view_domain)``
generates an empty version of a cell (if there is no corresponding group)
``_grid_column_info(name, range)``
generates a ColumnMetadata object based on the column type, storing values
either returned directly (as part of ``read_grid``) or used query and
reformat ``read_group`` into ``read_grid``:
``grouping``
the actual grouping field/query for the columns
``domain``
domain to apply to ``read_group`` in case the column field is
paginated, can be an empty list
``prev`` and ``next``
context segments which will be sent to ``read_grid`` for pages before
and after the current one. If ``False``, disables pagination in that
direction
``values``
column values to display on the "current page", each value is a
dictionary with the following keys:
``values``
dictionary mapping field names to values for the entire column,
usually just ``name`` -> a value
``domain``
domain matching this specific column
``is_current``
``True`` if the current column should be specifically outlined in
the grid, ``False`` otherwise
``format``
how to format the values of that column/type from ``read_group``
formatting to ``read_grid`` formatting (matching ``values`` in
ColumnInfo)
ACL
~~~
* if the view is not editable, individual cells won't be editable
* if the view is not creatable, the ``Add a Line`` button will not be
displayed (it currently creates a new empty record)
Context Keys
~~~~~~~~~~~~
``grid_range``
selects which range should be used by default if the view has multiple
ranges
``grid_anchor``
if applicable, used as the default anchor of column ranges instead of
whatever ``read_grid`` defines as its default.
For date fields, the reference date around which the initial span will be
computed. The default date anchor is "today" (in the user's timezone)
.. _reference/views/kanban:
Kanban
@@ -2127,8 +2387,6 @@ For instance if ``foo`` and ``bar`` refer to two groupbys
has the effect to activate first ``bar`` then ``foo``.
.. 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