[ADD] doc: added Form View Guidelines (authored by apr and rco).

bzr revid: vmt@openerp.com-20130328155941-5cxok3ymhiolrfo5

14 files changed, 300 insertions, 0 deletions

diff --git a/doc/form-view-guidelines.rst b/doc/form-view-guidelines.rst
new file mode 100644
index 00000000000..f00fb005039
--- /dev/null
+++ b/doc/form-view-guidelines.rst
@@ -0,0 +1,299 @@
+.. _form-view-guidelines:
+
+Form Views Guidelines
+=====================
+
+Authors: Aline Preillon, Raphael Collet
+
+
+This document presents functional and technical guidelines for
+creating/organizing form views in OpenERP version 7.0.  For each item, both the
+functional and technical aspects are explained.  The goal of the new style of
+forms is to make OpenERP easier to use, and to guide users through the system.
+
+Business Views
+--------------
+
+Business views are targeted at regular users, not advanced users.  Examples
+are: Opportunities, Products, Partners, Tasks, Projects, etc.
+
+oppreadonly.png
+
+In general, a business view is composed of
+
+1. a status bar on top (with technical or business flow),
+2. a sheet in the middle (the form itself),
+3. a bottom part with History and Comments.
+
+Technically, the new form views are structured as follows in XML::
+
+    <form version=”7.0”>
+        <header> ... content of the status bar  ... </header>
+        <sheet>  ... content of the sheet       ... </sheet>
+        <div class=”oe_chatter”> ... content of the bottom part ... </div>
+    </form>
+
+The Status Bar
+''''''''''''''
+
+The purpose of the status bar is to show the status of the record and the
+action buttons, which were formerly at the bottom of form views.
+
+status.png
+
+The Buttons
+...........
+
+The order of buttons follows the business flow.  For instance, in a sale order,
+the logical steps are:
+
+1. Send the quotation
+2. Confirm the quotation
+3. Create the final invoice
+4. Send the goods
+
+Highlighted buttons (in red) emphasize the logical next step, to help the user.
+It is usually the first active button.  On the other end, cancel buttons must
+remain grey (normal).  For instance, in Invoice, the button “Refund” must never
+be red.
+
+Technically, buttons are highlighted by adding the class “oe_highlight”::
+
+    <button class=”oe_highlight” name=”...” type=”...” states=”...”/>
+
+The Status
+..........
+
+We use the widget “statusbar”, and the current value of the state is shown in
+red.  One should make visible the states that are common to all flows (for
+instance, a sale order begins as a quotation, then we send it, then it becomes
+a full sale order, and finally it is done.)  Exceptions or states depending on
+particular flow are only visible if it is the current one.
+
+The states are shown following the order used in the field (the list in a
+selection field, etc).  States that are always visible are indicated by the
+attribute statusbar_visible.  One can also show some states in a specific color
+with statusbar_colors.
+
+::
+
+    <field name="state" widget="statusbar"
+        statusbar_visible="draft,sent,progress,invoiced,done"
+        statusbar_colors="{‘shipping_except’:’red’,’waiting_date’:’blue’}"/>
+
+The Sheet
+'''''''''
+
+All business views should look like a printed sheet:
+
+sheet.png
+
+Technically, the layout of forms version 7.0 is different than former versions.
+There is no longer a default “grid” layout; instead the layout is more based on
+HTML and CSS.  The following conventions are now used:
+
+1. The elements <form> and <page> no longer define groups; the elements inside
+   are laid out inline.  One should use explicit <div> or <group> to create
+   blocks.
+2. By default, the element <group> now defines two columns inside, unless an
+   attribute col=”n” is used.  The columns have the same width (1/n th of the
+   group’s width).  Use a <group> element to produce a column of fields.
+3. The element <separator string=”XXX”/> on top of a group can be replaced
+   putting string=”XXX” inside the <group> element.
+4. The element <field name=”XXX”/> does not produce a label, except when they
+   are directly below a <group> element.  Use <label for=”XXX”/> to produce
+   the label of the field.
+
+Sheet Headers
+.............
+
+Some sheets have headers with one or more fields, and the labels of those
+fields are only shown in edit mode.
+
++------------+-------------+
+| View mode  |  Edit mode  |
++------------+-------------+
+| header.png | header2.png |
++------------+-------------+
+
+Use HTML text, <div>, <h1>, <h2>… to produce nice headers, and <label> with the
+CSS class “oe_edit_only” to produce the field’s label in edit mode.  Use the
+CSS class “oe_inline” to produce inline fields (not blocks). The form above is
+produced by the following XML.
+
+::
+
+    <label for="name" class="oe_edit_only"/>
+    <h1><field name="name"/></h1>
+
+    <label for="planned_revenue" class="oe_edit_only"/>
+    <h2>
+        <field name="planned_revenue" class="oe_inline"/>
+        <field name="company_currency" class="oe_inline oe_edit_only"/> at 
+        <field name="probability" class="oe_inline"/> % success rate
+    </h2>
+
+Button Box
+..........
+
+Many relevant actions or links can be directly displayed in the form.  For
+example, in Opportunity form, the actions “Schedule a Call” and “Schedule a
+Meeting” take an important place in the use of the CRM.  Instead of placing
+them in the “More” menu of the sidebar, put them directly in the sheet as
+buttons (on the top right).
+
+header3.png
+
+Technically, the buttons are placed inside a <div> to group them as a block on
+the right-hand side of the sheet.
+
+::
+
+    <div class="oe_button_box oe_right">
+        <button string="Schedule/Log Call" name="..." type="action"/>
+        <button string="Schedule Meeting" name="action_makeMeeting" type="object"/>
+    </div>
+
+Groups and Titles
+.................
+
+A column of fields is now produced with a <group> element, with an optional
+title.  The title has the same effect as placing an explicit <separator>
+element inside the group.
+
+<image>.png
+
+::
+
+    <group string="Payment Options">
+        <field name="writeoff_amount"/>
+        <field name="payment_option"/>
+    </group>
+
+It is recommended to have two columns of fields on the form.  For this, simply
+put the <group> elements that contain the fields inside a <group> element.
+
+To ease view inheritance, it is recommended to put a name=”...” in <group>
+elements.  Adding fields inside such a group is trivial.
+
+Special Case: Subtotals
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Some CSS classes are defined to render subtotals like in invoice forms:
+
+screenshot-00.png
+
+::
+
+    <group class="oe_subtotal_footer">
+        <field name="amount_untaxed"/>
+        <field name="amount_tax"/>
+        <field name="amount_total" class="oe_subtotal_footer_separator"/>
+        <field name="residual" style="margin-top: 10px"/>
+    </group>
+
+Placeholders and Inline Fields
+..............................
+
+Sometimes field labels make the form too complex.  One can omit field labels,
+and instead put a placeholder inside the field.  The placeholder text is
+visible only when the field is empty.  The placeholder should tell what to
+place inside the field, and not be an example.
+
+One can also group fields together by rendering them “inline” inside an
+explicit block element like <div>.  This allows to group several elements in
+place of a field (without its label).
+
+The following example, taken from the Leads form, shows both placeholders and
+inline fields (zip and city).
+
++-----------------+-------------------+
+|    Edit mode    |     View mode     |
++-----------------+-------------------+
+| placeholder.png | screenshot-01.png |
++-----------------+-------------------+
+
+::
+
+    <group>
+        <label for="street" string="Address"/>
+        <div>
+            <field name="street" placeholder="Street..."/>
+            <field name="street2"/>
+            <div>
+                <field name="zip" class="oe_inline" placeholder="ZIP"/>
+                <field name="city" class="oe_inline" placeholder="City"/>
+            </div>
+            <field name="state_id" placeholder="State"/>
+            <field name="country_id" placeholder="Country"/>
+        </div>
+    </group>
+
+Images
+......
+
+Images, like avatars, should be displayed on the right of the sheet.  The
+product form looks like:
+
+screenshot-02.png
+
+The form above contains a <sheet> element that starts with::
+
+    <field name="product_image" widget="image" class="oe_avatar oe_right"/>
+
+Tags
+....
+
+Many2many fields, like categories, are better rendered as a list of tags.  Use
+the widget “many2many_tags”:
+
+<image>.png
+
+::
+
+    <field name="category_id"
+        widget="many2many_tags"/>
+
+Configuration Forms and Wizards
+-------------------------------
+
+Configuration Forms
+'''''''''''''''''''
+
+Examples of configuration forms: Stages, Leave Type, etc.  This concerns all
+menu items under Configuration of each application (like Sales/Configuration).
+
+nosheet.png
+
+For those views, the guidelines are:
+
+1. no header (because no state, no workflow, no button)
+2. no sheet
+
+Regular Wizards (Popup)
+'''''''''''''''''''''''
+
+Example: “Schedule a Call” from an opportunity.
+
+wizard-popup.png
+
+The guidelines are:
+
+1. avoid separators (the title is already in the popup title bar, so another
+   separator is not relevant);
+2. avoid cancel buttons (user generally close the popup window to get the same
+   effect);
+3. action buttons must be highlighted (red);
+4. when there is a text area, use a placeholder instead of a label or a
+   separator;
+5. like in regular form views, put buttons in the <header> element.
+
+Configuration Wizard
+''''''''''''''''''''
+
+Example: Settings / Configuration / Sales.  The guidelines are:
+
+1. always in line (no popup);
+2. no sheet;
+3. keep the cancel button (users cannot close the window);
+4. the button “Apply” must be red.
diff --git a/doc/form-view-guidelines/header.png b/doc/form-view-guidelines/header.png
new file mode 100644
index 00000000000..ab50afac777
--- /dev/null
+++ b/doc/form-view-guidelines/header.png
diff --git a/doc/form-view-guidelines/header2.png b/doc/form-view-guidelines/header2.png
new file mode 100644
index 00000000000..108301ba392
--- /dev/null
+++ b/doc/form-view-guidelines/header2.png
diff --git a/doc/form-view-guidelines/header3.png b/doc/form-view-guidelines/header3.png
new file mode 100644
index 00000000000..15354004730
--- /dev/null
+++ b/doc/form-view-guidelines/header3.png
diff --git a/doc/form-view-guidelines/nosheet.png b/doc/form-view-guidelines/nosheet.png
new file mode 100644
index 00000000000..ba259e22771
--- /dev/null
+++ b/doc/form-view-guidelines/nosheet.png
diff --git a/doc/form-view-guidelines/oppreadonly.png b/doc/form-view-guidelines/oppreadonly.png
new file mode 100644
index 00000000000..d6109c84965
--- /dev/null
+++ b/doc/form-view-guidelines/oppreadonly.png
diff --git a/doc/form-view-guidelines/placeholder.png b/doc/form-view-guidelines/placeholder.png
new file mode 100644
index 00000000000..c09f3fc529f
--- /dev/null
+++ b/doc/form-view-guidelines/placeholder.png
diff --git a/doc/form-view-guidelines/screenshot-00.png b/doc/form-view-guidelines/screenshot-00.png
new file mode 100644
index 00000000000..306e8283d13
--- /dev/null
+++ b/doc/form-view-guidelines/screenshot-00.png
diff --git a/doc/form-view-guidelines/screenshot-01.png b/doc/form-view-guidelines/screenshot-01.png
new file mode 100644
index 00000000000..710c1e52d15
--- /dev/null
+++ b/doc/form-view-guidelines/screenshot-01.png
diff --git a/doc/form-view-guidelines/screenshot-02.png b/doc/form-view-guidelines/screenshot-02.png
new file mode 100644
index 00000000000..4bc7b773bbf
--- /dev/null
+++ b/doc/form-view-guidelines/screenshot-02.png
diff --git a/doc/form-view-guidelines/sheet.png b/doc/form-view-guidelines/sheet.png
new file mode 100644
index 00000000000..93672a67fdb
--- /dev/null
+++ b/doc/form-view-guidelines/sheet.png
diff --git a/doc/form-view-guidelines/status.png b/doc/form-view-guidelines/status.png
new file mode 100644
index 00000000000..d0cb3f02209
--- /dev/null
+++ b/doc/form-view-guidelines/status.png
diff --git a/doc/form-view-guidelines/wizard-popup.png b/doc/form-view-guidelines/wizard-popup.png
new file mode 100644
index 00000000000..2bcdd153d82
--- /dev/null
+++ b/doc/form-view-guidelines/wizard-popup.png
diff --git a/doc/index.rst b/doc/index.rst
index 5dbea31f02e..e641de1da67 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -18,6 +18,7 @@ OpenERP Server
    06_misc
    deployment-gunicorn
    deployment-mod-wsgi
+   form-view-guidelines
 
 OpenERP Command
 '''''''''''''''