NextERP/documentation
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[IMP] reference/user_interface: rework kanban documentation

Browse Source 
Following the new kanban API with `card` template.

Task~3992107

closes odoo/documentation#11081

Signed-off-by: Aaron Bohy (aab) <aab@odoo.com>
This commit is contained in:
Aaron Bohy 2024-09-24 12:06:11 +02:00
parent 78225635f4
commit 5765edca11
4 changed files with 304 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
content/developer/reference/frontend/javascript_reference.rst
View File

@ -1306,9 +1306,25 @@ Reference (`reference`)
- `model_field`: name of an `ir.model` containing the model of the records that can be selected. - `model_field`: name of an `ir.model` containing the model of the records that can be selected.
When this option is set, the select part of the `reference` field isn't displayed. When this option is set, the select part of the `reference` field isn't displayed.
.. _reference/javascript_reference/view_widgets:
Widgets Widgets
------- -------
Ribbon (`web_ribbon`)
This widget displays a ribbon at the top right corner of the kanban card or the form view sheet,
for instance, to indicate archived records.
.. code-block:: xml
<widget name="web_ribbon" title="Archived" bg_color="text-bg-danger"/>
Attributes:
- `title`: text displayed in the ribbon.
- `tooltip`: text displayed in the ribbon's tooltip.
- `bg-class`: classname to set on the ribbon, typically to define the ribbon's color.
Week Days (`week_days`) Week Days (`week_days`)
This widget displays a list of checkboxes for week days, 1 checkbox for each day This widget displays a list of checkboxes for week days, 1 checkbox for each day
and allow the user to select a subset of the choices. and allow the user to select a subset of the choices.

423
content/developer/reference/user_interface/view_architectures.rst
View File

