From 923e947917c7082b9e583633a45e179af84cb1d2 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@openerp.com>
Date: Wed, 29 Feb 2012 15:17:54 +0100
Subject: [PATCH] [ADD] small Model examples

bzr revid: xmo@openerp.com-20120229141754-2mr8b6sm6es2j4wb
---
 doc/source/changelog-6.2.rst |  4 ++--
 doc/source/rpc.rst           | 38 ++++++++++++++++++++++++++++++++++--
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/doc/source/changelog-6.2.rst b/doc/source/changelog-6.2.rst
index 2b492472f0f..5facb47ac14 100644
--- a/doc/source/changelog-6.2.rst
+++ b/doc/source/changelog-6.2.rst
@@ -31,7 +31,7 @@ API simplification
     than shortcuts, or are there due to domain and context evaluation
     issues in 6.1.
 
-    The shortcuts really add little value, and OpenERP Web embeds a
-    restricted Python evaluator (in javascript) meaning most of the
+    The shortcuts really add little value, and OpenERP Web 6.2 embeds
+    a restricted Python evaluator (in javascript) meaning most of the
     context and domain parsing & evaluation can be moved to the
     javascript code and does not require cooperative RPC bridging.
diff --git a/doc/source/rpc.rst b/doc/source/rpc.rst
index 8ed72e8520b..ea426916932 100644
--- a/doc/source/rpc.rst
+++ b/doc/source/rpc.rst
@@ -27,19 +27,53 @@ class maps ontwo the OpenERP server objects via two primary methods,
 :js:func:`~openerp.web.Model.query`.
 
 :js:func:`~openerp.web.Model.call` is a direct mapping to the
-corresponding method of the OpenERP server object.
+corresponding method of the OpenERP server object. Its usage is
+similar to that of the OpenERP Model API, with three differences:
+
+* The interface is :doc:`asynchronous </async>`, so instead of
+  returning results directly RPC method calls will return
+  :js:class:`Deferred` instances, which will themselves resolve to the
+  result of the matching RPC call.
+
+* Because ECMAScript 3/Javascript 1.5 doesnt feature any equivalent to
+  ``__getattr__`` or ``method_missing``, there needs to be an explicit
+  method to dispatch RPC methods.
+
+* No notion of pooler, the model proxy is instantiated where needed,
+  not fetched from an other (somewhat global) object
+
+.. code-block:: javascript
+
+    var Users = new Model('res.users');
+
+    Users.call('change_password', ['oldpassword', 'newpassword'],
+                      {context: some_context}).then(function (result) {
+        // do something with change_password result
+    });
 
 :js:func:`~openerp.web.Model.query` is a shortcut for a builder-style
 iterface to searches (``search`` + ``read`` in OpenERP RPC terms). It
 returns a :js:class:`~openerp.web.Query` object which is immutable but
 allows building new :js:class:`~openerp.web.Query` instances from the
-first one, adding new properties or modifiying the parent object's.
+first one, adding new properties or modifiying the parent object's:
+
+.. code-block:: javascript
+
+    Users.query(['name', 'login', 'user_email', 'signature'])
+         .filter([['active', '=', true], ['company_id', '=', main_company]])
+         .limit(15)
+         .all().then(function (users) {
+        // do work with users records
+    });
 
 The query is only actually performed when calling one of the query
 serialization methods, :js:func:`~openerp.web.Query.all` and
 :js:func:`~openerp.web.Query.first`. These methods will perform a new
 RPC query every time they are called.
 
+For that reason, it's actually possible to keep "intermediate" queries
+around and use them differently/add new specifications on them.
+
 .. js:class:: openerp.web.Model(name)
 
     .. js:attribute:: openerp.web.Model.name