[MERGE] Sync with trunk.

bzr revid: tde@openerp.com-20121108161124-au0kg2b4h2uzzf6c

5 files changed, 55 insertions, 1 deletions

diff --git a/doc/index.rst.inc b/doc/index.rst.inc
index 31ac2494a48..d7710067fb8 100644
--- a/doc/index.rst.inc
+++ b/doc/index.rst.inc
@@ -7,6 +7,7 @@ OpenERP Server
 
    import
    module-versioning
+   on_change_tips
    test-framework
 
 Changed in 7.0
diff --git a/doc/on_change_tips.rst b/doc/on_change_tips.rst
new file mode 100644
index 00000000000..05186d09740
--- /dev/null
+++ b/doc/on_change_tips.rst
@@ -0,0 +1,51 @@
+.. _on_change_tips:
+
+On Change Methods
+=================
+
+Definition of on change methods in a view looks like this:
+
+::
+
+    <field name="name" on_change="name_change(name, address, city)"/>
+
+And here is the corresponding method in the model:
+
+::
+
+    def name_change(self, cr, uid, ids, name, address, city, context=None):
+        ...
+        return {
+            'value': {
+                'address': ...
+                'city': ...
+            }
+        }
+
+On change methods can be confusing when people use them, here are a list of clarifications to avoid any misconception:
+
+- On change methods can be executed during the creation of a row, long before it is effectively saved into the database.
+- Fields are *not* validated before going through a on change methods. As an example, a field marqued as required can be False.
+- On change methods can read data in the database but should *never* attempt to write anything, this is always a strong conception
+  problem.
+- The format of the values passed to an on change method is exactly the same than the one passed to the write() method. So
+  the on change method must be able to handle any format used for all the fields it process. The following list describe some fields
+  that can have an unusual format.
+
+  - *float*: Due to the way JSON represents numbers and the way the JSON library of Python handles it, a float field will not always
+    be represented as a python float type. When the number can be represented as an integer it will appear as a python integer type.
+    This can be a problem when using some mathematical operations (example: price / 2), so it is a good practice to always cast any number
+    to float when you want to handle floats in on change methods.
+  - *one2many and many2many*: There are plenty of misconception about x2many fields in on change methods. The reality is, in fact, quite
+    complex. x2many are defined by a list of operations, each operation was given a number (0 -> create, 1 -> write, ect...) and has
+    its own semantic. To be able to use one2many and many2many in on change methods, you are strongly encourage to use the
+    resolve_2many_commands() method. Here is a sample usage:
+
+    ::
+
+        values = self.resolve_2many_commands(cr, uid, 'my_o2m', my_o2m_values, ['price', 'tax'], context)
+
+    This code will convert the complex list of operations that makes the o2m value into a simple list of dictionaries containing the fields
+    'price' and 'tax', which is way simpler to handle in most on change methods. Please note that you can also return a list of
+    dictionaries as the new value of a one2many, it will replace the actual rows contained in that one2many (but it will also remove the
+    previous ones).
\ No newline at end of file
diff --git a/openerp/addons/base/base_data.xml b/openerp/addons/base/base_data.xml
index 1b253b82041..7c136a5752f 100644
--- a/openerp/addons/base/base_data.xml
+++ b/openerp/addons/base/base_data.xml
@@ -69,6 +69,7 @@
             <field name="name">Administrator</field>
             <field name="company_id" ref="main_company"/>
             <field name="customer" eval="False"/>
+            <field name="email">admin@example.com</field>
         </record>
 
         <record model="res.users" id="base.user_root">
diff --git a/openerp/addons/base/base_demo.xml b/openerp/addons/base/base_demo.xml
index 65ade7ec3b9..e0013289928 100644
--- a/openerp/addons/base/base_demo.xml
+++ b/openerp/addons/base/base_demo.xml
@@ -6,6 +6,7 @@
             <field name="email">demo@example.com</field>
             <field name="company_id" ref="main_company"/>
             <field name="customer" eval="False"/>
+            <field name="email">demo@example.com</field>
         </record>
         <record id="user_demo" model="res.users">
             <field name="partner_id" ref="base.partner_demo"/>
diff --git a/openerp/addons/base/res/res_partner_view.xml b/openerp/addons/base/res/res_partner_view.xml
index bd379e3bec2..28b9e960ebe 100644
--- a/openerp/addons/base/res/res_partner_view.xml
+++ b/openerp/addons/base/res/res_partner_view.xml
@@ -147,7 +147,7 @@
 
                     <group>
                         <group>
-                            <label for="type" attrs="{'invisible': [('parent_id','=', False)]}" invisible="1"/>
+                            <label for="type" attrs="{'invisible': [('parent_id','=', False)]}"/>
                             <div attrs="{'invisible': [('parent_id','=', False)]}" invisible="1" name="div_type">
                                 <field class="oe_inline"
                                     name="type"/>