@ -171,8 +171,6 @@ The `field` element can have the following attributes:
:type: str :type: str
:default: `''` :default: `''`
.. include:: view_architectures/field_attribute_widget.rst
.. attribute:: options .. attribute:: options
:noindex: :noindex:
@ -1402,8 +1400,6 @@ The `field` element can have the following attributes:
:type: :ref:`Python expression <reference/view_architectures/python_expression>` :type: :ref:`Python expression <reference/view_architectures/python_expression>`
:default: `False` :default: `False`
.. include:: view_architectures/field_attribute_widget.rst
.. attribute:: sum, avg .. attribute:: sum, avg
:noindex: :noindex:
@ -2338,10 +2334,9 @@ A numeric value (between 1 and 99) can be used to define the order of default *g
Kanban Kanban
====== ======
Kanban views are a used as a `kanban board <https://en.wikipedia.org/wiki/Kanban_board>`_ Kanban views are used as a `kanban board <https://en.wikipedia.org/wiki/Kanban_board>`_
visualisation: they display records as "cards", halfway between a :ref:`list visualisation: they display records as "cards", halfway between a :ref:`list
<reference/view_architectures/list>` view and a non-editable :ref:`form <reference/view_architectures/list>` and a :ref:`form <reference/view_architectures/form>` view.
<reference/view_architectures/form>` view.
Records may be grouped in columns for use in workflow visualisation or manipulation (e.g., tasks or Records may be grouped in columns for use in workflow visualisation or manipulation (e.g., tasks or
work-progress management), or ungrouped (used simply to visualize records). work-progress management), or ungrouped (used simply to visualize records).
@ -2520,53 +2515,295 @@ Optional attributes can be added to the root element `kanban` to customize the v
Components Components
---------- ----------
Kanban views accept the following children elements: :ref:`field Kanban views accept the following children elements: :ref:`templates
<reference/view_architectures/kanban/templates>`, :ref:`field
<reference/view_architectures/kanban/field>`, :ref:`header <reference/view_architectures/kanban/field>`, :ref:`header
<reference/view_architectures/kanban/header>`, :ref:`progressbar <reference/view_architectures/kanban/header>`, :ref:`progressbar
<reference/view_architectures/kanban/progressbar>`, and :ref:`templates <reference/view_architectures/kanban/progressbar>`.
<reference/view_architectures/kanban/templates>`.
Placeholders are denoted in all caps. .. _reference/view_architectures/kanban/templates:
.. _reference/view_architectures/kanban/field: `templates`: define cards structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`field`: display field values The `templates` element is used to define the :ref:`QWeb templates <reference/qweb>` that structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ the kanban cards.
The `field` element declares fields to use in the :ref:`templates The definition of a card's structure can be split into multiple templates for clarity, but at least
<reference/view_architectures/kanban/templates>`. If the field is simply displayed, it does not need one root `card` template must be defined.
to be pre-declared.
An additional template can be defined: `menu`. If defined, it is rendered inside a dropdown
that can be toggled with a vertical ellipsis (:guilabel:`⋮`) on the top right of the card.
The templates are written in :ref:`JavaScript QWeb <reference/qweb/javascript>`.
.. code-block:: xml .. code-block:: xml
<kanban> <kanban>
<field name="FIELD_NAME"/> <templates>
... <t t-name="card">
<field name="name"/>
</t>
</templates>
</kanban> </kanban>
The `field` element can have the following attributes: .. warning::
These are QWeb templates, not `Owl <https://github.com/odoo/owl>`_ templates, meaning that
directives like `t-on-click` aren't available.
Fields
******
Inside those templates, the `field` element allows to render a field. It can have the following
attributes:
.. include:: view_architectures/field_attribute_name.rst .. include:: view_architectures/field_attribute_name.rst
.. admonition:: Possible structure and representation of its rendering By default, field nodes are replaced by a `span` containing their formatted value, unless the
`widget` attribute is specified, in which case their rendering and behavior depends on the
corresponding widget. The `widget` attribute can have different values including:
.. list-table:: .. attribute:: handle
:class: o-showcase-table :noindex:
* - .. image:: view_architectures/kanban_field.svg Allows reordering records with a drag and drop, using the corresponding field as order.
:align: center
* - .. code-block:: xml .. attribute:: kanban_color_picker
:noindex:
<kanban> Allows editing a color (integer) field. Combined with the root attribute `highlight_color`,
<templates> allows editing the color of the cards.
<t t-name="kanban-box">
<div> See the :ref:`Field section <reference/js/widgets>` to discover
<field name="name"/> various widgets and their options.
</div>
</t> Rendering Context
</templates> *****************
</kanban>
Kanban templates being rendered with the :ref:`QWeb engine <reference/qweb/javascript>`, they have
a *rendering context*, a set of variables available in the templates, containing useful information
and tools. Here're the available variables:
.. attribute:: record
:noindex:
An object with all the fields defined in the view. Each field has two attributes: `value`
and `raw_value`. The former is formatted according to current user parameters, while the latter
is the raw value (e.g. the `id` for a many2one field). This object is useful for instance, for
using field values inside `t-if` conditions. For display purposes, we recommend using the
`<field>` tag.
.. example::
.. code-block:: xml
<kanban>
<templates>
<field name="is_company"/>
<t t-name="card">
<field name="name"/>
<field t-if="!record.is_company.raw_value" name="parent_id">
</t>
</templates>
</kanban>
.. attribute:: widget
:noindex:
An object with 2 keys defining the available actions for the user:
- `editable`: true if the user can edit records, false otherwise;
- `deletable`: true if the user can delete records, false otherwise.
This is useful to conditionally display elements requiring specific access rights.
.. example::
.. code-block:: xml
<kanban>
<templates>
<t t-name="card">
<field name="name"/>
</t>
<t t-name="menu">
<a t-if="widget.deletable" role="menuitem" type="delete" class="dropdown-item">Delete</a>
</t>
</templates>
</kanban>
.. attribute:: context
:noindex:
The current context propagated from either the action that opens the kanban view, or the one2many
or many2many field that embeds the kanban view in a form view.
.. attribute:: read_only_mode
:noindex:
Indicates that the view is readonly.
:type: bool
.. attribute:: selection_mode
:noindex:
Whether the kanban view is opened when selecting a many2one or many2many field (in mobile
environment).
:type: bool
.. attribute:: luxon
:noindex:
The `luxon <https://moment.github.io/luxon/api-docs/index.html>`_ object, allowing to
manipulate date and datetime field values.
.. attribute:: JSON
:noindex:
The Javascript `JSON <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON>`_
namespace object containing a `parse` method allowing to parse json field values into Javascript
Objects.
Buttons and links
*****************
While most of the kanban templates are standard :ref:`QWeb templates <reference/qweb>`, the kanban
view processes `button` and `a` elements is a special way. Buttons and links with a `type` attribute
perform different operations than their standard HTML function. The `type` attribute can have the
values `action` and `object` of :ref:`regular buttons <reference/view_architectures/list/button>`,
or the following values:
.. attribute:: open
:noindex:
Clicking the element opens the card's record in form view.
.. attribute:: delete
:noindex:
Clicking the element deletes the card's record and removes the card.
.. attribute:: archive
:noindex:
Clicking the element archives the card's record and removes the card.
.. attribute:: unarchive
:noindex:
Clicking the element unarchives the card's record and removes the card.
.. attribute:: set_cover
:noindex:
Clicking the element allows to select an image to set as cover image of the record.
Widgets
*******
The `widget` element allows to insert dynamically generated (in Javascript) html inside the cards. It
has a mandatory `name` attribute, referring to a Javascript implementation (an Owl component)
registered to the `view_widgets` registry.
.. todo: document view_widgets registry and standard widgets
See the :ref:`Widget section <reference/javascript_reference/view_widgets>` to discover various
widgets and their options.
Layouts
*******
Several card layouts can be easily obtained using standard html elements and `Bootstrap utility
classes <https://getbootstrap.com/docs/5.0/utilities/api/>`_. By default, the card is a `flexbox
container <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox>`_
with `column` direction.
.. example::
.. code-block:: xml
<kanban>
<templates>
<t t-name="card">
<field class="fw-bold fs-5" name="display_name"/>
<field class="text-muted" name="parent_id"/>
<field name="tag_ids" widget="many2many_tags"/>
</t>
</templates>
</kanban>
The `footer` html element is styled to stick to the bottom of the card, and is as a flexbox
container with `row` direction, allowing to easily display several fields on the same line.
.. example::
.. code-block:: xml
<kanban>
<templates>
<t t-name="card">
<field class="fw-bold fs-5" name="display_name"/>
<field class="text-muted" name="parent_id"/>
<field name="tag_ids" widget="many2many_tags"/>
<footer>
<field name="priority" widget="priority"/> <!-- bottom left corner -->
<field class="ms-auto" name="activity_ids" widget="kanban_activity"/> <!-- bottom right corner -->
</footer>
</t>
</templates>
</kanban>
To display some content, like an image, on the side of the card, one can use `aside` and `main` html
elements, with the `flex-row` classname on the card. The `main` node is a flexbox container like the
card is when there's no `aside`.
.. example::
.. code-block:: xml
<kanban>
<templates>
<t t-name="card" class="flex-row">
<aside>
<field name="avatar_128" widget="image" alt="Avatar"/>
</aside>
<main class="ms-2">
<field class="fw-bold fs-5" name="display_name"/>
<field class="text-muted" name="parent_id"/>
<field name="tag_ids" widget="many2many_tags"/>
<footer>
<field name="priority" widget="priority"/>
<field class="ms-auto" name="activity_ids" widget="kanban_activity"/>
</footer>
</main>
</t>
</templates>
</kanban>
.. tip::
The classname `o_kanban_aside_full` set on the `aside` element removes the padding so that the
image spreads to the borders of the card.
.. _reference/view_architectures/kanban/field:
`field`: declare more fields to fetch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `field` element can also be used *outside* the kanban :ref:`templates
<reference/view_architectures/kanban/templates>`. In that case, it allows to declare fields that are
not displayed in the card, but still need to be fetched, for instance because their value is used
in a `t-if` condition.
.. example::
.. code-block:: xml
<kanban>
<templates>
<field name="is_company"/>
<t t-name="card">
<field name="name"/>
<field t-if="!record.is_company.raw_value" name="parent_id">
</t>
</templates>
</kanban>
.. _reference/view_architectures/kanban/header: .. _reference/view_architectures/kanban/header:
@ -2578,10 +2815,10 @@ The `header` element is used to insert custom buttons in the control panel.
.. code-block:: xml .. code-block:: xml
<kanban> <kanban>
<header> <header>
<BUTTONS/> ...
</header> </header>
... ...
</kanban> </kanban>
The `header` element accepts only `button` children elements, similar to :ref:`list views' button The `header` element accepts only `button` children elements, similar to :ref:`list views' button
@ -2628,7 +2865,8 @@ additional attributes:
`progressbar`: show progress bars on top of columns `progressbar`: show progress bars on top of columns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `progressbar` element is used to define a progress bar to display on top of kanban columns. The `progressbar` element is used to define a progress bar to display on top of kanban columns in
grouped kanban views.
.. code-block:: xml .. code-block:: xml
@ -2687,111 +2925,6 @@ The `progressbar` element can have the following attributes:
</templates> </templates>
</kanban> </kanban>
.. _reference/view_architectures/kanban/templates:
`templates`: define cards structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `templates` elements is used to define the :ref:`QWeb templates <reference/qweb>` that structure
the kanban cards.
Cards structure definition can be split into multiple templates for clarity, but at least one root
template `kanban-box` must be defined.
An additional template can be defined: `kanban-menu`. If defined, it is rendered inside a dropdown
that can be toggled with a vertical ellipsis (:guilabel:`⋮`) on the top right of the card.
The templates are written in :ref:`JavaScript QWeb <reference/qweb/javascript>`
.. code-block:: xml
<kanban>
...
<templates>
<t t-name="kanban-box">
<div>
<field name="name"/>
</div>
</t>
</templates>
</kanban>
The following variables are available in the rendering context:
.. attribute:: widget
:noindex:
The current :js:class:`KanbanRecord`. It can be used to fetch some meta-information. The methods
are also available directly in the template context and don't need to be accessed via `widget`.
:type: str
.. attribute:: record
:noindex:
An object with all the requested fields as its attributes. Each field has two attributes: `value`
and `raw_value`. The former is formatted according to current user parameters while the latter is
the raw value from a :meth:`~odoo.models.Model.read` (except for the `date` and `datetime` fields
that are `formatted according to the user locale <https://github.com/odoo/odoo/blob/a678bd4e
/addons/web_kanban/static/src/js/kanban_record.js#L102>`_).
:type: str
.. attribute:: context
:noindex:
The current context propagated from either the action that opens the kanban view, or the one2many
or many2many field that embeds the kanban view in a form view.
:type: str
.. attribute:: read_only_mode
:noindex:
:type: str
.. attribute:: selection_mode
:noindex:
Whether the kanban view is opened when selecting a many2one or many2many field in mobile
environment.
:type: bool
While most of the kanban templates are standard :ref:`QWeb templates <reference/qweb>`, the kanban
view processes `field`, `button` and `a` elements is a special way:
- By default, fields are replaced by their formatted value, unless the `widget` attribute is
specified, in which case their rendering and behavior depends on the corresponding widget. The
`widget` attribute can have different values including:
.. attribute:: handle
:noindex:
Allow reordering records with a drag and drop when their are sorted based on `sequence` (or
`integer`) fields.
.. todo:: list all widgets and move the attribute definition in the <field> section
- Buttons and links with a `type` attribute perform different operations than their standard HTML
function. The `type` attribute can have the values `action` and `object` of :ref:`regular buttons
<reference/view_architectures/list/button>`, or the following values:
.. attribute:: open
:noindex:
Clicking the element opens the card's record in form view in read-only mode.
.. attribute:: edit
:noindex:
Clicking the element opens the card's record in form view in editable mode.
.. attribute:: delete
:noindex:
Clicking the element deletes the card's record and removes the card.
.. todo:: .. todo::
- kanban-specific CSS - kanban-specific CSS
- kanban structures/widgets (vignette, details, ...) - kanban structures/widgets (vignette, details, ...)

10
content/developer/reference/user_interface/view_architectures/field_attribute_name.rst
View File

@ -5,3 +5,13 @@
:requirement: Mandatory :requirement: Mandatory
:type: str :type: str
.. attribute:: widget
:noindex:
The widget used to represent the field. The selected widget can change the way the field is
rendered and/or the way it can be edited. It refers to a Javascript implementation (an Owl
component) registered to the `fields` registry.
:requirement: Optional
:type: str

21
content/developer/reference/user_interface/view_architectures/field_attribute_widget.rst
View File

@ -1,21 +0,0 @@
.. attribute:: widget
:noindex:
The rendering method and context to use in place of the default one assigned to the field's type
(e.g., :class:`~odoo.fields.Char`, :class:`~odoo.fields.Many2one`). See
:ref:`reference/js/widgets`.
.. example::
.. code-block:: xml
<form>
<field name="tag_ids" widget="many2many_tags"/>
</form>
<list>
<field name="sequence" widget="handle"/>
<field name="level_progress" widget="progressbar"/>
</list>
:requirement: Optional
:type: str
:default: `''`