diff --git a/content/developer/reference/frontend/javascript_reference.rst b/content/developer/reference/frontend/javascript_reference.rst index c241a890c..e4d174905 100644 --- a/content/developer/reference/frontend/javascript_reference.rst +++ b/content/developer/reference/frontend/javascript_reference.rst @@ -1306,9 +1306,25 @@ Reference (`reference`) - `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. +.. _reference/javascript_reference/view_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 + + + + 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`) 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. diff --git a/content/developer/reference/user_interface/view_architectures.rst b/content/developer/reference/user_interface/view_architectures.rst index 9c90909fd..ab7927548 100644 --- a/content/developer/reference/user_interface/view_architectures.rst +++ b/content/developer/reference/user_interface/view_architectures.rst @@ -171,8 +171,6 @@ The `field` element can have the following attributes: :type: str :default: `''` -.. include:: view_architectures/field_attribute_widget.rst - .. attribute:: options :noindex: @@ -1402,8 +1400,6 @@ The `field` element can have the following attributes: :type: :ref:`Python expression ` :default: `False` -.. include:: view_architectures/field_attribute_widget.rst - .. attribute:: sum, avg :noindex: @@ -2338,10 +2334,9 @@ A numeric value (between 1 and 99) can be used to define the order of default *g Kanban ====== -Kanban views are a used as a `kanban board `_ +Kanban views are used as a `kanban board `_ visualisation: they display records as "cards", halfway between a :ref:`list -` view and a non-editable :ref:`form -` view. +` and a :ref:`form ` view. 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). @@ -2520,53 +2515,295 @@ Optional attributes can be added to the root element `kanban` to customize the v Components ---------- -Kanban views accept the following children elements: :ref:`field +Kanban views accept the following children elements: :ref:`templates +`, :ref:`field `, :ref:`header `, :ref:`progressbar -`, and :ref:`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 ` that structure +the kanban cards. -The `field` element declares fields to use in the :ref:`templates -`. If the field is simply displayed, it does not need -to be pre-declared. +The definition of a card's structure can be split into multiple templates for clarity, but at least +one root `card` template must be defined. + +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 `. .. code-block:: xml - - ... + + + + + -The `field` element can have the following attributes: +.. warning:: + + These are QWeb templates, not `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 -.. 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:: - :class: o-showcase-table + .. attribute:: handle + :noindex: - * - .. image:: view_architectures/kanban_field.svg - :align: center + Allows reordering records with a drag and drop, using the corresponding field as order. - * - .. code-block:: xml + .. attribute:: kanban_color_picker + :noindex: - - - -
- -
-
-
-
+ Allows editing a color (integer) field. Combined with the root attribute `highlight_color`, + allows editing the color of the cards. + +See the :ref:`Field section ` to discover +various widgets and their options. + +Rendering Context +***************** + +Kanban templates being rendered with the :ref:`QWeb engine `, 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 + `` tag. + + .. example:: + .. code-block:: xml + + + + + + + + + + + +.. 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 + + + + + + + + Delete + + + + +.. 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 `_ object, allowing to + manipulate date and datetime field values. + +.. attribute:: JSON + :noindex: + + The Javascript `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 `, 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 `, +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 ` to discover various +widgets and their options. + +Layouts +******* + +Several card layouts can be easily obtained using standard html elements and `Bootstrap utility +classes `_. By default, the card is a `flexbox +container `_ +with `column` direction. + +.. example:: + .. code-block:: xml + + + + + + + + + + + +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 + + + + + + + +
+ + +
+
+
+
+ +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 + + + + + +
+ + + +
+ + +
+
+
+
+
+ +.. 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 +`. 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 + + + + + + + + + + .. _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 -
- -
- ... +
+ ... +
+ ...
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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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 @@ -2687,111 +2925,6 @@ The `progressbar` element can have the following attributes: -.. _reference/view_architectures/kanban/templates: - -`templates`: define cards structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `templates` elements is used to define the :ref:`QWeb templates ` 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 ` - -.. code-block:: xml - - - ... - - -
- -
-
-
-
- -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 `_). - - :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 `, 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 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 - `, 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:: - kanban-specific CSS - kanban structures/widgets (vignette, details, ...) diff --git a/content/developer/reference/user_interface/view_architectures/field_attribute_name.rst b/content/developer/reference/user_interface/view_architectures/field_attribute_name.rst index 1f1cd534a..7265ea754 100644 --- a/content/developer/reference/user_interface/view_architectures/field_attribute_name.rst +++ b/content/developer/reference/user_interface/view_architectures/field_attribute_name.rst @@ -5,3 +5,13 @@ :requirement: Mandatory :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 diff --git a/content/developer/reference/user_interface/view_architectures/field_attribute_widget.rst b/content/developer/reference/user_interface/view_architectures/field_attribute_widget.rst deleted file mode 100644 index d083475f9..000000000 --- a/content/developer/reference/user_interface/view_architectures/field_attribute_widget.rst +++ /dev/null @@ -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 - -
- - - - - - - - :requirement: Optional - :type: str - :default: `''`