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 allows changing the color of a row's text based on the corresponding
139 Defined as a mapping of colors to Python expressions. Values are of the
140 form: :samp:`{color}:{expr}[;...]`. For each record, pairs are tested
141 in-order, the expression is evaluated for the record and if ``true`` the
142 corresponding color is applied to the row. If no color matches, uses the
143 default text color (black).
145 * ``color`` can be any valid `CSS color unit`_.
146 * ``expr`` should be a Python expression evaluated with the current
147 record's attributes as context values. Other context values are ``uid``
148 (the id of the current user) and ``current_date`` (the current date as
149 a string of the form ``yyyy-MM-dd``)
151 allows changing a row's font style based on the corresponding record's
154 The format is the same as for ``color``, but the ``color`` of each pair
155 is replaced by ``bold``, ``italic`` or ``underline``, the expression
156 evaluating to ``true`` will apply the corresponding style to the row's
157 text. Contrary to ``colors``, multiple pairs can match each record
158 ``create``, ``edit``, ``delete``
159 allows *dis*\ abling the corresponding action in the view by setting the
160 corresponding attribute to ``false``
162 only makes sense on an ``editable`` list. Should be the name of a method
163 on the list's model. The method will be called with the ``id`` of a record
164 after having created or edited that record (in database).
166 The method should return a list of ids of other records to load or update.
168 alternative translatable label for the view
172 not displayed anymore
174 .. toolbar attribute is for tree-tree views
176 Possible children elements of the list view are:
178 .. _reference/views/list/button:
181 displays a button in a list cell
184 icon to use to display the button
186 * if there is no ``icon``, the button's text
187 * if there is an ``icon``, ``alt`` text for the icon
189 type of button, indicates how it clicking it affects Odoo:
191 ``workflow`` (default)
192 sends a signal to a workflow. The button's ``name`` is the
193 workflow signal, the row's record is passed as argument to the
196 call a method on the list's model. The button's ``name`` is the
197 method, which is called with the current row's record id and the
200 .. web client also supports a @args, which allows providing
201 additional arguments as JSON. Should that be documented? Does
202 not seem to be used anywhere
205 load an execute an ``ir.actions``, the button's ``name`` is the
206 database id of the action. The context is expanded with the list's
207 model (as ``active_model``), the current row's record
208 (``active_id``) and all the records currently loaded in the list
209 (``active_ids``, may be just a subset of the database records
210 matching the current search)
216 dynamic attributes based on record values.
218 A mapping of attributes to domains, domains are evaluated in the
219 context of the current row's record, if ``True`` the corresponding
220 attribute is set on the cell.
222 Possible attributes are ``invisible`` (hides the button) and
223 ``readonly`` (disables the button but still shows it)
225 shorthand for ``invisible`` ``attrs``: a list of space, separated
226 states, requires that the model has a ``state`` field and that it is
229 Makes the button ``invisible`` if the record is *not* in one of the
232 merged into the view's context when performing the button's Odoo call
234 confirmation message to display (and for the user to accept) before
235 performing the button's Odoo call
237 .. declared but unused: help
240 defines a column where the corresponding field should be displayed for
241 each record. Can use the following attributes:
244 the name of the field to display in the current model. A given name
245 can only be used once per view
247 the title of the field's column (by default, uses the ``string`` of
250 fetches and stores the field, but doesn't display the column in the
251 table. Necessary for fields which shouldn't be displayed but are
252 used by e.g. ``@colors``
254 lists the groups which should be able to see the field
256 alternate representations for a field's display. Possible list view
260 displays ``float`` fields as a progress bar.
262 replaces the m2o field's value by a checkmark if the field is
263 filled, and a cross if it is not
265 for ``sequence`` fields, instead of displaying the field's value
266 just displays a dra&drop icon
268 displays the corresponding aggregate at the bottom of the column. The
269 aggregation is only computed on *currently displayed* records. The
270 aggregation operation must match the corresponding field's
273 dynamic attributes based on record values. Only effects the current
274 field, so e.g. ``invisible`` will hide the field but leave the same
275 field of other records visible, it will not hide the column itself
277 .. note:: if the list view is ``editable``, any field attribute from the
278 :ref:`form view <reference/views/form>` is also valid and will
279 be used when setting up the inline form view
281 .. _reference/views/form:
286 Form views are used to display the data from a single record. Their root
287 element is ``<form>``. They are composed of regular HTML_ with additional
288 structural and semantic components.
290 Structural components
291 ---------------------
293 Structural components provide structure or "visual" features with little
294 logic. They are used as elements or sets of elements in form views.
297 defines a tabbed section. Each tab is defined through a ``page`` child
298 element. Pages can have the following attributes:
300 ``string`` (required)
305 standard dynamic attributes based on record values
308 used to define column layouts in forms. By default, groups define 2 columns
309 and most direct children of groups take a single column. ``field`` direct
310 children of groups display a label by default, and the label and the field
311 itself have a colspan of 1 each.
313 The number of columns in a ``group`` can be customized using the ``col``
314 attribute, the number of columns taken by an element can be customized using
317 Children are laid out horizontally (tries to fill the next column before
320 Groups can have a ``string`` attribute, which is displayed as the group's
323 only useful within ``group`` elements, ends the current row early and
324 immediately switches to a new row (without filling any remaining column
327 small horizontal spacing, with a ``string`` attribute behaves as a section
330 can be used as a direct child to ``form`` for a narrower and more responsive
333 combined with ``sheet``, provides a full-width location above the sheet
334 itself, generally used to display workflow buttons and status widgets
339 Semantic components tie into and allow interaction with the Odoo
340 system. Available semantic components are:
343 call into the Odoo system, similar to :ref:`list view buttons
344 <reference/views/list/button>`
346 renders (and allow edition of, possibly) a single field of the current
347 record. Possible attributes are:
350 the name of the field to render
352 fields have a default rendering based on their type
353 (e.g. :class:`~openerp.fields.Char`,
354 :class:`~openerp.fields.Many2one`). The ``widget`` attributes allows using
355 a different rendering method and context.
357 .. todo:: list of widgets
359 & options & specific attributes (e.g. widget=statusbar
360 statusbar_visible statusbar_colors clickable)
362 JSON object specifying configuration option for the field's widget
363 (including default widgets)
365 HTML class to set on the generated element, common field classes are:
368 prevent the usual line break following fields
369 ``oe_left``, ``oe_right``
370 floats_ the field to the corresponding direction
371 ``oe_read_only``, ``oe_edit_only``
372 only displays the field in the corresponding form mode
374 avoids displaying the navigation button in a
375 :class:`~openerp.fields.Many2one`
377 for image fields, displays images as "avatar" (square, 90x90 maximum
378 size, some image decorations)
380 only displays the field for specific users
382 calls the specified method when this field's value is edited, can generate
383 update other fields or display warnings for the user
387 Use :func:`openerp.api.onchange` on the model
390 dynamic meta-parameters based on record values
392 for relational fields only, filters to apply when displaying existing
393 records for selection
395 for relational fields only, context to pass when fetching possible values
397 display the field in both readonly and edition mode, but never make it
400 generates an error and prevents saving the record if the field doesn't
403 don't automatically display the field's label, only makes sense if the
404 field is a direct child of a ``group`` element
406 help message to display in *empty* fields. Can replace field labels in
407 complex forms. *Should not* be an example of data as users are liable to
408 confuse placeholder text with filled fields
410 for :class:`~openerp.fields.One2many`, display mode (view type) to use for
411 the field's linked records. One of ``tree``, ``form``, ``kanban`` or
412 ``graph``. The default is ``tree`` (a list display)
414 tooltip displayed for users when hovering the field or its label
416 for binary fields, name of the related field providing the name of the
419 indicates that a :class:`~openerp.fields.Char` field stores a password and
420 that its data shouldn't be displayed
422 .. todo:: classes for forms
426 Business Views guidelines
427 -------------------------
429 .. sectionauthor:: Aline Preillon, Raphael Collet
431 Business views are targeted at regular users, not advanced users. Examples
432 are: Opportunities, Products, Partners, Tasks, Projects, etc.
434 .. image:: forms/oppreadonly.png
435 :class: img-responsive
437 In general, a business view is composed of
439 1. a status bar on top (with technical or business flow),
440 2. a sheet in the middle (the form itself),
441 3. a bottom part with History and Comments.
443 Technically, the new form views are structured as follows in XML::
446 <header> ... content of the status bar ... </header>
447 <sheet> ... content of the sheet ... </sheet>
448 <div class="oe_chatter"> ... content of the bottom part ... </div>
454 The purpose of the status bar is to show the status of the current record and
457 .. image:: forms/status.png
458 :class: img-responsive
463 The order of buttons follows the business flow. For instance, in a sale order,
464 the logical steps are:
466 1. Send the quotation
467 2. Confirm the quotation
468 3. Create the final invoice
471 Highlighted buttons (in red by default) emphasize the logical next step, to
472 help the user. It is usually the first active button. On the other hand,
473 :guilabel:`cancel` buttons *must* remain grey (normal). For instance, in
474 Invoice the button :guilabel:`Refund` must never be red.
476 Technically, buttons are highlighted by adding the class "oe_highlight"::
478 <button class="oe_highlight" name="..." type="..." states="..."/>
483 Uses the ``statusbar`` widget, and shows the current state in red. States
484 common to all flows (for instance, a sale order begins as a quotation, then we
485 send it, then it becomes a full sale order, and finally it is done) should be
486 visible at all times but exceptions or states depending on particular sub-flow
487 should only be visible when current.
489 .. image:: forms/status1.png
490 :class: img-responsive
492 .. image:: forms/status2.png
493 :class: img-responsive
495 The states are shown following the order used in the field (the list in a
496 selection field, etc). States that are always visible are specified with the
497 attribute ``statusbar_visible``.
499 ``statusbar_colors`` can be used to give a custom color to specific states.
503 <field name="state" widget="statusbar"
504 statusbar_visible="draft,sent,progress,invoiced,done"
505 statusbar_colors="{'shipping_except':'red','waiting_date':'blue'}"/>
510 All business views should look like a printed sheet:
512 .. image:: forms/sheet.png
513 :class: img-responsive
515 1. Elements inside a ``<form>`` or ``<page>`` do not define groups, elements
516 inside them are laid out according to normal HTML rules. They content can
517 be explicitly grouped using ``<group>`` or regular ``<div>`` elements.
518 2. By default, the element ``<group>`` defines two columns inside, unless an
519 attribute ``col="n"`` is used. The columns have the same width (1/n th of
520 the group's width). Use a ``<group>`` element to produce a column of fields.
521 3. To give a title to a section, add a ``string`` attribute to a ``<group>`` element::
523 <group string="Time-sensitive operations">
525 this replaces the former use of ``<separator string="XXX"/>``.
526 4. The ``<field>`` element does not produce a label, except as direct children
527 of a ``<group>`` element\ [#backwards-compatibility]_. Use :samp:`<label
528 for="{field_name}>` to produce a label of a field.
533 Some sheets have headers with one or more fields, and the labels of those
534 fields are only shown in edit mode.
541 * - .. image:: forms/header.png
542 :class: img-responsive
543 - .. image:: forms/header2.png
544 :class: img-responsive
546 Use HTML text, ``<div>``, ``<h1>``, ``<h2>``… to produce nice headers, and
547 ``<label>`` with the class ``oe_edit_only`` to only display the field's label
548 in edit mode. The class ``oe_inline`` will make fields inline (instead of
549 blocks): content following the field will be displayed on the same line rather
550 than on the line below it. The form above is produced by the following XML::
552 <label for="name" class="oe_edit_only"/>
553 <h1><field name="name"/></h1>
555 <label for="planned_revenue" class="oe_edit_only"/>
557 <field name="planned_revenue" class="oe_inline"/>
558 <field name="company_currency" class="oe_inline oe_edit_only"/> at
559 <field name="probability" class="oe_inline"/> % success rate
565 Many relevant actions or links can be displayed in the form. For example, in
566 Opportunity form, the actions "Schedule a Call" and "Schedule a Meeting" take
567 an important place in the use of the CRM. Instead of placing them in the
568 "More" menu, put them directly in the sheet as buttons (on the top right) to
569 make them more visible and more easily accessible.
571 .. image:: forms/header3.png
572 :class: img-responsive
574 Technically, the buttons are placed inside a <div> to group them as a block on
575 the right-hand side of the sheet.
579 <div class="oe_button_box oe_right">
580 <button string="Schedule/Log Call" name="..." type="action"/>
581 <button string="Schedule Meeting" name="action_makeMeeting" type="object"/>
587 A column of fields is now produced with a ``<group>`` element, with an
590 .. image:: forms/screenshot-03.png
591 :class: img-responsive
595 <group string="Payment Options">
596 <field name="writeoff_amount"/>
597 <field name="payment_option"/>
600 It is recommended to have two columns of fields on the form. For this, simply
601 put the ``<group>`` elements that contain the fields inside a top-level
604 To make :ref:`view extension <reference/views/inheritance>` simpler, it is
605 recommended to put a ``name`` attribute on ``<group>`` elements, so new fields
606 can easily be added at the right place.
608 Special Case: Subtotals
609 ~~~~~~~~~~~~~~~~~~~~~~~
611 Some classes are defined to render subtotals like in invoice forms:
613 .. image:: forms/screenshot-00.png
614 :class: img-responsive
618 <group class="oe_subtotal_footer">
619 <field name="amount_untaxed"/>
620 <field name="amount_tax"/>
621 <field name="amount_total" class="oe_subtotal_footer_separator"/>
622 <field name="residual" style="margin-top: 10px"/>
625 Placeholders and Inline Fields
626 ..............................
628 Sometimes field labels make the form too complex. One can omit field labels,
629 and instead put a placeholder inside the field. The placeholder text is
630 visible only when the field is empty. The placeholder should tell what to
631 place inside the field, it *must not* be an example as they are often confused
634 One can also group fields together by rendering them "inline" inside an
635 explicit block element like `<div>``. This allows grouping semantically
636 related fields as if they were a single (composite) fields.
638 The following example, taken from the *Leads* form, shows both placeholders and
639 inline fields (zip and city).
646 * - .. image:: forms/placeholder.png
647 :class: img-responsive
648 - .. image:: forms/screenshot-01.png
649 :class: img-responsive
654 <label for="street" string="Address"/>
656 <field name="street" placeholder="Street..."/>
657 <field name="street2"/>
659 <field name="zip" class="oe_inline" placeholder="ZIP"/>
660 <field name="city" class="oe_inline" placeholder="City"/>
662 <field name="state_id" placeholder="State"/>
663 <field name="country_id" placeholder="Country"/>
670 Images, like avatars, should be displayed on the right of the sheet. The
671 product form looks like:
673 .. image:: forms/screenshot-02.png
674 :class: img-responsive
676 The form above contains a <sheet> element that starts with:
680 <field name="product_image" widget="image" class="oe_avatar oe_right"/>
685 Most :class:`~openerp.fields.Many2many` fields, like categories, are better
686 rendered as a list of tags. Use the widget ``many2many_tags`` for this:
688 .. image:: forms/screenshot-04.png
689 :class: img-responsive
693 <field name="category_id" widget="many2many_tags"/>
695 Configuration forms guidelines
696 ------------------------------
698 Examples of configuration forms: Stages, Leave Type, etc. This concerns all
699 menu items under Configuration of each application (like Sales/Configuration).
701 .. image:: forms/nosheet.png
702 :class: img-responsive
704 1. no header (because no state, no workflow, no button)
707 Dialog forms guidelines
708 -----------------------
710 Example: "Schedule a Call" from an opportunity.
712 .. image:: forms/wizard-popup.png
713 :class: img-responsive
715 1. avoid separators (the title is already in the popup title bar, so another
716 separator is not relevant)
717 2. avoid cancel buttons (user generally close the popup window to get the same
719 3. action buttons must be highlighted (red)
720 4. when there is a text area, use a placeholder instead of a label or a
722 5. like in regular form views, put buttons in the <header> element
724 Configuration Wizards guidelines
725 --------------------------------
727 Example: Settings / Configuration / Sales.
729 1. always in line (no popup)
731 3. keep the cancel button (users cannot close the window)
732 4. the button "Apply" must be red
735 .. _reference/views/graph:
740 The graph view is used to visualize aggregations over a number of records or
741 record groups. Its root element is ``<graph>`` which can take the following
745 one of ``bar`` (default), ``pie``, ``line`` and ``pivot``, the type of graph
746 to use (``pivot`` technically isn't a graph type, it displays the
747 aggregation as a `pivot table`_)
749 only used for ``bar`` charts. If present and set to ``True``, stacks bars
752 The only allowed element within a graph view is ``field`` which can have the
753 following attributes:
756 the name of a field to use in a graph view. If used for grouping (rather
760 indicates whether the field should be used as a grouping criteria or as an
761 aggregated value within a group. Possible values are:
764 groups by the specified field. All graph types support at least one level
765 of grouping, some may support more. For pivot tables, each group gets its
768 only used by pivot tables, creates column-wise groups
770 field to aggregate within a group
773 on date and datetime fields, groups by the specified interval (``day``,
774 ``week``, ``month``, ``quarter`` or ``year``) instead of grouping on the
775 specific datetime (fixed second resolution) or date (fixed day resolution).
779 graph view aggregations are performed on database content, non-stored
780 function fields can not be used in graph views
782 .. _reference/views/kanban:
787 The kanban view is a `kanban board`_ visualisation: it displays records as
788 "cards", halfway between a :ref:`list view <reference/views/list>` and a
789 non-editable :ref:`form view <reference/views/form>`. Records may be grouped
790 in columns for use in workflow visualisation or manipulation (e.g. tasks or
791 work-progress management), or ungrouped (used simply to visualize records).
793 The root element of the Kanban view is ``<kanban>``, it can use the following
797 whether the kanban view should be grouped if no grouping is specified via
798 the action or the current research. Should be the name of the field to group
799 by when no grouping is otherwise specified
801 cards sorting order used if the user has not already sorted the records (via
804 adds HTML classes to the root HTML element of the Kanban view
806 whether it should be possible to create records without switching to the
807 form view. By default, ``quick_create`` is enabled when the Kanban view is
808 grouped, and disabled when not.
810 Set to ``true`` to always enable it, and to ``false`` to always disable it.
812 Possible children of the view element are:
815 declares fields to aggregate or to use in kanban *logic*. If the field is
816 simply displayed in the kanban view, it does not need to be pre-declared.
818 Possible attributes are:
821 the name of the field to fetch
822 ``sum``, ``avg``, ``min``, ``max``, ``count``
823 displays the corresponding aggregation at the top of a kanban column, the
824 field's value is the label of the aggregation (a string). Only one
825 aggregate operation per field is supported.
828 defines a list of :ref:`reference/qweb` templates. Cards definition may be
829 split into multiple templates for clarity, but kanban views *must* define at
830 least one root template ``kanban-box``, which will be rendered once for each
833 The kanban view uses mostly-standard :ref:`javascript qweb
834 <reference/qweb/javascript>` and provides the following context variables:
837 the current :ref:`reference/javascript/client` instance
839 the current :js:class:`KanbanRecord`, can be used to fetch some
840 meta-information. These methods are also available directly in the
841 template context and don't need to be accessed via ``widget``
843 an object with all the requested fields as its attributes. Each field has
844 two attributes ``value`` and ``raw_value``, the former is formatted
845 according to current user parameters, the latter is the direct value from
846 a :meth:`~openerp.models.Model.read`
851 .. rubric:: buttons and fields
853 While most of the Kanban templates are standard :ref:`reference/qweb`, the
854 Kanban view processes ``field``, ``button`` and ``a`` elements specially:
856 * by default fields are replaced by their formatted value, unless they
857 match specific kanban view widgets
859 .. todo:: list widgets?
861 * buttons and links with a ``type`` attribute become perform Odoo-related
862 operations rather than their standard HTML function. Possible types are:
864 ``action``, ``object``
865 standard behavior for :ref:`Odoo buttons
866 <reference/views/list/button>`, most attributes relevant to standard
867 Odoo buttons can be used.
869 opens the card's record in the form view in read-only mode
871 opens the card's record in the form view in editable mode
873 deletes the card's record and removes the card
877 * kanban-specific CSS
878 * kanban structures/widgets (vignette, details, ...)
883 .. js:class:: KanbanRecord
885 :js:class:`Widget` handling the rendering of a single record to a
886 card. Available within its own rendering as ``widget`` in the template
889 .. js:function:: kanban_color(raw_value)
891 Converts a color segmentation value to a kanban color class
892 :samp:`oe_kanban_color_{color_index}`. The built-in CSS provides classes
893 up to a ``color_index`` of 9.
895 .. js:function:: kanban_getcolor(raw_value)
897 Converts a color segmentation value to a color index (between 0 and 9 by
898 default). Color segmentation values can be either numbers or strings.
900 .. js:function:: kanban_image(model, field, id[, cache][, options])
902 Generates the URL to the specified field as an image access.
904 :param String model: model hosting the image
905 :param String field: name of the field holding the image data
906 :param id: identifier of the record contaning the image to display
907 :param Number cache: caching duration (in seconds) of the browser
908 default should be overridden. ``0`` disables
910 :returns: an image URL
912 .. js:function:: kanban_text_ellipsis(string[, size=160])
914 clips text beyond the specified size and appends an ellipsis to it. Can
915 be used to display the initial part of potentially very long fields
916 (e.g. descriptions) without the risk of unwieldy cards
918 .. _reference/views/calendar:
923 Calendar views display records as events in a daily, weekly or monthly
924 calendar. Their root element is ``<calendar>``. Available attributes on the
927 ``date_start`` (required)
928 name of the record's field holding the start date for the event
930 name of the record's field holding the end date for the event, if
931 ``date_end`` is provided records become movable (via drag and drop)
932 directly in the calendar
934 alternative to ``date_end``, provides the duration of the event instead of
937 .. todo:: what's the unit? Does it allow moving the record?
940 name of a record field to use for *color segmentation*. Records in the
941 same color segment are allocated the same highlight color in the calendar,
942 colors are allocated semi-randomly.
944 opens the event in a dialog instead of switching to the form view, enabled
947 enables quick-event creation on click: only asks the user for a ``name``
948 and tries to create a new event with just that and the clicked event
949 time. Falls back to a full form dialog if the quick creation fails
951 format string for event display, field names should be within brackets
954 name of a boolean field on the record indicating whether the corresponding
955 event is flagged as day-long (and duration is irrelevant)
960 what's the purpose of ``<field>`` inside a calendar view?
964 calendar code is an unreadable mess, no idea what these things are:
970 calendar code also seems to refer to multiple additional attributes of
973 .. _reference/views/gantt:
978 Gantt views appropriately display Gantt charts (for scheduling).
980 The root element of gantt views is ``<gantt/>``, it has no children but can
981 take the following attributes:
983 ``date_start`` (required)
984 name of the field providing the start datetime of the event for each
987 name of the field providing the end duration of the event for each
988 record. Can be replaced by ``date_delay``. One (and only one) of
989 ``date_stop`` and ``date_delay`` must be provided.
991 If the field is ``False`` for a record, it's assumed to be a "point event"
992 and the end date will be set to the start date
994 name of the field providing the duration of the event
996 name of a field providing the completion percentage for the record's event,
999 name of a field to group tasks by
1001 .. previously documented content which don't seem to be used anymore:
1012 .. _reference/views/diagram:
1017 The diagram view can be used to display directed graphs of records. The root
1018 element is ``<diagram>`` and takes no attributes.
1020 Possible children of the diagram view are:
1022 ``node`` (required, 1)
1023 Defines the nodes of the graph. Its attributes are:
1026 the node's Odoo model
1028 conditional shape mapping similar to colors and fonts in :ref:`the list
1029 view <reference/views/list>`. The only valid shape is ``rectangle`` (the
1030 default shape is an ellipsis)
1032 same as ``shape``, but conditionally maps a background color for
1033 nodes. The default background color is white, the only valid alternative
1035 ``arrow`` (required, 1)
1036 Defines the directed edges of the graph. Its attributes are:
1038 ``object`` (required)
1039 the edge's Odoo model
1040 ``source`` (required)
1041 :class:`~openerp.fields.Many2one` field of the edge's model pointing to
1042 the edge's source node record
1043 ``destination`` (required)
1044 :class:`~openerp.fields.Many2one` field of the edge's model pointing to
1045 the edge's destination node record
1047 Python list of attributes (as quoted strings). The corresponding
1048 attributes's values will be concatenated and displayed as the edge's
1052 Explanatory note for the diagram, the ``string`` attribute defines the
1053 note's content. Each ``label`` is output as a paragraph in the diagram
1054 header, easily visible but without any special emphasis.
1056 .. _reference/views/search:
1061 Search views are a break from previous view types in that they don't display
1062 *content*: although they apply to a specific model, they are used to filter
1063 other view's content (generally aggregated views
1064 e.g. :ref:`reference/views/list` or :ref:`reference/views/graph`). Beyond that
1065 difference in use case, they are defined the same way.
1067 The root element of search views is ``<search>``. It takes no attributes.
1069 .. @string is not displayed anywhere, should be removed
1071 Possible children elements of the search view are:
1074 fields define domains or contexts with user-provided values. When search
1075 domains are generated, field domains are composed with one another and
1076 with filters using **AND**.
1078 Fields can have the following attributes:
1081 the name of the field to filter on
1085 by default, fields generate domains of the form :samp:`[({name},
1086 {operator}, {provided_value})]` where ``name`` is the field's name and
1087 ``provided_value`` is the value provided by the user, possibly
1088 filtered or transformed (e.g. a user is expected to provide the
1089 *label* of a selection field's value, not the value itself).
1091 The ``operator`` attribute allows overriding the default operator,
1092 which depends on the field's type (e.g. ``=`` for float fields but
1093 ``ilike`` for char fields)
1095 complete domain to use as the field's search domain, can use a
1096 ``self`` variable to inject the provided value in the custom
1097 domain. Can be used to generate significantly more flexible domains
1098 than ``operator`` alone (e.g. searches on multiple fields at once)
1100 If both ``operator`` and ``filter_domain`` are provided,
1101 ``filter_domain`` takes precedence.
1103 allows adding context keys, including the user-provided value (which
1104 as for ``domain`` is available as a ``self`` variable). By default,
1105 fields don't generate domains.
1107 .. note:: the domain and context are inclusive and both are generated
1108 if if a ``context`` is specified. To only generate context
1109 values, set ``filter_domain`` to an empty list:
1110 ``filter_domain="[]"``
1112 make the field only available to specific users
1114 use specific search widget for the field (the only use case in
1115 standard Odoo 8.0 is a ``selection`` widget for
1116 :class:`~openerp.fields.Many2one` fields)
1118 if the field can provide an auto-completion
1119 (e.g. :class:`~openerp.fields.Many2one`), filters the possible
1123 a filter is a predefined toggle in the search view, it can only be enabled
1124 or disabled. Its main purposes are to add data to the search context (the
1125 context passed to the data view for searching/filtering), or to append new
1126 sections to the search filter.
1128 Filters can have the following attributes:
1130 ``string`` (required)
1131 the label of the filter
1133 an Odoo :ref:`domain <reference/orm/domains>`, will be appended to the
1134 action's domain as part of the search domain
1136 a Python dictionary, merged into the action's domain to generate the
1139 logical name for the filter, can be used to :ref:`enable it by default
1140 <reference/views/search/defaults>`, can also be used as
1141 :ref:`inheritance hook <reference/views/inheritance>`
1143 a longer explanatory text for the filter, may be displayed as a
1146 makes a filter only available to specific users
1148 an icon to display next to the label, if there's sufficient space
1154 .. versionadded:: 7.0
1156 Sequences of filters (without non-filters separating them) are treated
1157 as inclusively composited: they will be composed with ``OR`` rather
1158 than the usual ``AND``, e.g.
1162 <filter domain="[('state', '=', 'draft')]"/>
1163 <filter domain="[('state', '=', 'done')]"/>
1165 if both filters are selected, will select the records whose ``state``
1166 is ``draft`` or ``done``, but
1170 <filter domain="[('state', '=', 'draft')]"/>
1172 <filter domain="[('delay', '<', 15)]"/>
1174 if both filters are selected, will select the records whose ``state``
1175 is ``draft`` **and** ``delay`` is below 15.
1178 can be used to separates groups of filters in simple search views
1180 can be used to separate groups of filters, more readable than
1181 ``separator`` in complex search views
1183 .. _reference/views/search/defaults:
1188 Search fields and filters can be configured through the action's ``context``
1189 using :samp:`search_default_{name}` keys. For fields, the value should be the
1190 value to set in the field, for filters it's a boolean value. For instance,
1191 assuming ``foo`` is a field and ``bar`` is a filter an action context of:
1193 .. code-block:: python
1196 'search_default_foo': 'acro',
1197 'search_default_bar': 1
1200 will automatically enable the ``bar`` filter and search the ``foo`` field for
1203 .. _reference/views/qweb:
1208 QWeb views are standard :ref:`reference/qweb` templates inside a view's
1209 ``arch``. They don't have a specific root element.
1211 A QWeb view can only contain a single template\ [#template_inherit]_, and the
1212 template's name *must* match the view's complete (including module name)
1213 :term:`external id`.
1215 :ref:`reference/data/template` should be used as a shortcut to define QWeb
1218 .. [#backwards-compatibility] for backwards compatibility reasons
1219 .. [#hasclass] an extension function is added for simpler matching in QWeb
1220 views: ``hasclass(*classes)`` matches if the context node has
1221 all the specified classes
1222 .. [#treehistory] for historical reasons, it has its origin in tree-type views
1223 later repurposed to a more table/list-type display
1224 .. [#template_inherit] or no template if it's an inherited view, then :ref:`it
1225 should only contain xpath elements
1226 <reference/views/inheritance>`
1228 .. _accesskey: http://www.w3.org/TR/html5/editing.html#the-accesskey-attribute
1229 .. _CSS color unit: http://www.w3.org/TR/css3-color/#colorunits
1230 .. _floats: https://developer.mozilla.org/en-US/docs/Web/CSS/float
1231 .. _HTML: http://en.wikipedia.org/wiki/HTML
1232 .. _kanban board: http://en.wikipedia.org/wiki/Kanban_board
1233 .. _pivot table: http://en.wikipedia.org/wiki/Pivot_table
1234 .. _XPath: http://en.wikipedia.org/wiki/XPath