.. _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: Generic structure ================= Basic views generally share the common structure defined below. Placeholders are denoted in all caps. .. code-block:: xml NAME MODEL 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 `. * ``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. .. todo:: info on create/... in the context ? * ``create`` Disable/enable record creation on the view. * ``edit`` (``form`` & ``list`` & ``gantt``) Disable/enable record editing 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-{$name}`` (``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. Here are some of the other values available in the context: * ``uid``: the id of the current user, * ``today``: the current local date as a string of the form ``YYYY-MM-DD``, * ``now``: same as ``today`` with the addition of the current time. This value is formatted as ``YYYY-MM-DD hh:mm:ss``. .. code-block:: xml .. 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. * ``sample`` (``kanban`` & ``list`` & ``gantt`` & ``graph`` & ``pivot`` & ``cohort`` & ``dashboard``) Populate the view with a set of sample records if none are found for the current model. This attribute is false by default. These fake records will have heuristics for certain field names/models. For example, a field 'display_name' on the model 'res.users' will be populated with sample people names while an 'email' field will be in the form 'firstname.lastname@sample.demo'. The user will not be able to interact with these data and they will be discarded as soon as an action is performed (record created, column added, etc.) * ``banner_route`` a route address to be fetched and prepended to the view. If this attribute is set, the :ref:`controller route url` 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 tag, it will be removed and appended to . To interact with the backend you can use 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 .. code-block:: python class MyController(odoo.http.Controller): @http.route('/module_name/hello', auth='user', type='json') def hello(self): return { 'html': """

hello, world

""" } .. 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. Specify the parent using the `ref` attribute: .. code-block:: xml * ``mode`` :class:`~odoo.fields.Selection`: `extension / primary` inheritance mode, ``extension`` by default if ``inherit_id`` is set, ``primary`` otherwise. An example of where you would want to override ``mode`` while using ``inherit_id`` is delegation inheritance. In that case your derived model will be separate from its parent and views matching with one won't match with the other. Suppose you inherit from a view associated with the parent model and want to customize the derived view to show data from the derived model. The ``mode`` of the derived view needs to be set to ``primary``, because it's the base (and maybe only) view for that derived model. Otherwise the :ref:`view matching ` rules won't apply. .. _reference/views/inheritance/view-matching: 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. * when a view is requested by ``id``, if its mode is not ``primary`` its *closest* parent with mode ``primary`` is matched. View resolution --------------- Resolution generates the final ``arch`` for a requested/matched ``primary`` view: #. if the view has a parent, the parent is fully resolved then the current view's inheritance specs are applied #. if the view has no parent, its ``arch`` is used as-is #. the current view's children with mode ``extension`` are looked up and their inheritance specs are applied depth-first (a child view is applied, then its children, then its siblings) The result of applying children views yields the final ``arch`` .. todo:: NOTE on fields_view_get and link to ORM ? Inheritance specs ----------------- Inheritance specs are comprised of an element locator, to match the inherited element in the parent view, and children element that will be used to modify the inherited element. There are three types of element locators for matching a target element: * An ``xpath`` element with an ``expr`` attribute. ``expr`` is an XPath_ expression\ [#hasclass]_ applied to the current ``arch``, the first node it finds is the match * a ``field`` element with a ``name`` attribute, matches the first ``field`` with the same ``name``. All other attributes are ignored during matching * any other element: the first element with the same name and identical attributes (ignoring ``position`` and ``version`` attributes) is matched .. code-block:: xml
The inheritance spec may have an optional ``position`` attribute specifying how the matched node should be altered: ``inside`` (default) the content of the inheritance spec is appended to the matched node ``replace`` the content of the inheritance spec replaces the matched node. Any text node containing only ``$0`` within the contents of the spec will be replaced by a complete copy of the matched node, effectively wrapping the matched node. ``after`` the content of the inheritance spec is added to the matched node's parent, after the matched node ``before`` the content of the inheritance spec is added to the matched node's parent, before the matched node ``attributes`` the content of the inheritance spec should be ``attribute`` elements with a ``name`` attribute and an optional body: * if the ``attribute`` element has a body, a new attributed named after its ``name`` is created on the matched node with the ``attribute`` element's text as value * if the ``attribute`` element has no body, the attribute named after its ``name`` is removed from the matched node. If no such attribute exists, an error is raised .. code-block:: xml 0 {'invisible': [('sale_ok', '=', False)], 'readonly': [('editable', '=', False)]} ``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. .. code-block:: xml A view's specs are applied sequentially. .. [#hasclass] an extension function is added for simpler matching in QWeb views: ``hasclass(*classes)`` matches if the context node has all the specified classes .. _reference/views/types: View types ========== .. _reference/views/activity: 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. .. warning:: The Activity view is only available when the ``mail`` module is installed, and for the models that inherit from the ``mail.activity.mixin``. The root element of the Activity view is ````, it accepts the following attributes: - ``string`` (mandatory) A title, which should describe the view Possible children of the view element are: ``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. Possible attributes are: ``name`` (required) the name of the field to fetch ``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. The activity view uses mostly-standard :ref:`javascript qweb ` and provides the following context variables (see :ref:`reference/views/kanban` for more details): ``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`` .. _reference/views/calendar: Calendar -------- Calendar views display records as events in a daily, weekly, monthly or yearly calendar. .. note:: By default the calendar view will be centered around the current date (today). You can pass a specific initial date to the context of the action in order to set the initial focus of the calendar on the period (see `mode`) around this date (the context key to use being `initial_date`) Their root element is ````. Available attributes on the calendar view are: ``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`` (the field to which this values is saved can be controlled through ``rec_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 ``create_name_field`` name of the record's field holding the textual representation of the record, this is used when creating records through the 'quick create' mechanism ``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``, ``year`` ``scales`` Comma-separated list of scales to provide. By default, all scales are available. See mode for possible scale values. ```` 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: * ``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`` and ``filter_field`` you can add a filter and save the result in the defined model, the filter is added in the sidebar. The ``filter_field`` is optional and allows you to specify the field that will hold the status of the filter. * ``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. .. _reference/views/cohort: Cohort ------ .. raw:: html Enterprise feature 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 The root element of the Cohort view is , 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. ```` (optional) allows to specify a particular field in order to manage it from the available measures, it's main use is for hiding a field from the selectable measures: - ``name`` (mandatory) the name of the field to use in the view. - ``string`` (optional) the name that would be used to display the field in the cohort view, overrides the default python String attribute of the field. - ``invisible`` (optional) 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 $). .. _reference/views/dashboard: Dashboard --------- .. raw:: html Enterprise feature 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 The root element of the Dashboard view is , 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 - ``col`` (optional) The number of columns spanned by this tag (only makes sense inside a group). By default, 1. - ``widget`` (optional) A widget to format the value (like the widget attribute for fields). For example, monetary. - ``help`` (optional) A help message to dipslay in a tooltip (equivalent of help for a field in python) - ``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. .. code-block:: xml - ``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. - ``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. ``formula`` declares a derived value. Formulas are values computed from aggregates. Note that like aggregates, formulas are supposed to be used inside a group tag (otherwise the style will not be properly applied). Admissible attributes are: - ``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``. - ``name`` (optional) A string to identify this formula - ``string`` (optional) A short description that will be displayed above the formula. - ``col`` (optional) The number of columns spanned by this tag (only makes sense inside a group). By default, 1. - ``widget`` (optional) A widget to format the value (like the widget attribute for fields). For example, monetary. By default, it is 'float'. - ``help`` (optional) A help message to dipslay in a tooltip (equivalent of help for a field in python) - ``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. ``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: 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. Structural components ~~~~~~~~~~~~~~~~~~~~~ Structural components provide structure or "visual" features with little logic. They are used as elements or sets of elements in form views. ``notebook`` defines a tabbed section. Each tab is defined through a ``page`` child element. Pages can have the following attributes: * ``string`` (required) the title of the tab * ``accesskey`` an HTML accesskey_ * ``attrs`` standard dynamic attributes based on record values .. note:: Note that ``notebook`` should not be placed within ``group`` ``group`` used to define column layouts in forms. By default, groups define 2 columns and most direct children of groups take a single column. ``field`` direct children of groups display a label by default, and the label and the field itself have a colspan of 1 each. The number of columns in a ``group`` can be customized using the ``col`` attribute, the number of columns taken by an element can be customized using ``colspan``. Children are laid out horizontally (tries to fill the next column before changing row). Groups can have a ``string`` attribute, which is displayed as the group's title ``newline`` only useful within ``group`` elements, ends the current row early and immediately switches to a new row (without filling any remaining column beforehand) ``separator`` small horizontal spacing, with a ``string`` attribute behaves as a section title ``sheet`` can be used as a direct child to ``form`` for a narrower and more responsive form layout ``header`` combined with ``sheet``, provides a full-width location above the sheet 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: ``button`` call into the Odoo system, similar to :ref:`list view buttons `. In addition, the following attribute can be specified: ``special`` for form views opened in dialogs: ``save`` to save the record and close the dialog, ``cancel`` to close the dialog without saving. ``confirm`` confirmation message to display (and for the user to accept) before performing the button's Odoo call (also works in Kanban views). ``field`` 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'. However, the behavior is not guaranteed when several fields exist with different values for modifier 'required'. Possible attributes of the field node are: ``name`` (mandatory) the name of the field to render ``id`` 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`` 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. .. todo:: list of widgets & options & specific attributes (e.g. widget=statusbar statusbar_visible clickable) ``options`` JSON object specifying configuration option for the field's widget (including default widgets) ``class`` HTML class to set on the generated element, common field classes are: ``oe_inline`` prevent the usual line break following fields ``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) ``groups`` only displays the field for specific users ``on_change`` calls the specified method when this field's value is edited, can generate update other fields or display warnings for the user .. deprecated:: 8.0 Use :func:`odoo.api.onchange` on the model ``attrs`` dynamic meta-parameters based on record values ``domain`` for relational fields only, filters to apply when displaying existing records for selection ``context`` for relational fields only, context to pass when fetching possible values ``readonly`` display the field in both readonly and edit mode, but never make it editable ``required`` generates an error and prevents saving the record if the field doesn't have a value ``nolabel`` don't automatically display the field's label, only makes sense if the field is a direct child of a ``group`` element ``placeholder`` 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`` 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`` tooltip displayed for users when hovering the field or its label ``filename`` for binary fields, name of the related field providing the name of the file ``password`` indicates that a :class:`~odoo.fields.Char` field stores a password and that its data shouldn't be displayed ``kanban_view_ref`` for opening specific kanban view when selecting records from m2o/m2m in mobile environment ``label`` when a ``field`` component isn't placed directly inside a ``group``, or when its ``nolabel`` attribute is set, the field's label isn't automatically displayed alongside its value. The ``label`` component is the manual alternative of displaying the label of a field. Possible attributes are: ``for`` (mandatory) the reference to the field associated with the label. Can be either the name of a field, or its id (``id`` attribute set on the ``field``). When there are several occurrences of the same field in the view, and there are several ``label`` components associated with these ``field`` nodes, those labels must have unique ``for`` attributes (in this case referencing the ``id`` attribute of the corresponding ``field`` nodes). ``string`` the label to display. Display the field's label (coming from the field definition in the model) by default. ``class`` same as for ``field`` component. ``attrs`` same as for ``field`` component. Generic structure ~~~~~~~~~~~~~~~~~ .. code-block:: xml
.. todo:: classes for forms .. todo:: widgets? .. _reference/views/gantt: Gantt ----- .. raw:: html Enterprise feature Gantt views appropriately display Gantt charts (for scheduling). The root element of gantt views is ````, 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. Here are some of the other values available in the context: * ``uid``: the id of the current user, * ``today``: the current local date as a string of the form ``YYYY-MM-DD``, * ``now``: same as ``today`` with the addition of the current time. This value is formatted as ``YYYY-MM-DD hh:mm:ss``. ``{$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 ``disable_drag_drop`` if set to true, the gantt view will not have any drag&drop support ``consolidation`` field name to display consolidation value in record cell ``consolidation_max`` dictionary 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``, ``cell_create``, ``edit``, ``delete``, ``plan`` allows *dis*\ abling the corresponding action in the view by setting the corresponding attribute to ``false`` (default: ``true``). * ``create``: If enabled, an ``Add`` button will be available in the control panel to create records. * ``cell_create``: If enabled and ``create`` enabled, a "**+**" button will be displayed while hovering on a time slot cell to create a new record on that slot. * ``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 ` 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 will display the users avatars next to their names when grouped by user_id. .. _reference/views/graph: Graph ----- The graph view is used to visualize aggregations over a number of records or record groups. Its root element is ```` which can take the following attributes: ``type`` (optional) one of ``bar`` (default), ``pie`` and ``line``, the type of graph to use ``stacked`` (optional) only used for ``bar`` charts. Set to ``0`` to prevent the bars within a group to be stacked initially. ``disable_linking`` (optional) set to ``1`` to prevent from redirecting clicks on graph to list view ``order`` (optional) if set, x-axis values will be sorted by default according their measure with respect to the given order (``asc`` or ``desc``). Only used for ``bar`` and ``pie`` charts. ``string`` (optional) string displayed in the breadcrumbs when redirecting to list view. The only allowed element within a graph view is ``field`` which can have the following attributes: ``name`` (mandatory) the name of a field to use in the view. If used for grouping (rather than aggregating) ``invisible`` (optional) if true, the field will not appear either in the active measures nor in the selectable measures. ``type`` (optional) if set to ``measure``, the field will be used as an aggregated value within a group instead of a grouping criteria. It only works for the last field with that attribute but it is useful for other fields with string attribute (see below). ``interval`` (optional) 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). Default is ``month``. ``string`` (optional) only used for field with ``type="measure"``. The name that will be used to display the field in the graph view, overrides the default python String attribute of the field. 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:: 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 Enterprise feature 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: ```` (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 positive 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. ``