9 As all data of the program is stored in objects, as explained in the Objects
10 section, how are these objects exposed to the user ? We will try to answer this
11 question in this section.
13 First of all, let's note that every resource type uses its own interface. For
14 example, the screen to modify a partner's data is not the same as the one to
17 Then, you have to know that the OpenERP user interface is dynamic, it means
18 that it is not described "statically" by some code, but dynamically built from
19 XML descriptions of the client screens.
21 From now on, we will call these screen descriptions views.
23 A notable characteristic of these views is that they can be edited at any
24 moment (even during the program execution). After a modification to a displayed
25 view has occurred, you simply need to close the tab corresponding to that
26 'view' and re-open it for the changes to appear.
31 Views describe how each object (type of resource) is displayed. More precisely, for each object, we can define one (or several) view(s) to describe which fields should be drawn and how.
33 There are two types of views:
38 .. note:: Since OpenERP 4.1, form views can also contain graphs.
43 The field disposition in a form view always follows the same principle. Fields are distributed on the screen following the rules below:
45 * By default, each field is preceded by a label, with its name.
46 * Fields are placed on the screen from left to right, and from top to bottom, according to the order in which they are declared in the view.
47 * Every screen is divided into 4 columns, each column being able to contain either a label, or an "edition" field. As every edition field is preceded (by default) by a label with its name, there will be two fields (and their respective labels) on each line of the screen. The green and red zones on the screen-shot below, illustrate those 4 columns. They designate respectively the labels and their corresponding fields.
49 .. .. figure:: images/sale_order.png
54 Views also support more advanced placement options:
56 * A view field can use several columns. For example, on the screen-shot below, the zone in the blue frame is, in fact, the only field of a "one to many". We will come back later on this note, but let's note that it uses the whole width of the screen and not only one column.
58 .. .. figure:: images/sale_order_sale_order_lines.png
62 * We can also make the opposite operation: take a columns group and divide it in as many columns as desired. The surrounded green zones of the screen above are good examples. Precisely, the green framework up and on the right side takes the place of two columns, but contains 4 columns.
64 As we can see below in the purple zone of the screen, there is also a way to distribute the fields of an object on different tabs.
66 .. .. figure:: images/sale_order_notebook.png
73 The on_change attribute defines a method that is called when the
74 content of a view field has changed.
76 This method takes at least arguments: cr, uid, ids, which are the
77 three classical arguments and also the context dictionary. You can add
78 parameters to the method. They must correspond to other fields defined
79 in the view, and must also be defined in the XML with fields defined
82 <field name="name_of_field" on_change="name_of_method(other_field'_1_', ..., other_field'_n_')"/>
84 The example below is from the sale order view.
86 You can use the 'context' keyword to access data in the context that
87 can be used as params of the function.::
89 <field name="shop_id" on_change="onchange_shop_id(shop_id)"/>
91 .. code-block:: python
93 def onchange_shop_id(self, cr, uid, ids, shop_id):
98 shop=self.pool.get('sale.shop').browse(cr,uid,shop_id)
99 v['project_id']=shop.project_id.id
100 if shop.pricelist_id.id:
102 v['pricelist_id']=shop.pricelist_id.id
104 v['payment_default_id']=shop.payment_default_id.id
109 When editing the shop_id form field, the onchange_shop_id method of
110 the sale_order object is called and returns a dictionary where the
111 'value' key contains a dictionary of the new value to use in the
112 'project_id', 'pricelist_id' and 'payment_default_id' fields.
114 Note that it is possible to change more than just the values of
115 fields. For example, it is possible to change the value of some fields
116 and the domain of other fields by returning a value of the form:
117 return {'domain': d, 'value': value}
119 :returns: a dictionary with any mix of the following keys:
122 A mapping of ``{field: domain}``.
124 The returned domains should be set on the fields instead of the
128 A mapping of ``{field: value}}``, the values will be set on the
129 corresponding fields and may trigger new onchanges or attrs
132 ``warning`` A dict with the keys ``title`` and ``message``. Both
133 are mandatory. Indicate that an error message should be
134 displayed to the user.
140 These views are used when we work in list mode (in order to visualize several resources at once) and in the search screen. These views are simpler than the form views and thus have less options.
142 .. .. figure:: images/tree_view.png
149 Search views are a new feature of OpenERP supported as of version 6.0
150 It creates a customized search panel, and is declared quite similarly to a form view,
151 except that the view type and root element change to ``search`` instead of ``form``.
153 .. .. image:: images/search.png
157 Following is the list of new elements and features supported in search views.
162 Unlike form group elements, search view groups support unlimited number of widget(fields or filters)
163 in a row (no automatic line wrapping), and only use the following attributes:
165 + ``expand``: turns on the expander icon on the group (1 for expanded by default, 0 for collapsed)
166 + ``string``: label for the group
170 <group expand="1" string="Group By">
171 <filter string="Users" icon="terp-project" domain="[]" context="{'group_by':'user_id'}"/>
172 <filter string="Project" icon="terp-project" domain="[]" context="{'group_by':'project_id'}"/>
173 <separator orientation="vertical"/>
174 <filter string="Deadline" icon="terp-project" domain="[]" context="{'group_by':'date_deadline'}"/>
177 In the screenshot above the green area is an expandable group.
181 Filters are displayed as a toggle button on search panel
182 Filter elements can add new values in the current domain or context of the search view.
183 Filters can be added as a child element of field too, to indicate that they apply specifically
184 to that field (in this case the button's icon will smaller)
186 In the picture above the red area contains filters at the top of the form while
187 the blue area highlights a field and it's child filter.
191 <filter string="Current" domain="[('state','in',('open','draft'))]" help="Draft, Open and Pending Tasks" icon="terp-project"/>
192 <field name="project_id" select="1" widget="selection">
193 <filter domain="[('project_id.user_id','=',uid)]" help="My Projects" icon="terp-project"/>
201 <filter string="Project" icon="terp-project" domain="[]" context="{'group_by':'project_id'}"/>
203 Above filters groups records sharing the same ``project_id`` value. Groups are loaded
204 lazily, so the inner records are only loaded when the group is expanded.
205 The group header lines contain the common values for all records in that group, and all numeric
206 fields currently displayed in the view are replaced by the sum of the values in that group.
208 It is also possible to group on multiple values by specifying a list of fields instead of a single string.
209 In this case nested groups will be displayed::
211 <filter string="Project" icon="terp-project" domain="[]" context="{'group_by': ['project_id', 'user_id'] }"/>
216 Field elements in search views are used to get user-provided values
217 for searches. As a result, as for group elements, they are quite
218 different than form view's fields:
220 * a search field can contain filters, which generally indicate that
221 both field and filter manage the same field and are related.
223 Those inner filters are rendered as smaller buttons, right next to
224 the field, and *must not* have a ``string`` attribute.
226 * a search field really builds a domain composed of ``[(field_name,
227 operator, field_value)]``. This domain can be overridden in two
230 * ``@operator`` replaces the default operator for the field (which
233 * ``@filter_domain`` lets you provide a fully custom domain, which
234 will replace the default domain creation
236 * a search field does not create a context by default, but you can
237 provide an ``@context`` which will be evaluated and merged into the
238 wider context (as with a ``filter`` element).
240 To get the value of the field in your ``@context`` or
241 ``@filter_domain``, you can use the variable ``self``:
245 <field name="location_id" string="Location"
246 filter_domain="['|',('location_id','ilike',self),('location_dest_id','ilike',self)]"/>
252 <field name="journal_id" widget="selection"
253 context="{'journal_id':self, 'visible_id':self, 'normal_view':False}"/>
255 Range fields (date, datetime, time)
256 """""""""""""""""""""""""""""""""""
258 The range fields are composed of two input widgets (from and two)
261 This leads to peculiarities (compared to non-range search fields):
263 * It is not possible to override the operator of a range field via
264 ``@operator``, as the domain is built of two sections and each
265 section uses a different operator.
267 * Instead of being a simple value (integer, string, float) ``self``
268 for use in ``@filter_domain`` and ``@context`` is a ``dict``.
270 Because each input widget of a range field can be empty (and the
271 field itself will still be valid), care must be taken when using
272 ``self``: it has two string keys ``"from"`` and ``"to"``, but any of
273 these keys can be either missing entirely or set to the value
276 Actions for Search view
277 +++++++++++++++++++++++
279 After declaring a search view, it will be used automatically for all tree views on the same model.
280 If several search views exist for a single model, the one with the highest priority (lowest sequence) will
281 be used. Another option is to explicitly select the search view you want to use, by setting the
282 ``search_view_id`` field of the action.
284 In addition to being able to pass default form values in the context of the action, OpenERP 6.0 now
285 supports passing initial values for search views too, via the context. The context keys need to match the
286 ``search_default_XXX`` format. ``XXX`` may refer to the ``name`` of a ``<field>`` or ``<filter>``
287 in the search view (as the ``name`` attribute is not required on filters, this only works for filters that have
288 an explicit ``name`` set). The value should be either the initial value for search fields, or
289 simply a boolean value for filters, to toggle them
293 <record id="action_view_task" model="ir.actions.act_window">
294 <field name="name">Tasks</field>
295 <field name="res_model">project.task</field>
296 <field name="view_type">form</field>
297 <field name="view_mode">tree,form,calendar,gantt,graph</field>
298 <field eval="False" name="filter"/>
299 <field name="view_id" ref="view_task_tree2"/>
300 <field name="context">{"search_default_current":1,"search_default_user_id":uid}</field>
301 <field name="search_view_id" ref="view_task_search_form"/>
307 As of v6.0, all search views also features custom search filters, as show below.
308 Users can define their own custom filters using any of the fields available on the current model,
309 combining them with AND/OR operators. It is also possible to save any search context (the combination
310 of all currently applied domain and context values) as a personal filter, which can be recalled
311 at any time. Filters can also be turned into Shortcuts directly available in the User's homepage.
313 .. .. image:: images/filter.png
318 In above screenshot we filter Partner where Salesman = Demo user and Country = Belgium,
319 We can save this search criteria as a Shortcut or save as Filter.
321 Filters are user specific and can be modified via the Manage Filters option in the filters drop-down.
327 A graph is a new mode of view for all views of type form. If, for example, a sale order line must be visible as list or as graph, define it like this in the action that open this sale order line. Do not set the view mode as "tree,form,graph" or "form,graph" - it must be "graph,tree" to show the graph first or "tree,graph" to show the list first. (This view mode is extra to your "form,tree" view and should have a separate menu item):
331 <field name="view_type">form</field>
332 <field name="view_mode">tree,graph</field>
336 tree = (tree with shortcuts at the left), form = (switchable view form/list)
340 tree,graph : sequences of the views when switching
342 Then, the user will be able to switch from one view to the other. Unlike forms and trees, OpenERP is not able to automatically create a view on demand for the graph type. So, you must define a view for this graph:
347 <record model="ir.ui.view" id="view_order_line_graph">
348 <field name="name">sale.order.line.graph</field>
349 <field name="model">sale.order.line</field>
350 <field name="type">graph</field>
351 <field name="arch" type="xml">
352 <graph string="Sales Order Lines">
353 <field name="product_id" group="True"/>
354 <field name="price_unit" operator="*"/>
362 A view of type graph is just a list of fields for the graph.
367 The default type of the graph is a pie chart - to change it to a barchart change **<graph string="Sales Order Lines">** to **<graph string="Sales Order Lines" type="bar">** You also may change the orientation.
373 <graph string="Sales Order Lines" orientation="horizontal" type="bar">
378 The first field is the X axis. The second one is the Y axis and the optional third one is the Z axis for 3 dimensional graphs. You can apply a few attributes to each field/axis:
380 * **group**: if set to true, the client will group all item of the same value for this field. For each other field, it will apply an operator
381 * **operator**: the operator to apply is another field is grouped. By default it's '+'. Allowed values are:
386 + min: minimum of the list
387 + max: maximum of the list
389 :Defining real statistics on objects:
391 The easiest method to compute real statistics on objects is:
393 1. Define a statistic object which is a postgresql view
394 2. Create a tree view and a graph view on this object
396 You can get en example in all modules of the form: report\_.... Example: report_crm.
399 Controlling view actions
400 ------------------------
402 When defining a view, the following attributes can be added on the
403 opening element of the view (i.e. ``<form>``, ``<tree>``...)
406 set to ``false`` to hide the link / button which allows to create a new
410 set to ``false`` to hide the link / button which allows to remove a
414 set to ``false`` to hide the link / button which allows to
418 These attributes are available on form, tree, kanban and gantt
419 views. They are normally automatically set from the access rights of
420 the users, but can be forced globally in the view definition. A
421 possible use case for these attributes is to define an inner tree view
422 for a one2many relation inside a form view, in which the user cannot
423 add or remove related records, but only edit the existing ones (which
424 are presumably created through another way, such as a wizard).
430 Calendar view provides timeline/schedule view for the data.
435 Here is an example view:
439 <calendar color="user_id" date_delay="planned_hours" date_start="date_start" string="Tasks">
441 <field name="project_id"/>
444 Here is the list of supported attributes for ``calendar`` tag:
447 The title string for the view.
450 A ``datetime`` field to specify the starting date for the calendar item. This
451 attribute is required.
454 A ``datetime`` field to specify the end date. Ignored if ``date_delay``
455 attribute is specified.
458 A ``numeric`` field to specify time in hours for a record. This attribute
459 will get preference over ``date_stop`` and ``date_stop`` will be ignored.
462 An ``integer`` value to specify working day length. Default is ``8`` hours.
465 A field, generally ``many2one``, to colorize calendar/gantt items.
468 A string value to set default view/zoom mode. For ``calendar`` view, this can be
469 one of following (default is ``month``):
480 .. .. figure:: images/calendar_month.png
486 .. .. figure:: images/calendar_week.png
494 Gantt view provides timeline view for the data. Generally, it can be used to display
495 project tasks and resource allocation.
497 A Gantt chart is a graphical display of all the tasks that a project is composed of.
498 Each bar on the chart is a graphical representation of the length of time the task is
501 A resource allocation summary bar is shown on top of all the grouped tasks,
502 representing how effectively the resources are allocated among the tasks.
504 Color coding of the summary bar is as follows:
506 * `Gray` shows that the resource is not allocated to any task at that time
507 * `Blue` shows that the resource is fully allocated at that time.
508 * `Red` shows that the resource is overallocated
513 Here is an example view:
517 <gantt color="user_id" date_delay="planned_hours" date_start="date_start" string="Tasks">
518 <level object="project.project" link="project_id" domain="[]">
523 The ``attributes`` accepted by the ``gantt`` tag are similar to ``calendar`` view tag. The
524 ``level`` tag is used to group the records by some ``many2one`` field. Currently, only
525 one level is supported.
527 Here is the list of supported attributes for ``gantt`` tag:
530 The title string for the view.
533 A ``datetime`` field to specify the starting date for the gantt item. This
534 attribute is required.
537 A ``datetime`` field to specify the end date. Ignored if ``date_delay``
538 attribute is specified.
541 A ``numeric`` field to specify time in hours for a record. This attribute
542 will get preference over ``date_stop`` and ``date_stop`` will be ignored.
545 An ``integer`` value to specify working day length. Default is ``8`` hours.
548 A field, generally ``many2one``, to colorize calendar/gantt items.
551 A string value to set default view/zoom mode. For ``gantt`` view, this can be
552 one of following (default is ``month``):
564 The ``level`` tag supports following attributes:
567 An openerp object having many2one relationship with view object.
570 The field name in current object that links to the given ``object``.
573 The domain to be used to filter the given ``object`` records.
578 The left side pane displays list of the tasks grouped by the given ``level`` field.
579 You can reorder or change the group of any records by dragging them.
581 The main content pane displays horizontal bars plotted on a timeline grid. A group
582 of bars are summarized with a top summary bar displaying resource allocation of all
583 the underlying tasks.
585 You can change the task start time by dragging the tasks horizontally. While
586 end time can be changed by dragging right end of a bar.
590 The time is calculated considering ``day_length`` so a bar will span more
591 then one day if total time for a task is greater then ``day_length`` value.
596 .. .. figure:: images/gantt.png
604 The files describing the views are of the form:
610 <?xml version="1.0"?>
617 The view definitions contain mainly three types of tags:
619 * **<record>** tags with the attribute model="ir.ui.view", which contain the view definitions themselves
620 * **<record>** tags with the attribute model="ir.actions.act_window", which link actions to these views
621 * **<menuitem>** tags, which create entries in the menu, and link them with actions
623 New : You can specify groups for whom the menu is accessible using the groups
624 attribute in the `menuitem` tag.
626 New : You can now add shortcut using the `shortcut` tag.
633 name="Draft Purchase Order (Proposals)"
634 model="purchase.order"
638 Note that you should add an id attribute on the `menuitem` which is referred by
643 <record model="ir.ui.view" id="v">
644 <field name="name">sale.order.form</field>
645 <field name="model">sale.order</field>
646 <field name="priority" eval="2"/>
647 <field name="arch" type="xml">
648 <form string="Sale Order">
654 Default value for the priority field : 16. When not specified the system will use the view with the lower priority.
661 You can specify the columns to include in the list, along with some details of
662 the list's appearance. The search fields aren't specified here, they're
663 specified by the `select` attribute in the form view fields.
667 <record id="view_location_tree2" model="ir.ui.view">
668 <field name="name">stock.location.tree</field>
669 <field name="model">stock.location</field>
670 <field name="type">tree</field>
671 <field name="priority" eval="2"/>
672 <field name="arch" type="xml">
674 colors="blue:usage=='view';darkred:usage=='internal'">
676 <field name="complete_name"/>
677 <field name="usage"/>
680 invisible="'product_id' not in context"/>
683 invisible="'product_id' not in context"/>
688 That example is just a flat list, but you can also display a real tree structure
689 by specifying a `field_parent`. The name is a bit misleading, though; the field
690 you specify must contain a list of all **child** entries.
694 <record id="view_location_tree" model="ir.ui.view">
695 <field name="name">stock.location.tree</field>
696 <field name="model">stock.location</field>
697 <field name="type">tree</field>
698 <field name="field_parent">child_ids</field>
699 <field name="arch" type="xml">
701 <field icon="icon" name="name"/>
707 On the `tree` element, the following attributes are supported:
710 Conditions for applying different colors to items in the list. The default
713 Set this to 1 if you want a tree structure to list the top level entries
714 in a separate toolbar area. When you click on an entry in the toolbar, all
715 its descendants will be displayed in the main tree. The value is ignored
725 Adds a separator line
731 <separator string="Links" colspan="4"/>
733 The string attribute defines its label and the colspan attribute defines his horizontal size (in number of columns).
738 <notebook>: With notebooks you can distribute the view fields on different tabs (each one defined by a page tag). You can use the tabpos properties to set tab at: up, down, left, right.
744 <notebook colspan="4">....</notebook>
749 <group>: groups several columns and split the group in as many columns as desired.
751 * **colspan**: the number of columns to use
752 * **rowspan**: the number of rows to use
753 * **expand**: if we should expand the group or not
754 * **col**: the number of columns to provide (to its children)
755 * **string**: (optional) If set, a frame will be drawn around the group of fields, with a label containing the string. Otherwise, the frame will be invisible.
761 <group col="3" colspan="2">
762 <field name="invoiced" select="2"/>
763 <button colspan="1" name="make_invoice" states="confirmed" string="Make Invoice"
770 Defines a new notebook page for the view.
776 <page string="Order Line"> ... </page>:
778 * **string**: defines the name of the page.
786 :guilabel:`attributes for the "field" tag`
788 * ``select="1"``: mark this field as being one of the search criteria for
789 this resource's search view. A value of 1 means that the field is
790 included in the basic search, and a value of 2 means that it is in
793 * ``colspan="4"``: the number of columns on which a field must extend.
795 * ``readonly="1"``: set the widget as read only
797 * ``required="1"``: the field is marked as required. If a field is marked as required, a user has to fill it the system won't save the resource if the field is not filled. This attribute supersede the required field value defined in the object.
799 * ``nolabel="1"``: hides the label of the field (but the field is not hidden in the search view).
801 * ``invisible="True"``: hides both the label and the field.
803 * ``password="True"``: replace field values by asterisks, "*".
805 * ``string=""``: change the field label. Note that this label is also used in the search view: see select attribute above).
807 * ``domain``: can restrict the domain.
808 + Example: domain="[('partner_id','=',partner_id)]"
810 * ``widget``: can change the widget.
811 + Example: widget="one2many_list"
822 * ``mode``: sequences of the views when switching.
823 + Example: mode="tree,graph"
825 * ``on_change``: define a function that is called when the content of the field changes.
826 + Example: on_change="onchange_partner(type,partner_id)"
827 + See ViewsSpecialProperties for details
829 * ``attrs``: Permits to define attributes of a field depends on other fields of the same window. (It can be use on page, group, button and notebook tag also)
830 + Format: "{'attribute':[('field_name','operator','value'),('field_name','operator','value')],'attribute2':[('field_name','operator','value'),]}"
831 + where attribute will be readonly, invisible, required
833 + Example: (in product.product)
837 <field digits="(14, 3)" name="volume" attrs="{'readonly':[('type','=','service')]}"/>
839 * ``eval``: evaluate the attribute content as if it was Python code (see :ref:`below <eval-attribute-link>` for example)
841 * ``default_focus``: set to ``1`` to put the focus (cursor position) on this field when the form is first opened.
842 There can only be one field within a view having this attribute set to ``1`` **(new as of 5.2)**
846 <field name="name" default_focus=”1”/>
851 Here's the source code of the view of a sale order object. This is the same object as the object shown on the screen shots of the presentation.
857 <?xml version="1.0"?>
860 <record id="view_partner_form" model="ir.ui.view">
861 <field name="name">res.partner.form</field>
862 <field name="model">res.partner</field>
863 <field name="type">form</field>
864 <field name="arch" type="xml">
865 <form string="Partners">
866 <group colspan="4" col="6">
867 <field name="name" select="1"/>
868 <field name="ref" select="1"/>
869 <field name="customer" select="1"/>
870 <field domain="[('domain', '=', 'partner')]" name="title"/>
871 <field name="lang" select="2"/>
872 <field name="supplier" select="2"/>
874 <notebook colspan="4">
875 <page string="General">
876 <field colspan="4" mode="form,tree" name="address"
877 nolabel="1" select="1">
878 <form string="Partner Contacts">
879 <field name="name" select="2"/>
880 <field domain="[('domain', '=', 'contact')]" name="title"/>
881 <field name="function"/>
882 <field name="type" select="2"/>
883 <field name="street" select="2"/>
884 <field name="street2"/>
886 <field name="zip" select="2"/>
887 <field name="city" select="2"/>
889 <field completion="1" name="country_id" select="2"/>
890 <field name="state_id" select="2"/>
892 <field name="phone"/>
895 <field name="mobile"/>
896 <field name="email" select="2" widget="email"/>
898 <tree string="Partner Contacts">
902 <field name="country_id"/>
903 <field name="phone"/>
904 <field name="email"/>
907 <separator colspan="4" string="Categories"/>
908 <field colspan="4" name="category_id" nolabel="1" select="2"/>
910 <page string="Sales & Purchases">
911 <separator string="General Information" colspan="4"/>
912 <field name="user_id" select="2"/>
913 <field name="active" select="2"/>
914 <field name="website" widget="url"/>
915 <field name="date" select="2"/>
916 <field name="parent_id"/>
919 <page string="History">
920 <field colspan="4" name="events" nolabel="1" widget="one2many_list"/>
922 <page string="Notes">
923 <field colspan="4" name="comment" nolabel="1"/>
930 action="action_partner_form"
931 id="menu_partner_form"
932 parent="base.menu_base_partner"
937 .. _eval-attribute-link:
942 The **eval** attribute evaluate its content as if it was Python code. This
943 allows you to define values that are not strings.
945 Normally, content inside *<field>* tags are always evaluated as strings.
947 .. describe:: Example 1:
951 <field name="value">2.3</field>
953 This will evaluate to the string ``'2.3'`` and not the float ``2.3``
955 .. describe:: Example 2:
959 <field name="value">False</field>
961 This will evaluate to the string ``'False'`` and not the boolean
962 ``False``. This is especially tricky because Python's conversion rules
963 consider any non-empty string to be ``True``, so the above code will
964 end up storing the opposite of what is desired.
966 If you want to evaluate the value to a float, a boolean or another
967 type, except string, you need to use the **eval** attribute:
971 <field name="value" eval="2.3" />
972 <field name="value" eval="False" />
977 Adds a button to the current view. Allows the user to perform various
978 actions on the current record.
980 After a button has been clicked, the record should always be reloaded.
982 Buttons have the following attributes:
985 Defines the type of action performed when the button is activated:
987 ``workflow`` (default)
988 The button will send a workflow signal [#]_ on the current model
989 using the ``@name`` of the button as workflow signal name and
990 providing the record id as parameter (in a list).
992 The workflow signal may return an action descriptor, which should
993 be executed. Otherwise it will return ``False``.
996 The button will execute the method of name ``@name`` on the
997 current model, providing the record id as parameter (in a
998 list). This call may return an action descriptor to execute.
1001 The button will trigger the execution of an action
1002 (``ir.actions.actions``). The ``id`` of this action is the
1003 ``@name`` of the button.
1005 From there, follows the normal action-execution workflow.
1008 Only has one possible value currently: ``cancel``, which indicates
1009 that the popup should be closed without performing any RPC call or
1013 Only meaningful within a popup-type window (e.g. a
1014 wizard). Otherwise, is a noop.
1018 ``@special`` and ``@type`` are incompatible.
1021 The button's identifier, used to indicate which method should be
1022 called, which signal sent or which action executed.
1025 A confirmation popup to display before executing the button's
1026 task. If the confirmation is dismissed the button's task *must not*
1030 The label which should be displayed on the button [#]_.
1033 Display an icon on the button, if absent the button is text-only
1036 ``@states``, ``@attrs``, ``@invisible``
1037 Standard OpenERP meaning for those view attributes
1040 If set to a truthy value (``1``), automatically selects that button
1041 so it is used if ``RETURN`` is pressed while on the form.
1043 May be ignored by the client.
1045 .. versionadded:: 6.0
1051 <button name="order_confirm" states="draft" string="Confirm Order" icon="gtk-execute"/>
1052 <button name="_action_open_window" string="Open Margins" type="object" default_focus=”1”/>
1057 Adds a simple label using the string attribute as caption.
1063 <label string="Test"/>
1068 Force a return to the line even if all the columns of the view are not filled in.
1076 .. [#] via ``exec_workflow`` on the ``object`` rpc endpoint
1078 .. [#] in form view, in list view buttons have no label
1080 .. [#] behavior in list view is undefined, as list view buttons don't
1084 Inheritance in Views
1085 --------------------
1087 When you create and inherit objects in some custom or specific modules, it is better to inherit (than to replace) from an existing view to add/modify/delete some fields and preserve the others.
1093 <record model="ir.ui.view" id="view_partner_form">
1094 <field name="name">res.partner.form.inherit</field>
1095 <field name="model">res.partner</field>
1096 <field name="inherit_id" ref="base.view_partner_form"/>
1097 <field name="arch" type="xml">
1098 <notebook position="inside">
1099 <page string="Relations">
1100 <field name="relation_ids" colspan="4" nolabel="1"/>
1106 This will add a page to the notebook of the ``res.partner.form`` view in the
1109 The inheritance engine will parse the existing view and search for the root nodes of
1113 <field name="arch" type="xml">
1115 It will append or edit the content of this tag. If this tag has some attributes,
1116 it will look in the parent view for a node with matching attributes (except
1119 You can use these values in the position attribute:
1121 * inside (default): your values will be appended inside the tag
1122 * after: add the content after the tag
1123 * before: add the content before the tag
1124 * replace: replace the content of the tag.
1131 <record model="ir.ui.view" id="view_partner_form1">
1132 <field name="name">res.partner.form.inherit1</field>
1133 <field name="model">res.partner</field>
1134 <field name="inherit_id" ref="base.view_partner_form"/>
1135 <field name="arch" type="xml">
1136 <page string="Extra Info" position="replace">
1137 <field name="relation_ids" colspan="4" nolabel="1"/>
1142 Will replace the content of the Extra Info tab of the notebook with the ``relation_ids`` field.
1144 The parent and the inherited views are correctly updated with ``--update=all`` argument like any other views.
1149 To delete a field from a form, an empty element with ``position="replace"`` attribute is used. Example:
1153 <record model="ir.ui.view" id="view_partner_form2">
1154 <field name="name">res.partner.form.inherit2</field>
1155 <field name="model">res.partner</field>
1156 <field name="inherit_id" ref="base.view_partner_form"/>
1157 <field name="arch" type="xml">
1158 <field name="lang" position="replace"/>
1165 To add a field into a form before the specified tag use ``position="before"`` attribute.
1169 <record model="ir.ui.view" id="view_partner_form3">
1170 <field name="name">res.partner.form.inherit3</field>
1171 <field name="model">res.partner</field>
1172 <field name="inherit_id" ref="base.view_partner_form"/>
1173 <field name="arch" type="xml">
1174 <field name="lang" position="before">
1175 <field name="relation_ids"/>
1180 Will add ``relation_ids`` field before the ``lang`` field.
1182 To add a field into a form after the specified tag use ``position="after"`` attribute.
1186 <record model="ir.ui.view" id="view_partner_form4">
1187 <field name="name">res.partner.form.inherit4</field>
1188 <field name="model">res.partner</field>
1189 <field name="inherit_id" ref="base.view_partner_form"/>
1190 <field name="arch" type="xml">
1191 <field name="lang" position="after">
1192 <field name="relation_ids"/>
1197 Will add ``relation_ids`` field after the ``lang`` field.
1203 To make changes in more than one location, wrap the fields in a data element.
1207 <record model="ir.ui.view" id="view_partner_form5">
1208 <field name="name">res.partner.form.inherit5</field>
1209 <field name="model">res.partner</field>
1210 <field name="inherit_id" ref="base.view_partner_form"/>
1211 <field name="arch" type="xml">
1213 <field name="lang" position="replace"/>
1214 <field name="website" position="after">
1215 <field name="lang"/>
1221 Will delete the ``lang`` field from its usual location, and display it after
1222 the ``website`` field.
1224 .. _xpath-element-inheritance:
1229 Sometimes a view is too complicated to let you simply identify a target field
1230 by name. For example, the field might appear in two places. When that happens,
1231 you can use an ``xpath`` element to describe where your changes should be
1236 <record model="ir.ui.view" id="view_partner_form6">
1237 <field name="name">res.partner.form.inherit6</field>
1238 <field name="model">res.partner</field>
1239 <field name="inherit_id" ref="base.view_partner_form"/>
1240 <field name="arch" type="xml">
1243 expr="//field[@name='address']/form/field[@name='email']"
1248 expr="//field[@name='address']/tree/field[@name='email']"
1256 Will add the ``age`` field after the ``email`` field in both the form and tree
1257 view of the address list.
1260 Specify the views you want to use
1261 ---------------------------------
1263 There are some cases where you would like to specify a view other than the default:
1265 - If there are several form or tree views for an object.
1266 - If you want to change the form or tree view used by a relational field
1267 (one2many for example).
1269 Using the priority field
1270 ++++++++++++++++++++++++
1272 This field is available in the view definition, and is 16 by default. By
1273 default, OpenERP will display a model using the view with the highest priority
1274 (the smallest number). For example, imagine we have two views for a simple model.
1275 The model *client* with two fields : **firstname** and **lastname**. We will define
1276 two views, one which shows the firstname first, and the other one which shows
1283 Here is the first view for the model 'client'.
1284 We don't specify a priority field, which means
1287 <record model="ir.ui.view" id="client_form_view_1">
1288 <field name="name">client.form.view1</field>
1289 <field name="model">client</field>
1290 <field name="type">form</fiel>
1291 <field name="arch" type="xml">
1292 <field name="firstname"/>
1293 <field name="lastname"/>
1298 A second view, which show fields in an other order.
1299 We specify a priority of 15.
1301 <record model="ir.ui.view" id="client_form_view_2">
1302 <field name="name">client.form.view2</field>
1303 <field name="model">client</field>
1304 <field name="priority" eval="15"/>
1305 <field name="type">form</fiel>
1306 <field name="arch" type="xml">
1307 <field name="lastname"/>
1308 <field name="firstname"/>
1312 Now, each time OpenERP will have to show a form view for our object *client*, it will have the choice between two views.
1313 **It will always use the second one, because it has a higher priority !** Unless you tell it to use the first one !
1315 Specify per-action view
1316 +++++++++++++++++++++++
1318 To illustrate this point, we will create 2 menus which show a form view for this *client* object :
1324 This action open the default view (in our case,
1325 the view with the highest priority, the second one)
1328 model="ir.actions.act_window"
1329 id="client_form_action">
1330 <field name="name">client.form.action</field>
1331 <field name="res_model">client</field>
1332 <field name="view_type">form</field>
1333 <field name="view_mode">form</field>
1337 This action open the view we specify.
1340 model="ir.actions.act_window"
1341 id="client_form_action1">
1342 <field name="name">client.form.action1</field>
1343 <field name="res_model">client</field>
1344 <field name="view_type">form</field>
1345 <field name="view_mode">form</field>
1346 <field name="view_id" ref="client_form_view_1"/>
1349 <menuitem id="menu_id" name="Client main menu"/>
1352 name="Here we don't specify the view"
1353 action="client_form_action" parent="menu_id"/>
1356 name="Here we specify the view"
1357 action="client_form_action1" parent="menu_id"/>
1359 As you can see on line *19*, we can specify a view. That means that when we open
1360 the second menu, OpenERP will use the form view *client_form_view_1*, regardless
1365 Remember to use the module name (*module.view_id*) in the *ref* attribute if
1366 you are referring to a view defined in another module.
1368 Specify views for related fields
1369 ++++++++++++++++++++++++++++++++
1374 The *view_id* method works very well for menus/actions, but how can you specify the view to use for a one2many
1375 field, for example? When you have a one2many field, two views are used, a tree view (**in blue**), and a form view when
1376 you click on the add button (**in red**).
1378 .. .. figure:: images/one2many_views.png
1382 When you add a one2many field in a form view, you do something like this :
1386 <field name="order_line" colspan="4" nolabel="1"/>
1388 If you want to specify the views to use, you can add a *context* attribute, and
1389 specify a view id for each type of view supported, exactly like the action's
1390 *view_id* attribute, except that the provided view id must always be
1391 fully-qualified with the module name, even if it belongs to the same module:
1395 <field name="order_line" colspan="4" nolabel="1"
1396 context="{'form_view_ref': 'module.view_id',
1397 'tree_view_ref': 'module.view_id'}"/>
1401 You *have to* put the module name in the view_id, because this
1402 is evaluated when the view is displayed, and not when the XML file
1403 is parsed, so the module name information is not available. Failing
1404 to do so will result in the default view being selected (see
1407 If you don't specify the views, OpenERP will choose one in this order :
1409 1. It will use the <form> or <tree> view defined **inside** the field (see below)
1410 2. Else, it will use the views with the highest priority for this object.
1411 3. Finally, it will generate default empty views, with all fields.
1415 The context keys are named <view_type>_view_ref.
1419 By default, OpenERP will never use a view that is not defined for your object. If you have two models, with the
1420 same fields, but a different model name, OpenERP will never use the view of one for the other,
1421 even if one model inherit an other.
1423 You can force this by manually specifying the view, either in the action or in the context.
1428 In the case of relational fields, you can create a view directly inside a field :
1432 <record model="ir.ui.view" id="some_view">
1433 <field name="name">some.view</field>
1434 <field name="type">form</field>
1435 <field name="model">some.model.with.one2many</field>
1436 <field name="arch" type="xml">
1439 <!-- <=== order_line is a one2many field -->
1440 <field name="order_line" colspan="4" nolabel="1">
1452 If you or another developer want to inherit from this view in another module,
1453 you need to inherit from the parent view and then modify the child fields.
1454 With child views, you'll often need to use an :ref:`xpath-element-inheritance`
1455 to describe exactly where to place your new fields.
1459 <record model="ir.ui.view" id="some_inherited_view">
1460 <field name="name">some.inherited.view</field>
1461 <field name="type">form</field>
1462 <field name="model">some.model.with.one2many</field>
1463 <field name="inherit_id" ref="core_module.some_view"/>
1464 <field name="arch" type="xml">
1467 expr="//field[@name='order_line']/form/field[@name='qty']"
1469 <field name="size"/>
1472 expr="//field[@name='order_line']/tree/field[@name='qty']"
1474 <field name="size"/>
1479 One down side of defining a subview like this is that it can't be inherited on
1480 its own, it can only be inherited with the parent view. Your views will be more
1481 flexible if you define the child views separately and then specify which child
1482 view to use as part of the one2many field.