From 14c04387644d185f12f0c25f10321b827291fa56 Mon Sep 17 00:00:00 2001 From: "Antoine Vandevenne (anv)" Date: Tue, 25 Jul 2023 17:24:49 +0200 Subject: [PATCH] [IMP] reference/user_interface: reformat and clarify views reference In particular, the following changes are made: - Use the `class` and `attribute` admonitions along with custom attributes to define classes, views' root attributes, views' components, and attribute values. This allows re-using the responsive design that was made for reference lists, and getting rid of the previous implementation that relied on class attributes, which were not intended for this usage and reduce readability while hindering further contributions due to a lack of flexibility (no admonitions, sub-attributes...) - Use definition lists to define view types to allow for clearer and longer descriptions. - Rewrite and restructure the explanations when there is a lack clarity. - Extract duplicated content to included RST files. - Display SVG images into dedicated admonitions. - Fix RST and English mistakes. - Rename `view_architecture` to `view_architectures`, as it lists all existing architectures and doesn't describe "the architecture of a view". - Replace underscores with hyphens in image file names to improve SEO. task-3458320 closes odoo/documentation#5237 closes odoo/documentation#7497 X-original-commit: a17eaf4c6f74e89d2f0e0b3e93dc5fd3c545b703 Signed-off-by: Antoine Vandevenne (anv) --- .../howtos/standalone_owl_application.rst | 2 +- content/developer/reference/backend/data.rst | 2 +- content/developer/reference/external_api.rst | 2 +- content/developer/reference/frontend/qweb.rst | 2 +- .../developer/reference/user_interface.rst | 2 +- .../reference/user_interface/icons.rst | 2 + .../user_interface/view_architecture.rst | 4049 ----------------- .../user_interface/view_architectures.rst | 3713 +++++++++++++++ .../button_attribute_context.rst | 14 + .../button_attribute_help.rst | 13 + .../button_attribute_icon.rst | 14 + .../button_attribute_name.rst | 9 + .../button_attribute_string.rst | 13 + .../button_attribute_type.rst | 26 + .../field_attribute_name.rst | 7 + .../field_attribute_readonly.rst | 15 + .../field_attribute_required.rst | 15 + .../field_attribute_string.rst | 8 + .../field_attribute_widget.rst | 21 + .../form_button_box.svg | 0 .../form_group.svg | 0 .../form_newline.svg | 0 .../form_notebook.svg | 0 .../form_separator.svg | 0 .../generic_attribute_class.rst | 34 + .../generic_attribute_column_invisible.rst | 17 + .../generic_attribute_groups.rst | 16 + .../generic_attribute_invisible.rst | 28 + .../kanban.svg | 0 .../kanban_field.svg | 0 .../kanban_progressbar.svg | 0 .../list.svg | 0 .../list_button.svg | 0 .../list_control.svg | 0 .../list_field.svg | 0 .../list_groupby.svg | 0 .../list_header.svg | 0 .../root_attribute_banner_route.rst | 44 + .../root_attribute_create.rst | 8 + .../root_attribute_default_group_by.rst | 9 + .../root_attribute_default_order.rst | 18 + .../root_attribute_delete.rst | 8 + .../root_attribute_edit.rst | 8 + .../root_attribute_sample.rst | 16 + .../root_attribute_string.rst | 9 + .../search.svg | 0 .../search_field.svg | 0 .../search_filter.svg | 0 .../reference/user_interface/view_records.rst | 483 +- content/developer/tutorials/backend.rst | 6 +- .../getting_started/01_architecture.rst | 4 +- .../getting_started/07_basicviews.rst | 8 +- .../getting_started/12_sprinkles.rst | 14 +- .../getting_started/15_qwebintro.rst | 5 +- redirects/17.0.txt | 1 + 55 files changed, 4365 insertions(+), 4300 deletions(-) delete mode 100644 content/developer/reference/user_interface/view_architecture.rst create mode 100644 content/developer/reference/user_interface/view_architectures.rst create mode 100644 content/developer/reference/user_interface/view_architectures/button_attribute_context.rst create mode 100644 content/developer/reference/user_interface/view_architectures/button_attribute_help.rst create mode 100644 content/developer/reference/user_interface/view_architectures/button_attribute_icon.rst create mode 100644 content/developer/reference/user_interface/view_architectures/button_attribute_name.rst create mode 100644 content/developer/reference/user_interface/view_architectures/button_attribute_string.rst create mode 100644 content/developer/reference/user_interface/view_architectures/button_attribute_type.rst create mode 100644 content/developer/reference/user_interface/view_architectures/field_attribute_name.rst create mode 100644 content/developer/reference/user_interface/view_architectures/field_attribute_readonly.rst create mode 100644 content/developer/reference/user_interface/view_architectures/field_attribute_required.rst create mode 100644 content/developer/reference/user_interface/view_architectures/field_attribute_string.rst create mode 100644 content/developer/reference/user_interface/view_architectures/field_attribute_widget.rst rename content/developer/reference/user_interface/{view_architecture => view_architectures}/form_button_box.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/form_group.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/form_newline.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/form_notebook.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/form_separator.svg (100%) create mode 100644 content/developer/reference/user_interface/view_architectures/generic_attribute_class.rst create mode 100644 content/developer/reference/user_interface/view_architectures/generic_attribute_column_invisible.rst create mode 100644 content/developer/reference/user_interface/view_architectures/generic_attribute_groups.rst create mode 100644 content/developer/reference/user_interface/view_architectures/generic_attribute_invisible.rst rename content/developer/reference/user_interface/{view_architecture => view_architectures}/kanban.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/kanban_field.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/kanban_progressbar.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/list.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/list_button.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/list_control.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/list_field.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/list_groupby.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/list_header.svg (100%) create mode 100644 content/developer/reference/user_interface/view_architectures/root_attribute_banner_route.rst create mode 100644 content/developer/reference/user_interface/view_architectures/root_attribute_create.rst create mode 100644 content/developer/reference/user_interface/view_architectures/root_attribute_default_group_by.rst create mode 100644 content/developer/reference/user_interface/view_architectures/root_attribute_default_order.rst create mode 100644 content/developer/reference/user_interface/view_architectures/root_attribute_delete.rst create mode 100644 content/developer/reference/user_interface/view_architectures/root_attribute_edit.rst create mode 100644 content/developer/reference/user_interface/view_architectures/root_attribute_sample.rst create mode 100644 content/developer/reference/user_interface/view_architectures/root_attribute_string.rst rename content/developer/reference/user_interface/{view_architecture => view_architectures}/search.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/search_field.svg (100%) rename content/developer/reference/user_interface/{view_architecture => view_architectures}/search_filter.svg (100%) diff --git a/content/developer/howtos/standalone_owl_application.rst b/content/developer/howtos/standalone_owl_application.rst index 044b2af17..8eb0f5b51 100644 --- a/content/developer/howtos/standalone_owl_application.rst +++ b/content/developer/howtos/standalone_owl_application.rst @@ -108,7 +108,7 @@ layout. ======================================== Now that we have created our assets bundle, we need to create a -:ref:`QWeb view` that uses that assets bundle. +:ref:`QWeb view ` that uses that assets bundle. .. code-block:: xml diff --git a/content/developer/reference/backend/data.rst b/content/developer/reference/backend/data.rst index b47d67ae6..78acf54ca 100644 --- a/content/developer/reference/backend/data.rst +++ b/content/developer/reference/backend/data.rst @@ -236,7 +236,7 @@ Defines an ``ir.ui.menu`` record with a number of defaults and fallbacks: ``template`` ------------ -Creates a :ref:`QWeb view ` requiring only the ``arch`` +Creates a :ref:`QWeb view ` requiring only the ``arch`` section of the view, and allowing a few *optional* attributes: ``id`` diff --git a/content/developer/reference/external_api.rst b/content/developer/reference/external_api.rst index cd74f97af..eafad838e 100644 --- a/content/developer/reference/external_api.rst +++ b/content/developer/reference/external_api.rst @@ -1112,7 +1112,7 @@ Provides information about Odoo models via its various fields. list of the model's fields through a :class:`~odoo.fields.One2many` to :ref:`reference/webservice/inspection/fields` ``view_ids`` - :class:`~odoo.fields.One2many` to the :doc:`../reference/user_interface//view_architecture` + :class:`~odoo.fields.One2many` to the :doc:`../reference/user_interface/view_architectures` defined for the model ``access_ids`` :class:`~odoo.fields.One2many` relation to the diff --git a/content/developer/reference/frontend/qweb.rst b/content/developer/reference/frontend/qweb.rst index 863454308..38c51ac09 100644 --- a/content/developer/reference/frontend/qweb.rst +++ b/content/developer/reference/frontend/qweb.rst @@ -675,7 +675,7 @@ Request-based Most Python-side uses of QWeb are in controllers (and during HTTP requests), in which case templates stored in the database (as -:ref:`views `) can be trivially rendered by calling +:ref:`views `) can be trivially rendered by calling :meth:`odoo.http.HttpRequest.render`: .. code-block:: python diff --git a/content/developer/reference/user_interface.rst b/content/developer/reference/user_interface.rst index a9848649c..ad870da9d 100644 --- a/content/developer/reference/user_interface.rst +++ b/content/developer/reference/user_interface.rst @@ -8,6 +8,6 @@ User interface :titlesonly: user_interface/view_records - user_interface/view_architecture + user_interface/view_architectures user_interface/scss_inheritance user_interface/icons diff --git a/content/developer/reference/user_interface/icons.rst b/content/developer/reference/user_interface/icons.rst index ffcf68d51..3debe6e6f 100644 --- a/content/developer/reference/user_interface/icons.rst +++ b/content/developer/reference/user_interface/icons.rst @@ -1,5 +1,7 @@ :hide-page-toc: +.. _reference/user_interface/ui_icons: + ======== UI icons ======== diff --git a/content/developer/reference/user_interface/view_architecture.rst b/content/developer/reference/user_interface/view_architecture.rst deleted file mode 100644 index d541788e5..000000000 --- a/content/developer/reference/user_interface/view_architecture.rst +++ /dev/null @@ -1,4049 +0,0 @@ -================= -View architecture -================= - -Generic view -============ - -The architecture of a view is defined by XML data interpreted by the JavaScript framework. - -For each view, there is a :file:`\*.rng` file defining the attributes and possible architectures. - -.. note:: The current context and user access rights may also impact the view abilities. - -.. seealso:: - :doc:`view_records` - -.. _reference/view_architecture/python_expression: - -Python expression -================= - -When evaluating node attributes, e.g. the `readonly` modifier, it is possible to provide a **Python -expression** that will be executed in an environment that has access to the following variables: - -- The names of all fields present in the current view, containing the value of the current record, - except for `column_invisible` in :ref:`list view `; - relational fields are given as a list of IDs; -- `parent`: the record that refers to the container; only inside sub-views of :ref:`relational - fields `; -- `context` (dict_): the current view's context; -- `uid` (integer_): the id of the current user; -- `today` (string_): the current local date in the `YYYY-MM-DD` format; -- `now` (string_): the current local datetime in the `YYYY-MM-DD hh:mm:ss` format. - -.. example:: - .. code-block:: xml - - - - -.. example:: - .. code-block:: xml - - - - -
- - -
- -.. .................................................................... - -.. _reference/view_architecture/form: - -Form -==== - -Form views are used to display the data from a single record. Their root element is -``
``. They are composed of regular HTML_ with additional structural and semantic -components. - -.. code-block:: xml - - - ... -
- -Optional attributes_ are added on root element ``
`` to customize the view. - -:string: - string_ (default: ``''``) - - This view title is displayed only if you open an action that has no name and - whose target is 'new' (opening a dialog) - -:create: - boolean_ (default: ``True``) - - Disable/enable record creation on the view. - -:edit: - boolean_ (default: ``True``) - - Disable/enable record editing on the view. - -:duplicate: - boolean_ (default: ``True``) - - Disable/enable record duplication on the view through the **Action** dropdown. - -:delete: - boolean_ (default: ``True``) - - Disable/enable record deletion on the view through the **Action** dropdown. - -:js_class: - string_ (optional) - - Name of the javascript component the webclient will instantiating instead of - the form the view. - -:disable_autofocus: - boolean_ (default: ``False``) - - Disable automatic focussing of the first field in the view. - -.. _reference/view_architecture/form/semantic: - -Semantic components -------------------- - -Semantic components tie into the Odoo system and allow interaction with it. -remark: (with the remark style) -Placeholders are denoted in all caps. - -.. _reference/view_architecture/form/field: - -: render formatted values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: xml - - - - - -renders (and allow editing of, possibly) a single field of the current -record. Using several times a field in a form view is supported and the -fields can receive different values for modifiers 'invisible' and -'readonly'. This fields have the same values but can be display -differentaly. However, the behavior is not guaranteed when several -fields exist with different values for modifier 'required'. ```` -can have the following attributes: - -:name: - string_ (mandatory) :ref:`model ` field name - - the name of the field to render -:string: - string_ (default: `string` value from :class:`~odoo.fields.Field`) - - the label to display. By default display the field's label coming - from the field definition in the model. -:id: - string_ (optional) - - the node id. Useful when there are several occurrences of the same field in - the view (see ``label`` component below). Default is the field name. - -:widget: - string_ (optional) - - fields have a default rendering based on their type - (e.g. :class:`~odoo.fields.Char`, :class:`~odoo.fields.Many2one`). - - The ``widget`` attributes allows using a different rendering method and context. - See more information in :ref:`reference/js/widgets` - - .. code-block:: xml - - - -:options: - :ref:`python expression ` that evaluates to a dict_ (default: ``{}``) - - JSON object specifying configuration option for the field's widget - (including default widgets) - - .. code-block:: xml - - - -:groups: - `Comma-separated values`_ (optional) whose choices are the :class:`~odoo.addons.base.models.res_users.Groups` reference - - only displays the field for specific users - - .. code-block:: xml - - - -:domain: - :ref:`python expression ` that evaluates to a :ref:`reference/orm/domains` (default: ``[]``) - - for relational fields only, filters to apply when displaying existing - records for selection - - .. code-block:: xml - - - -:context: - :ref:`python expression ` that evaluates to a dict_ (default: ``{}``) - - for relational fields only, context to pass when fetching possible values. - The default values ``default_FIELD_NAME`` (e.g. ``{'default_name': 'toto'}``) will be used to - create the linked record. ``OTHER_BUSINESS_KEY`` is every keys depending of the model/module. - - .. code-block:: xml - - - -:readonly: - :ref:`python expression ` that evaluates to a boolean_ (default: ``False``) - - Whether the field can be modified by the user (``False``) or is read only (``True``). - - .. code-block:: xml - - - - -:required: - :ref:`python expression ` that evaluates to a boolean_ (default: ``False``) - - Whether the field can be left empty (``False``) or must be set (``True``). - - .. code-block:: xml - - - - -:invisible: - :ref:`python expression ` that evaluates to a boolean_ (default: ``False``) - - Whether the field can be visible (``False``) or must be hide (``True``). - - There are two uses for field ``invisible`` attribute: - - * Usability: not to overload the view and to make it easier for the user to read depending on the content; - * Technical: fetched by the webclient for evaluating :ref:`python expression ` - - .. code-block:: xml - - - - - -:nolabel: - boolean_ (default: ``False``) - - if ``True``, do not automatically display the field's label, only - makes sense if the field is a direct child of a ``group`` element - -:placeholder: - string_ (optional) - - help message to display in *empty* fields. Can replace field labels in - complex forms. *Should not* be an example of data as users are liable to - confuse placeholder text with filled fields - -:mode: - `Comma-separated values`_ (default: ``tree``) whose choices are: ``kanban``, ``from``, ``tree`` - - for :class:`~odoo.fields.One2many`, display mode (view type) to use for - the field's linked records. One of ``tree``, ``form``, ``kanban`` or - ``graph``. The default is ``tree`` (a list display) - -:help: - string_ (optional) - - tooltip displayed for users when hovering the field or its label - -:class: - string_ (optional) `HTML class`_ - - `HTML class`_ to set on the generated element. - - The styling use the Bootstrap_ framework and :doc:`UI icons `. - - Below are the common Odoo_ classes: - - ``oe_inline``: prevent the usual line break following fields and limit their span. - - ``oe_left``, ``oe_right``: floats_ the field to the corresponding direction - - ``oe_read_only``, ``oe_edit_only``: only displays the field in the corresponding form mode - - ``oe_avatar``: for image fields, displays images as "avatar" (square, 90x90 maximum size, some image decorations) - -:filename: - string_ (optional) - - for binary fields, name of the related field providing the name of the file - -:password: - boolean_ (default: ``False``) - - if is ``True`` indicates that a :class:`~odoo.fields.Char` field stores a - password and that its data shouldn't be displayed - -:kanban_view_ref: - string_ (optional) defined by the pattern: ``%(ADDON.MODEL_view_TYPE)s`` (target the :doc:`view reference `) - - for opening specific kanban view when selecting records from m2o/m2m in mobile - environment - -:default_focus: - boolean_ (default: ``False``) - - If True, defines that this field is the fields that will be focussed when the view - opens. Cannot be present on more than one field of a view. - -.. note:: - :ref:`Relational fields ` node can contain specific - subviews. - - .. code-block:: xml - - - - - -
- - - - - -.. _reference/view_architecture/form/label: - -