1 .. _form-view-guidelines:
6 Authors: Aline Preillon, Raphael Collet
9 This document presents functional and technical guidelines for
10 creating/organizing form views in OpenERP version 7.0. For each item, both the
11 functional and technical aspects are explained. The goal of the new style of
12 forms is to make OpenERP easier to use, and to guide users through the system.
17 Business views are targeted at regular users, not advanced users. Examples
18 are: Opportunities, Products, Partners, Tasks, Projects, etc.
20 .. image:: /form-view-guidelines/oppreadonly.png
22 In general, a business view is composed of
24 1. a status bar on top (with technical or business flow),
25 2. a sheet in the middle (the form itself),
26 3. a bottom part with History and Comments.
28 Technically, the new form views are structured as follows in XML::
31 <header> ... content of the status bar ... </header>
32 <sheet> ... content of the sheet ... </sheet>
33 <div class=”oe_chatter”> ... content of the bottom part ... </div>
39 The purpose of the status bar is to show the status of the record and the
40 action buttons, which were formerly at the bottom of form views.
42 .. image:: /form-view-guidelines/status.png
47 The order of buttons follows the business flow. For instance, in a sale order,
48 the logical steps are:
51 2. Confirm the quotation
52 3. Create the final invoice
55 Highlighted buttons (in red) emphasize the logical next step, to help the user.
56 It is usually the first active button. On the other end, cancel buttons must
57 remain grey (normal). For instance, in Invoice, the button “Refund” must never
60 Technically, buttons are highlighted by adding the class “oe_highlight”::
62 <button class=”oe_highlight” name=”...” type=”...” states=”...”/>
67 We use the widget “statusbar”, and the current value of the state is shown in
68 red. One should make visible the states that are common to all flows (for
69 instance, a sale order begins as a quotation, then we send it, then it becomes
70 a full sale order, and finally it is done.) Exceptions or states depending on
71 particular flow are only visible if it is the current one.
73 .. image:: /form-view-guidelines/status1.png
75 .. image:: /form-view-guidelines/status2.png
77 The states are shown following the order used in the field (the list in a
78 selection field, etc). States that are always visible are indicated by the
79 attribute statusbar_visible. One can also show some states in a specific color
80 with statusbar_colors.
84 <field name="state" widget="statusbar"
85 statusbar_visible="draft,sent,progress,invoiced,done"
86 statusbar_colors="{‘shipping_except’:’red’,’waiting_date’:’blue’}"/>
91 All business views should look like a printed sheet:
93 .. image:: /form-view-guidelines/sheet.png
95 Technically, the layout of forms version 7.0 is different than former versions.
96 There is no longer a default “grid” layout; instead the layout is more based on
97 HTML and CSS. The following conventions are now used:
99 1. The elements <form> and <page> no longer define groups; the elements inside
100 are laid out inline. One should use explicit <div> or <group> to create
102 2. By default, the element <group> now defines two columns inside, unless an
103 attribute col=”n” is used. The columns have the same width (1/n th of the
104 group’s width). Use a <group> element to produce a column of fields.
105 3. The element <separator string=”XXX”/> on top of a group can be replaced
106 putting string=”XXX” inside the <group> element.
107 4. The element <field name=”XXX”/> does not produce a label, except when they
108 are directly below a <group> element. Use <label for=”XXX”/> to produce
109 the label of the field.
114 Some sheets have headers with one or more fields, and the labels of those
115 fields are only shown in edit mode.
117 +---------------------------------------------+----------------------------------------------+
118 | View mode | Edit mode |
119 +---------------------------------------------+----------------------------------------------+
120 | .. image:: /form-view-guidelines/header.png | .. image:: /form-view-guidelines/header2.png |
121 +---------------------------------------------+----------------------------------------------+
123 Use HTML text, <div>, <h1>, <h2>… to produce nice headers, and <label> with the
124 CSS class “oe_edit_only” to produce the field’s label in edit mode. Use the
125 CSS class “oe_inline” to produce inline fields (not blocks). The form above is
126 produced by the following XML.
130 <label for="name" class="oe_edit_only"/>
131 <h1><field name="name"/></h1>
133 <label for="planned_revenue" class="oe_edit_only"/>
135 <field name="planned_revenue" class="oe_inline"/>
136 <field name="company_currency" class="oe_inline oe_edit_only"/> at
137 <field name="probability" class="oe_inline"/> % success rate
143 Many relevant actions or links can be directly displayed in the form. For
144 example, in Opportunity form, the actions “Schedule a Call” and “Schedule a
145 Meeting” take an important place in the use of the CRM. Instead of placing
146 them in the “More” menu of the sidebar, put them directly in the sheet as
147 buttons (on the top right).
149 .. image:: /form-view-guidelines/header3.png
151 Technically, the buttons are placed inside a <div> to group them as a block on
152 the right-hand side of the sheet.
156 <div class="oe_button_box oe_right">
157 <button string="Schedule/Log Call" name="..." type="action"/>
158 <button string="Schedule Meeting" name="action_makeMeeting" type="object"/>
164 A column of fields is now produced with a <group> element, with an optional
165 title. The title has the same effect as placing an explicit <separator>
166 element inside the group.
168 .. image:: /form-view-guidelines/screenshot-03.png
172 <group string="Payment Options">
173 <field name="writeoff_amount"/>
174 <field name="payment_option"/>
177 It is recommended to have two columns of fields on the form. For this, simply
178 put the <group> elements that contain the fields inside a <group> element.
180 To ease view inheritance, it is recommended to put a name=”...” in <group>
181 elements. Adding fields inside such a group is trivial.
183 Special Case: Subtotals
184 ~~~~~~~~~~~~~~~~~~~~~~~
186 Some CSS classes are defined to render subtotals like in invoice forms:
188 .. image:: /form-view-guidelines/screenshot-00.png
192 <group class="oe_subtotal_footer">
193 <field name="amount_untaxed"/>
194 <field name="amount_tax"/>
195 <field name="amount_total" class="oe_subtotal_footer_separator"/>
196 <field name="residual" style="margin-top: 10px"/>
199 Placeholders and Inline Fields
200 ..............................
202 Sometimes field labels make the form too complex. One can omit field labels,
203 and instead put a placeholder inside the field. The placeholder text is
204 visible only when the field is empty. The placeholder should tell what to
205 place inside the field, and not be an example.
207 One can also group fields together by rendering them “inline” inside an
208 explicit block element like <div>. This allows to group several elements in
209 place of a field (without its label).
211 The following example, taken from the Leads form, shows both placeholders and
212 inline fields (zip and city).
214 +--------------------------------------------------+----------------------------------------------------+
215 | Edit mode | View mode |
216 +--------------------------------------------------+----------------------------------------------------+
217 | .. image:: /form-view-guidelines/placeholder.png | .. image:: /form-view-guidelines/screenshot-01.png |
218 +--------------------------------------------------+----------------------------------------------------+
223 <label for="street" string="Address"/>
225 <field name="street" placeholder="Street..."/>
226 <field name="street2"/>
228 <field name="zip" class="oe_inline" placeholder="ZIP"/>
229 <field name="city" class="oe_inline" placeholder="City"/>
231 <field name="state_id" placeholder="State"/>
232 <field name="country_id" placeholder="Country"/>
239 Images, like avatars, should be displayed on the right of the sheet. The
240 product form looks like:
242 .. image:: /form-view-guidelines/screenshot-02.png
244 The form above contains a <sheet> element that starts with::
246 <field name="product_image" widget="image" class="oe_avatar oe_right"/>
251 Many2many fields, like categories, are better rendered as a list of tags. Use
252 the widget “many2many_tags”:
254 .. image:: /form-view-guidelines/screenshot-04.png
258 <field name="category_id"
259 widget="many2many_tags"/>
261 Configuration Forms and Wizards
262 -------------------------------
267 Examples of configuration forms: Stages, Leave Type, etc. This concerns all
268 menu items under Configuration of each application (like Sales/Configuration).
270 .. image:: /form-view-guidelines/nosheet.png
272 For those views, the guidelines are:
274 1. no header (because no state, no workflow, no button)
277 Regular Wizards (Popup)
278 '''''''''''''''''''''''
280 Example: “Schedule a Call” from an opportunity.
282 .. image:: /form-view-guidelines/wizard-popup.png
286 1. avoid separators (the title is already in the popup title bar, so another
287 separator is not relevant);
288 2. avoid cancel buttons (user generally close the popup window to get the same
290 3. action buttons must be highlighted (red);
291 4. when there is a text area, use a placeholder instead of a label or a
293 5. like in regular form views, put buttons in the <header> element.
298 Example: Settings / Configuration / Sales. The guidelines are:
300 1. always in line (no popup);
302 3. keep the cancel button (users cannot close the window);
303 4. the button “Apply” must be red.