9 .. _reference/views/structure:
14 View objects expose a number of fields, they are optional unless specified
18 only useful as a mnemonic/description of the view when looking for one in
21 the model linked to the view, if applicable (it doesn't for QWeb views)
23 client programs can request views by ``id``, or by ``(model, type)``. For
24 the latter, all the views for the right type and model will be looked for,
25 and the one with the lowest ``priority`` number will be returned (it is
28 ``priority`` also defines the order of application during :ref:`view
29 inheritance <reference/views/inheritance>`
31 the description of the view's layout
33 :class:`~openerp.fields.Many2many` field to the groups allowed to view/use
36 the current view's parent view, see :ref:`reference/views/inheritance`,
39 inheritance mode, see :ref:`reference/views/inheritance`. If
40 ``inherit_id`` is unset the ``mode`` can only be ``primary``. If
41 ``inherit_id`` is set, ``extension`` by default but can be explicitly set
44 website feature defining togglable views. By default, views are always
47 .. _reference/views/inheritance:
55 * if a view is requested by ``(model, type)``, the view with the right model
56 and type, ``mode=primary`` and the lowest priority is matched
57 * when a view is requested by ``id``, if its mode is not ``primary`` its
58 *closest* parent with mode ``primary`` is matched
63 Resolution generates the final ``arch`` for a requested/matched ``primary``
66 #. if the view has a parent, the parent is fully resolved then the current
67 view's inheritance specs are applied
68 #. if the view has no parent, its ``arch`` is used as-is
69 #. the current view's children with mode ``extension`` are looked up and their
70 inheritance specs are applied depth-first (a child view is applied, then
71 its children, then its siblings)
73 The result of applying children views yields the final ``arch``
78 There are three types of inheritance specs:
80 * An ``xpath`` element with an ``expr`` attribute. ``expr`` is an XPath_
81 expression\ [#hasclass]_ applied to the current ``arch``, the first node
83 * a ``field`` element with a ``name`` attribute, matches the first ``field``
84 with the same ``name``
85 * any other element, the first element with the same name and identical
86 attributes (ignoring ``position``) is matched
88 The inheritance spec may have an optional ``position`` attribute specifying
89 how the matched node should be altered:
92 the content of the inheritance spec is appended to the matched node
94 the content of the inheritance spec replaces the matched node
96 the content of the inheritance spec is added to the matched node's
97 parent, after the matched node
99 the content of the inheritance spec is added to the matched node's
100 parent, before the matched node
102 the content of the inheritance spec should be ``attribute`` elements
103 with a ``name`` attribute and an optional body:
105 * if the ``attribute`` element has a body, a new attributed named
106 after its ``name`` is created on the matched node with the
107 ``attribute`` element's text as value
108 * if the ``attribute`` element has no body, the attribute named after
109 its ``name`` is removed from the matched node. If no such attribute
110 exists, an error is raised
112 A view's specs are applied sequentially.
114 .. _reference/views/list:
119 The root element of list views is ``<tree>``\ [#treehistory]_. The list view's
120 root can have the following attributes:
123 by default, selecting a list view's row opens the corresponding
124 :ref:`form view <reference/views/form>`. The ``editable`` attributes makes
125 the list view itself editable in-place.
127 Valid values are ``top`` and ``bottom``, making *new* records appear
128 respectively at the top or bottom of the list.
130 The architecture for the inline :ref:`form view <reference/views/form>` is
131 derived from the list view. Most attributes valid on a :ref:`form view
132 <reference/views/form>`'s fields and buttons are thus accepted by list
133 views although they may not have any meaning if the list view is
136 overrides the ordering of the view, replacing the model's default order.
137 The value is a comma-separated list of fields, postfixed by ``desc`` to
138 sort in reverse order:
142 <tree default_order="sequence,name desc">
144 allows changing the color of a row's text based on the corresponding
147 Defined as a mapping of colors to Python expressions. Values are of the
148 form: :samp:`{color}:{expr}[;...]`. For each record, pairs are tested
149 in-order, the expression is evaluated for the record and if ``true`` the
150 corresponding color is applied to the row. If no color matches, uses the
151 default text color (black).
153 * ``color`` can be any valid `CSS color unit`_.
154 * ``expr`` should be a Python expression evaluated with the current
155 record's attributes as context values. Other context values are ``uid``
156 (the id of the current user) and ``current_date`` (the current date as
157 a string of the form ``yyyy-MM-dd``)
159 allows changing a row's font style based on the corresponding record's
162 The format is the same as for ``color``, but the ``color`` of each pair
163 is replaced by ``bold``, ``italic`` or ``underline``, the expression
164 evaluating to ``true`` will apply the corresponding style to the row's
165 text. Contrary to ``colors``, multiple pairs can match each record
166 ``create``, ``edit``, ``delete``
167 allows *dis*\ abling the corresponding action in the view by setting the
168 corresponding attribute to ``false``
170 only makes sense on an ``editable`` list. Should be the name of a method
171 on the list's model. The method will be called with the ``id`` of a record
172 after having created or edited that record (in database).
174 The method should return a list of ids of other records to load or update.
176 alternative translatable label for the view
180 not displayed anymore
182 .. toolbar attribute is for tree-tree views
184 Possible children elements of the list view are:
186 .. _reference/views/list/button:
189 displays a button in a list cell
192 icon to use to display the button
194 * if there is no ``icon``, the button's text
195 * if there is an ``icon``, ``alt`` text for the icon
197 type of button, indicates how it clicking it affects Odoo:
199 ``workflow`` (default)
200 sends a signal to a workflow. The button's ``name`` is the
201 workflow signal, the row's record is passed as argument to the
204 call a method on the list's model. The button's ``name`` is the
205 method, which is called with the current row's record id and the
208 .. web client also supports a @args, which allows providing
209 additional arguments as JSON. Should that be documented? Does
210 not seem to be used anywhere
213 load an execute an ``ir.actions``, the button's ``name`` is the
214 database id of the action. The context is expanded with the list's
215 model (as ``active_model``), the current row's record
216 (``active_id``) and all the records currently loaded in the list
217 (``active_ids``, may be just a subset of the database records
218 matching the current search)
224 dynamic attributes based on record values.
226 A mapping of attributes to domains, domains are evaluated in the
227 context of the current row's record, if ``True`` the corresponding
228 attribute is set on the cell.
230 Possible attributes are ``invisible`` (hides the button) and
231 ``readonly`` (disables the button but still shows it)
233 shorthand for ``invisible`` ``attrs``: a list of space, separated
234 states, requires that the model has a ``state`` field and that it is
237 Makes the button ``invisible`` if the record is *not* in one of the
240 merged into the view's context when performing the button's Odoo call
242 confirmation message to display (and for the user to accept) before
243 performing the button's Odoo call
245 .. declared but unused: help
248 defines a column where the corresponding field should be displayed for
249 each record. Can use the following attributes:
252 the name of the field to display in the current model. A given name
253 can only be used once per view
255 the title of the field's column (by default, uses the ``string`` of
258 fetches and stores the field, but doesn't display the column in the
259 table. Necessary for fields which shouldn't be displayed but are
260 used by e.g. ``@colors``
262 lists the groups which should be able to see the field
264 alternate representations for a field's display. Possible list view
268 displays ``float`` fields as a progress bar.
270 replaces the m2o field's value by a checkmark if the field is
271 filled, and a cross if it is not
273 for ``sequence`` fields, instead of displaying the field's value
274 just displays a dra&drop icon
276 displays the corresponding aggregate at the bottom of the column. The
277 aggregation is only computed on *currently displayed* records. The
278 aggregation operation must match the corresponding field's
281 dynamic attributes based on record values. Only effects the current
282 field, so e.g. ``invisible`` will hide the field but leave the same
283 field of other records visible, it will not hide the column itself
285 .. note:: if the list view is ``editable``, any field attribute from the
286 :ref:`form view <reference/views/form>` is also valid and will
287 be used when setting up the inline form view
289 .. _reference/views/form:
294 Form views are used to display the data from a single record. Their root
295 element is ``<form>``. They are composed of regular HTML_ with additional
296 structural and semantic components.
298 Structural components
299 ---------------------
301 Structural components provide structure or "visual" features with little
302 logic. They are used as elements or sets of elements in form views.
305 defines a tabbed section. Each tab is defined through a ``page`` child
306 element. Pages can have the following attributes:
308 ``string`` (required)
313 standard dynamic attributes based on record values
316 used to define column layouts in forms. By default, groups define 2 columns
317 and most direct children of groups take a single column. ``field`` direct
318 children of groups display a label by default, and the label and the field
319 itself have a colspan of 1 each.
321 The number of columns in a ``group`` can be customized using the ``col``
322 attribute, the number of columns taken by an element can be customized using
325 Children are laid out horizontally (tries to fill the next column before
328 Groups can have a ``string`` attribute, which is displayed as the group's
331 only useful within ``group`` elements, ends the current row early and
332 immediately switches to a new row (without filling any remaining column
335 small horizontal spacing, with a ``string`` attribute behaves as a section
338 can be used as a direct child to ``form`` for a narrower and more responsive
341 combined with ``sheet``, provides a full-width location above the sheet
342 itself, generally used to display workflow buttons and status widgets
347 Semantic components tie into and allow interaction with the Odoo
348 system. Available semantic components are:
351 call into the Odoo system, similar to :ref:`list view buttons
352 <reference/views/list/button>`
354 renders (and allow edition of, possibly) a single field of the current
355 record. Possible attributes are:
358 the name of the field to render
360 fields have a default rendering based on their type
361 (e.g. :class:`~openerp.fields.Char`,
362 :class:`~openerp.fields.Many2one`). The ``widget`` attributes allows using
363 a different rendering method and context.
365 .. todo:: list of widgets
367 & options & specific attributes (e.g. widget=statusbar
368 statusbar_visible statusbar_colors clickable)
370 JSON object specifying configuration option for the field's widget
371 (including default widgets)
373 HTML class to set on the generated element, common field classes are:
376 prevent the usual line break following fields
377 ``oe_left``, ``oe_right``
378 floats_ the field to the corresponding direction
379 ``oe_read_only``, ``oe_edit_only``
380 only displays the field in the corresponding form mode
382 avoids displaying the navigation button in a
383 :class:`~openerp.fields.Many2one`
385 for image fields, displays images as "avatar" (square, 90x90 maximum
386 size, some image decorations)
388 only displays the field for specific users
390 calls the specified method when this field's value is edited, can generate
391 update other fields or display warnings for the user
395 Use :func:`openerp.api.onchange` on the model
398 dynamic meta-parameters based on record values
400 for relational fields only, filters to apply when displaying existing
401 records for selection
403 for relational fields only, context to pass when fetching possible values
405 display the field in both readonly and edition mode, but never make it
408 generates an error and prevents saving the record if the field doesn't
411 don't automatically display the field's label, only makes sense if the
412 field is a direct child of a ``group`` element
414 help message to display in *empty* fields. Can replace field labels in
415 complex forms. *Should not* be an example of data as users are liable to
416 confuse placeholder text with filled fields
418 for :class:`~openerp.fields.One2many`, display mode (view type) to use for
419 the field's linked records. One of ``tree``, ``form``, ``kanban`` or
420 ``graph``. The default is ``tree`` (a list display)
422 tooltip displayed for users when hovering the field or its label
424 for binary fields, name of the related field providing the name of the
427 indicates that a :class:`~openerp.fields.Char` field stores a password and
428 that its data shouldn't be displayed
430 .. todo:: classes for forms
434 Business Views guidelines
435 -------------------------
437 .. sectionauthor:: Aline Preillon, Raphael Collet
439 Business views are targeted at regular users, not advanced users. Examples
440 are: Opportunities, Products, Partners, Tasks, Projects, etc.
442 .. image:: forms/oppreadonly.png
443 :class: img-responsive
445 In general, a business view is composed of
447 1. a status bar on top (with technical or business flow),
448 2. a sheet in the middle (the form itself),
449 3. a bottom part with History and Comments.
451 Technically, the new form views are structured as follows in XML::
454 <header> ... content of the status bar ... </header>
455 <sheet> ... content of the sheet ... </sheet>
456 <div class="oe_chatter"> ... content of the bottom part ... </div>
462 The purpose of the status bar is to show the status of the current record and
465 .. image:: forms/status.png
466 :class: img-responsive
471 The order of buttons follows the business flow. For instance, in a sale order,
472 the logical steps are:
474 1. Send the quotation
475 2. Confirm the quotation
476 3. Create the final invoice
479 Highlighted buttons (in red by default) emphasize the logical next step, to
480 help the user. It is usually the first active button. On the other hand,
481 :guilabel:`cancel` buttons *must* remain grey (normal). For instance, in
482 Invoice the button :guilabel:`Refund` must never be red.
484 Technically, buttons are highlighted by adding the class "oe_highlight"::
486 <button class="oe_highlight" name="..." type="..." states="..."/>
491 Uses the ``statusbar`` widget, and shows the current state in red. States
492 common to all flows (for instance, a sale order begins as a quotation, then we
493 send it, then it becomes a full sale order, and finally it is done) should be
494 visible at all times but exceptions or states depending on particular sub-flow
495 should only be visible when current.
497 .. image:: forms/status1.png
498 :class: img-responsive
500 .. image:: forms/status2.png
501 :class: img-responsive
503 The states are shown following the order used in the field (the list in a
504 selection field, etc). States that are always visible are specified with the
505 attribute ``statusbar_visible``.
507 ``statusbar_colors`` can be used to give a custom color to specific states.
511 <field name="state" widget="statusbar"
512 statusbar_visible="draft,sent,progress,invoiced,done"
513 statusbar_colors="{'shipping_except':'red','waiting_date':'blue'}"/>
518 All business views should look like a printed sheet:
520 .. image:: forms/sheet.png
521 :class: img-responsive
523 1. Elements inside a ``<form>`` or ``<page>`` do not define groups, elements
524 inside them are laid out according to normal HTML rules. They content can
525 be explicitly grouped using ``<group>`` or regular ``<div>`` elements.
526 2. By default, the element ``<group>`` defines two columns inside, unless an
527 attribute ``col="n"`` is used. The columns have the same width (1/n th of
528 the group's width). Use a ``<group>`` element to produce a column of fields.
529 3. To give a title to a section, add a ``string`` attribute to a ``<group>`` element::
531 <group string="Time-sensitive operations">
533 this replaces the former use of ``<separator string="XXX"/>``.
534 4. The ``<field>`` element does not produce a label, except as direct children
535 of a ``<group>`` element\ [#backwards-compatibility]_. Use :samp:`<label
536 for="{field_name}>` to produce a label of a field.
541 Some sheets have headers with one or more fields, and the labels of those
542 fields are only shown in edit mode.
549 * - .. image:: forms/header.png
550 :class: img-responsive
551 - .. image:: forms/header2.png
552 :class: img-responsive
554 Use HTML text, ``<div>``, ``<h1>``, ``<h2>``… to produce nice headers, and
555 ``<label>`` with the class ``oe_edit_only`` to only display the field's label
556 in edit mode. The class ``oe_inline`` will make fields inline (instead of
557 blocks): content following the field will be displayed on the same line rather
558 than on the line below it. The form above is produced by the following XML::
560 <label for="name" class="oe_edit_only"/>
561 <h1><field name="name"/></h1>
563 <label for="planned_revenue" class="oe_edit_only"/>
565 <field name="planned_revenue" class="oe_inline"/>
566 <field name="company_currency" class="oe_inline oe_edit_only"/> at
567 <field name="probability" class="oe_inline"/> % success rate
573 Many relevant actions or links can be displayed in the form. For example, in
574 Opportunity form, the actions "Schedule a Call" and "Schedule a Meeting" take
575 an important place in the use of the CRM. Instead of placing them in the
576 "More" menu, put them directly in the sheet as buttons (on the top right) to
577 make them more visible and more easily accessible.
579 .. image:: forms/header3.png
580 :class: img-responsive
582 Technically, the buttons are placed inside a <div> to group them as a block on
583 the right-hand side of the sheet.
587 <div class="oe_button_box oe_right">
588 <button string="Schedule/Log Call" name="..." type="action"/>
589 <button string="Schedule Meeting" name="action_makeMeeting" type="object"/>
595 A column of fields is now produced with a ``<group>`` element, with an
598 .. image:: forms/screenshot-03.png
599 :class: img-responsive
603 <group string="Payment Options">
604 <field name="writeoff_amount"/>
605 <field name="payment_option"/>
608 It is recommended to have two columns of fields on the form. For this, simply
609 put the ``<group>`` elements that contain the fields inside a top-level
612 To make :ref:`view extension <reference/views/inheritance>` simpler, it is
613 recommended to put a ``name`` attribute on ``<group>`` elements, so new fields
614 can easily be added at the right place.
616 Special Case: Subtotals
617 ~~~~~~~~~~~~~~~~~~~~~~~
619 Some classes are defined to render subtotals like in invoice forms:
621 .. image:: forms/screenshot-00.png
622 :class: img-responsive
626 <group class="oe_subtotal_footer">
627 <field name="amount_untaxed"/>
628 <field name="amount_tax"/>
629 <field name="amount_total" class="oe_subtotal_footer_separator"/>
630 <field name="residual" style="margin-top: 10px"/>
633 Placeholders and Inline Fields
634 ..............................
636 Sometimes field labels make the form too complex. One can omit field labels,
637 and instead put a placeholder inside the field. The placeholder text is
638 visible only when the field is empty. The placeholder should tell what to
639 place inside the field, it *must not* be an example as they are often confused
642 One can also group fields together by rendering them "inline" inside an
643 explicit block element like `<div>``. This allows grouping semantically
644 related fields as if they were a single (composite) fields.
646 The following example, taken from the *Leads* form, shows both placeholders and
647 inline fields (zip and city).
654 * - .. image:: forms/placeholder.png
655 :class: img-responsive
656 - .. image:: forms/screenshot-01.png
657 :class: img-responsive
662 <label for="street" string="Address"/>
664 <field name="street" placeholder="Street..."/>
665 <field name="street2"/>
667 <field name="zip" class="oe_inline" placeholder="ZIP"/>
668 <field name="city" class="oe_inline" placeholder="City"/>
670 <field name="state_id" placeholder="State"/>
671 <field name="country_id" placeholder="Country"/>
678 Images, like avatars, should be displayed on the right of the sheet. The
679 product form looks like:
681 .. image:: forms/screenshot-02.png
682 :class: img-responsive
684 The form above contains a <sheet> element that starts with:
688 <field name="product_image" widget="image" class="oe_avatar oe_right"/>
693 Most :class:`~openerp.fields.Many2many` fields, like categories, are better
694 rendered as a list of tags. Use the widget ``many2many_tags`` for this:
696 .. image:: forms/screenshot-04.png
697 :class: img-responsive
701 <field name="category_id" widget="many2many_tags"/>
703 Configuration forms guidelines
704 ------------------------------
706 Examples of configuration forms: Stages, Leave Type, etc. This concerns all
707 menu items under Configuration of each application (like Sales/Configuration).
709 .. image:: forms/nosheet.png
710 :class: img-responsive
712 1. no header (because no state, no workflow, no button)
715 Dialog forms guidelines
716 -----------------------
718 Example: "Schedule a Call" from an opportunity.
720 .. image:: forms/wizard-popup.png
721 :class: img-responsive
723 1. avoid separators (the title is already in the popup title bar, so another
724 separator is not relevant)
725 2. avoid cancel buttons (user generally close the popup window to get the same
727 3. action buttons must be highlighted (red)
728 4. when there is a text area, use a placeholder instead of a label or a
730 5. like in regular form views, put buttons in the <header> element
732 Configuration Wizards guidelines
733 --------------------------------
735 Example: Settings / Configuration / Sales.
737 1. always in line (no popup)
739 3. keep the cancel button (users cannot close the window)
740 4. the button "Apply" must be red
743 .. _reference/views/graph:
748 The graph view is used to visualize aggregations over a number of records or
749 record groups. Its root element is ``<graph>`` which can take the following
753 one of ``bar`` (default), ``pie``, ``line`` and ``pivot``, the type of graph
754 to use (``pivot`` technically isn't a graph type, it displays the
755 aggregation as a `pivot table`_)
757 only used for ``bar`` charts. If present and set to ``True``, stacks bars
760 The only allowed element within a graph view is ``field`` which can have the
761 following attributes:
764 the name of a field to use in a graph view. If used for grouping (rather
768 indicates whether the field should be used as a grouping criteria or as an
769 aggregated value within a group. Possible values are:
772 groups by the specified field. All graph types support at least one level
773 of grouping, some may support more. For pivot tables, each group gets its
776 only used by pivot tables, creates column-wise groups
778 field to aggregate within a group
781 on date and datetime fields, groups by the specified interval (``day``,
782 ``week``, ``month``, ``quarter`` or ``year``) instead of grouping on the
783 specific datetime (fixed second resolution) or date (fixed day resolution).
787 graph view aggregations are performed on database content, non-stored
788 function fields can not be used in graph views
790 .. _reference/views/kanban:
795 The kanban view is a `kanban board`_ visualisation: it displays records as
796 "cards", halfway between a :ref:`list view <reference/views/list>` and a
797 non-editable :ref:`form view <reference/views/form>`. Records may be grouped
798 in columns for use in workflow visualisation or manipulation (e.g. tasks or
799 work-progress management), or ungrouped (used simply to visualize records).
801 The root element of the Kanban view is ``<kanban>``, it can use the following
805 whether the kanban view should be grouped if no grouping is specified via
806 the action or the current research. Should be the name of the field to group
807 by when no grouping is otherwise specified
809 cards sorting order used if the user has not already sorted the records (via
812 adds HTML classes to the root HTML element of the Kanban view
814 whether it should be possible to create records without switching to the
815 form view. By default, ``quick_create`` is enabled when the Kanban view is
816 grouped, and disabled when not.
818 Set to ``true`` to always enable it, and to ``false`` to always disable it.
820 Possible children of the view element are:
823 declares fields to aggregate or to use in kanban *logic*. If the field is
824 simply displayed in the kanban view, it does not need to be pre-declared.
826 Possible attributes are:
829 the name of the field to fetch
830 ``sum``, ``avg``, ``min``, ``max``, ``count``
831 displays the corresponding aggregation at the top of a kanban column, the
832 field's value is the label of the aggregation (a string). Only one
833 aggregate operation per field is supported.
836 defines a list of :ref:`reference/qweb` templates. Cards definition may be
837 split into multiple templates for clarity, but kanban views *must* define at
838 least one root template ``kanban-box``, which will be rendered once for each
841 The kanban view uses mostly-standard :ref:`javascript qweb
842 <reference/qweb/javascript>` and provides the following context variables:
845 the current :ref:`reference/javascript/client` instance
847 the current :js:class:`KanbanRecord`, can be used to fetch some
848 meta-information. These methods are also available directly in the
849 template context and don't need to be accessed via ``widget``
851 an object with all the requested fields as its attributes. Each field has
852 two attributes ``value`` and ``raw_value``, the former is formatted
853 according to current user parameters, the latter is the direct value from
854 a :meth:`~openerp.models.Model.read`
859 .. rubric:: buttons and fields
861 While most of the Kanban templates are standard :ref:`reference/qweb`, the
862 Kanban view processes ``field``, ``button`` and ``a`` elements specially:
864 * by default fields are replaced by their formatted value, unless they
865 match specific kanban view widgets
867 .. todo:: list widgets?
869 * buttons and links with a ``type`` attribute become perform Odoo-related
870 operations rather than their standard HTML function. Possible types are:
872 ``action``, ``object``
873 standard behavior for :ref:`Odoo buttons
874 <reference/views/list/button>`, most attributes relevant to standard
875 Odoo buttons can be used.
877 opens the card's record in the form view in read-only mode
879 opens the card's record in the form view in editable mode
881 deletes the card's record and removes the card
885 * kanban-specific CSS
886 * kanban structures/widgets (vignette, details, ...)
891 .. js:class:: KanbanRecord
893 :js:class:`Widget` handling the rendering of a single record to a
894 card. Available within its own rendering as ``widget`` in the template
897 .. js:function:: kanban_color(raw_value)
899 Converts a color segmentation value to a kanban color class
900 :samp:`oe_kanban_color_{color_index}`. The built-in CSS provides classes
901 up to a ``color_index`` of 9.
903 .. js:function:: kanban_getcolor(raw_value)
905 Converts a color segmentation value to a color index (between 0 and 9 by
906 default). Color segmentation values can be either numbers or strings.
908 .. js:function:: kanban_image(model, field, id[, cache][, options])
910 Generates the URL to the specified field as an image access.
912 :param String model: model hosting the image
913 :param String field: name of the field holding the image data
914 :param id: identifier of the record contaning the image to display
915 :param Number cache: caching duration (in seconds) of the browser
916 default should be overridden. ``0`` disables
918 :returns: an image URL
920 .. js:function:: kanban_text_ellipsis(string[, size=160])
922 clips text beyond the specified size and appends an ellipsis to it. Can
923 be used to display the initial part of potentially very long fields
924 (e.g. descriptions) without the risk of unwieldy cards
926 .. _reference/views/calendar:
931 Calendar views display records as events in a daily, weekly or monthly
932 calendar. Their root element is ``<calendar>``. Available attributes on the
935 ``date_start`` (required)
936 name of the record's field holding the start date for the event
938 name of the record's field holding the end date for the event, if
939 ``date_end`` is provided records become movable (via drag and drop)
940 directly in the calendar
942 alternative to ``date_end``, provides the duration of the event instead of
945 .. todo:: what's the unit? Does it allow moving the record?
948 name of a record field to use for *color segmentation*. Records in the
949 same color segment are allocated the same highlight color in the calendar,
950 colors are allocated semi-randomly.
952 opens the event in a dialog instead of switching to the form view, enabled
955 enables quick-event creation on click: only asks the user for a ``name``
956 and tries to create a new event with just that and the clicked event
957 time. Falls back to a full form dialog if the quick creation fails
959 format string for event display, field names should be within brackets
962 name of a boolean field on the record indicating whether the corresponding
963 event is flagged as day-long (and duration is irrelevant)
968 what's the purpose of ``<field>`` inside a calendar view?
972 calendar code is an unreadable mess, no idea what these things are:
978 calendar code also seems to refer to multiple additional attributes of
981 .. _reference/views/gantt:
986 Gantt views appropriately display Gantt charts (for scheduling).
988 The root element of gantt views is ``<gantt/>``, it has no children but can
989 take the following attributes:
991 ``date_start`` (required)
992 name of the field providing the start datetime of the event for each
995 name of the field providing the end duration of the event for each
996 record. Can be replaced by ``date_delay``. One (and only one) of
997 ``date_stop`` and ``date_delay`` must be provided.
999 If the field is ``False`` for a record, it's assumed to be a "point event"
1000 and the end date will be set to the start date
1002 name of the field providing the duration of the event
1004 name of a field providing the completion percentage for the record's event,
1006 ``default_group_by``
1007 name of a field to group tasks by
1009 .. previously documented content which don't seem to be used anymore:
1020 .. _reference/views/diagram:
1025 The diagram view can be used to display directed graphs of records. The root
1026 element is ``<diagram>`` and takes no attributes.
1028 Possible children of the diagram view are:
1030 ``node`` (required, 1)
1031 Defines the nodes of the graph. Its attributes are:
1034 the node's Odoo model
1036 conditional shape mapping similar to colors and fonts in :ref:`the list
1037 view <reference/views/list>`. The only valid shape is ``rectangle`` (the
1038 default shape is an ellipsis)
1040 same as ``shape``, but conditionally maps a background color for
1041 nodes. The default background color is white, the only valid alternative
1043 ``arrow`` (required, 1)
1044 Defines the directed edges of the graph. Its attributes are:
1046 ``object`` (required)
1047 the edge's Odoo model
1048 ``source`` (required)
1049 :class:`~openerp.fields.Many2one` field of the edge's model pointing to
1050 the edge's source node record
1051 ``destination`` (required)
1052 :class:`~openerp.fields.Many2one` field of the edge's model pointing to
1053 the edge's destination node record
1055 Python list of attributes (as quoted strings). The corresponding
1056 attributes's values will be concatenated and displayed as the edge's
1060 Explanatory note for the diagram, the ``string`` attribute defines the
1061 note's content. Each ``label`` is output as a paragraph in the diagram
1062 header, easily visible but without any special emphasis.
1064 .. _reference/views/search:
1069 Search views are a break from previous view types in that they don't display
1070 *content*: although they apply to a specific model, they are used to filter
1071 other view's content (generally aggregated views
1072 e.g. :ref:`reference/views/list` or :ref:`reference/views/graph`). Beyond that
1073 difference in use case, they are defined the same way.
1075 The root element of search views is ``<search>``. It takes no attributes.
1077 .. @string is not displayed anywhere, should be removed
1079 Possible children elements of the search view are:
1082 fields define domains or contexts with user-provided values. When search
1083 domains are generated, field domains are composed with one another and
1084 with filters using **AND**.
1086 Fields can have the following attributes:
1089 the name of the field to filter on
1093 by default, fields generate domains of the form :samp:`[({name},
1094 {operator}, {provided_value})]` where ``name`` is the field's name and
1095 ``provided_value`` is the value provided by the user, possibly
1096 filtered or transformed (e.g. a user is expected to provide the
1097 *label* of a selection field's value, not the value itself).
1099 The ``operator`` attribute allows overriding the default operator,
1100 which depends on the field's type (e.g. ``=`` for float fields but
1101 ``ilike`` for char fields)
1103 complete domain to use as the field's search domain, can use a
1104 ``self`` variable to inject the provided value in the custom
1105 domain. Can be used to generate significantly more flexible domains
1106 than ``operator`` alone (e.g. searches on multiple fields at once)
1108 If both ``operator`` and ``filter_domain`` are provided,
1109 ``filter_domain`` takes precedence.
1111 allows adding context keys, including the user-provided value (which
1112 as for ``domain`` is available as a ``self`` variable). By default,
1113 fields don't generate domains.
1115 .. note:: the domain and context are inclusive and both are generated
1116 if if a ``context`` is specified. To only generate context
1117 values, set ``filter_domain`` to an empty list:
1118 ``filter_domain="[]"``
1120 make the field only available to specific users
1122 use specific search widget for the field (the only use case in
1123 standard Odoo 8.0 is a ``selection`` widget for
1124 :class:`~openerp.fields.Many2one` fields)
1126 if the field can provide an auto-completion
1127 (e.g. :class:`~openerp.fields.Many2one`), filters the possible
1131 a filter is a predefined toggle in the search view, it can only be enabled
1132 or disabled. Its main purposes are to add data to the search context (the
1133 context passed to the data view for searching/filtering), or to append new
1134 sections to the search filter.
1136 Filters can have the following attributes:
1138 ``string`` (required)
1139 the label of the filter
1141 an Odoo :ref:`domain <reference/orm/domains>`, will be appended to the
1142 action's domain as part of the search domain
1144 a Python dictionary, merged into the action's domain to generate the
1147 logical name for the filter, can be used to :ref:`enable it by default
1148 <reference/views/search/defaults>`, can also be used as
1149 :ref:`inheritance hook <reference/views/inheritance>`
1151 a longer explanatory text for the filter, may be displayed as a
1154 makes a filter only available to specific users
1156 an icon to display next to the label, if there's sufficient space
1162 .. versionadded:: 7.0
1164 Sequences of filters (without non-filters separating them) are treated
1165 as inclusively composited: they will be composed with ``OR`` rather
1166 than the usual ``AND``, e.g.
1170 <filter domain="[('state', '=', 'draft')]"/>
1171 <filter domain="[('state', '=', 'done')]"/>
1173 if both filters are selected, will select the records whose ``state``
1174 is ``draft`` or ``done``, but
1178 <filter domain="[('state', '=', 'draft')]"/>
1180 <filter domain="[('delay', '<', 15)]"/>
1182 if both filters are selected, will select the records whose ``state``
1183 is ``draft`` **and** ``delay`` is below 15.
1186 can be used to separates groups of filters in simple search views
1188 can be used to separate groups of filters, more readable than
1189 ``separator`` in complex search views
1191 .. _reference/views/search/defaults:
1196 Search fields and filters can be configured through the action's ``context``
1197 using :samp:`search_default_{name}` keys. For fields, the value should be the
1198 value to set in the field, for filters it's a boolean value. For instance,
1199 assuming ``foo`` is a field and ``bar`` is a filter an action context of:
1201 .. code-block:: python
1204 'search_default_foo': 'acro',
1205 'search_default_bar': 1
1208 will automatically enable the ``bar`` filter and search the ``foo`` field for
1211 .. _reference/views/qweb:
1216 QWeb views are standard :ref:`reference/qweb` templates inside a view's
1217 ``arch``. They don't have a specific root element.
1219 A QWeb view can only contain a single template\ [#template_inherit]_, and the
1220 template's name *must* match the view's complete (including module name)
1221 :term:`external id`.
1223 :ref:`reference/data/template` should be used as a shortcut to define QWeb
1226 .. [#backwards-compatibility] for backwards compatibility reasons
1227 .. [#hasclass] an extension function is added for simpler matching in QWeb
1228 views: ``hasclass(*classes)`` matches if the context node has
1229 all the specified classes
1230 .. [#treehistory] for historical reasons, it has its origin in tree-type views
1231 later repurposed to a more table/list-type display
1232 .. [#template_inherit] or no template if it's an inherited view, then :ref:`it
1233 should only contain xpath elements
1234 <reference/views/inheritance>`
1236 .. _accesskey: http://www.w3.org/TR/html5/editing.html#the-accesskey-attribute
1237 .. _CSS color unit: http://www.w3.org/TR/css3-color/#colorunits
1238 .. _floats: https://developer.mozilla.org/en-US/docs/Web/CSS/float
1239 .. _HTML: http://en.wikipedia.org/wiki/HTML
1240 .. _kanban board: http://en.wikipedia.org/wiki/Kanban_board
1241 .. _pivot table: http://en.wikipedia.org/wiki/Pivot_table
1242 .. _XPath: http://en.wikipedia.org/wiki/XPath