doc/form-view-guidelines.rst

   1 .. _form-view-guidelines:
   2
   3 Form Views Guidelines
   4 =====================
   5
   6 Authors: Aline Preillon, Raphael Collet
   7
   8
   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.
  13
  14 Business Views
  15 --------------
  16
  17 Business views are targeted at regular users, not advanced users.  Examples
  18 are: Opportunities, Products, Partners, Tasks, Projects, etc.
  19
  20 .. image:: /form-view-guidelines/oppreadonly.png
  21
  22 In general, a business view is composed of
  23
  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.
  27
  28 Technically, the new form views are structured as follows in XML::
  29
  30     <form version=”7.0”>
  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>
  34     </form>
  35
  36 The Status Bar
  37 ''''''''''''''
  38
  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.
  41
  42 .. image:: /form-view-guidelines/status.png
  43
  44 The Buttons
  45 ...........
  46
  47 The order of buttons follows the business flow.  For instance, in a sale order,
  48 the logical steps are:
  49
  50 1. Send the quotation
  51 2. Confirm the quotation
  52 3. Create the final invoice
  53 4. Send the goods
  54
  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
  58 be red.
  59
  60 Technically, buttons are highlighted by adding the class “oe_highlight”::
  61
  62     <button class=”oe_highlight” name=”...” type=”...” states=”...”/>
  63
  64 The Status
  65 ..........
  66
  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.
  72
  73 .. image:: /form-view-guidelines/status1.png
  74
  75 .. image:: /form-view-guidelines/status2.png
  76
  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.
  81
  82 ::
  83
  84     <field name="state" widget="statusbar"
  85         statusbar_visible="draft,sent,progress,invoiced,done"
  86         statusbar_colors="{‘shipping_except’:’red’,’waiting_date’:’blue’}"/>
  87
  88 The Sheet
  89 '''''''''
  90
  91 All business views should look like a printed sheet:
  92
  93 .. image:: /form-view-guidelines/sheet.png
  94
  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:
  98
  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
 101    blocks.
 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.
 110
 111 Sheet Headers
 112 .............
 113
 114 Some sheets have headers with one or more fields, and the labels of those
 115 fields are only shown in edit mode.
 116
 117 +---------------------------------------------+----------------------------------------------+
 118 |            View mode                        |                  Edit mode                   |
 119 +---------------------------------------------+----------------------------------------------+
 120 | .. image:: /form-view-guidelines/header.png | .. image:: /form-view-guidelines/header2.png |
 121 +---------------------------------------------+----------------------------------------------+
 122
 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.
 127
 128 ::
 129
 130     <label for="name" class="oe_edit_only"/>
 131     <h1><field name="name"/></h1>
 132
 133     <label for="planned_revenue" class="oe_edit_only"/>
 134     <h2>
 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
 138     </h2>
 139
 140 Button Box
 141 ..........
 142
 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).
 148
 149 .. image:: /form-view-guidelines/header3.png
 150
 151 Technically, the buttons are placed inside a <div> to group them as a block on
 152 the right-hand side of the sheet.
 153
 154 ::
 155
 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"/>
 159     </div>
 160
 161 Groups and Titles
 162 .................
 163
 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.
 167
 168 .. image:: /form-view-guidelines/screenshot-03.png
 169
 170 ::
 171
 172     <group string="Payment Options">
 173         <field name="writeoff_amount"/>
 174         <field name="payment_option"/>
 175     </group>
 176
 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.
 179
 180 To ease view inheritance, it is recommended to put a name=”...” in <group>
 181 elements.  Adding fields inside such a group is trivial.
 182
 183 Special Case: Subtotals
 184 ~~~~~~~~~~~~~~~~~~~~~~~
 185
 186 Some CSS classes are defined to render subtotals like in invoice forms:
 187
 188 .. image:: /form-view-guidelines/screenshot-00.png
 189
 190 ::
 191
 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"/>
 197     </group>
 198
 199 Placeholders and Inline Fields
 200 ..............................
 201
 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.
 206
 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).
 210
 211 The following example, taken from the Leads form, shows both placeholders and
 212 inline fields (zip and city).
 213
 214 +--------------------------------------------------+----------------------------------------------------+
 215 |                 Edit mode                        |                    View mode                       |
 216 +--------------------------------------------------+----------------------------------------------------+
 217 | .. image:: /form-view-guidelines/placeholder.png | .. image:: /form-view-guidelines/screenshot-01.png |
 218 +--------------------------------------------------+----------------------------------------------------+
 219
 220 ::
 221
 222     <group>
 223         <label for="street" string="Address"/>
 224         <div>
 225             <field name="street" placeholder="Street..."/>
 226             <field name="street2"/>
 227             <div>
 228                 <field name="zip" class="oe_inline" placeholder="ZIP"/>
 229                 <field name="city" class="oe_inline" placeholder="City"/>
 230             </div>
 231             <field name="state_id" placeholder="State"/>
 232             <field name="country_id" placeholder="Country"/>
 233         </div>
 234     </group>
 235
 236 Images
 237 ......
 238
 239 Images, like avatars, should be displayed on the right of the sheet.  The
 240 product form looks like:
 241
 242 .. image:: /form-view-guidelines/screenshot-02.png
 243
 244 The form above contains a <sheet> element that starts with::
 245
 246     <field name="product_image" widget="image" class="oe_avatar oe_right"/>
 247
 248 Tags
 249 ....
 250
 251 Many2many fields, like categories, are better rendered as a list of tags.  Use
 252 the widget “many2many_tags”:
 253
 254 .. image:: /form-view-guidelines/screenshot-04.png
 255
 256 ::
 257
 258     <field name="category_id"
 259         widget="many2many_tags"/>
 260
 261 Configuration Forms and Wizards
 262 -------------------------------
 263
 264 Configuration Forms
 265 '''''''''''''''''''
 266
 267 Examples of configuration forms: Stages, Leave Type, etc.  This concerns all
 268 menu items under Configuration of each application (like Sales/Configuration).
 269
 270 .. image:: /form-view-guidelines/nosheet.png
 271
 272 For those views, the guidelines are:
 273
 274 1. no header (because no state, no workflow, no button)
 275 2. no sheet
 276
 277 Regular Wizards (Popup)
 278 '''''''''''''''''''''''
 279
 280 Example: “Schedule a Call” from an opportunity.
 281
 282 .. image:: /form-view-guidelines/wizard-popup.png
 283
 284 The guidelines are:
 285
 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
 289    effect);
 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
 292    separator;
 293 5. like in regular form views, put buttons in the <header> element.
 294
 295 Configuration Wizard
 296 ''''''''''''''''''''
 297
 298 Example: Settings / Configuration / Sales.  The guidelines are:
 299
 300 1. always in line (no popup);
 301 2. no sheet;
 302 3. keep the cancel button (users cannot close the window);
 303 4. the button “Apply” must be red.