From 542928adde6f74269f51d24e18896b2e8bb44fc2 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@openerp.com>
Date: Mon, 21 Nov 2011 15:09:08 +0100
Subject: [PATCH] [ADD] protocol to allow sidebar to query its parent view for
 context data

bzr revid: xmo@openerp.com-20111121140908-e9b3eygtt42m9bnp
---
 addons/web/static/src/js/views.js      | 33 ++++++-----
 doc/source/addons.rst                  |  3 +-
 doc/source/guides/sidebar-protocol.rst | 78 ++++++++++++++++++++++++++
 3 files changed, 99 insertions(+), 15 deletions(-)
 create mode 100644 doc/source/guides/sidebar-protocol.rst

diff --git a/addons/web/static/src/js/views.js b/addons/web/static/src/js/views.js
index 90060f47fc1..e119f2deabe 100644
--- a/addons/web/static/src/js/views.js
+++ b/addons/web/static/src/js/views.js
@@ -708,20 +708,22 @@ session.web.Sidebar = session.web.Widget.extend({
             });
             return false;
         }
-        var additional_context = {
-            active_id: ids[0],
-            active_ids: ids,
-            active_model: self.widget_parent.dataset.model
-        };
-        self.rpc("/web/action/load", {
-            action_id: item.action.id,
-            context: additional_context
-        }, function(result) {
-            result.result.context = _.extend(result.result.context || {},
-                additional_context);
-            result.result.flags = result.result.flags || {};
-            result.result.flags.new_window = true;
-            self.do_action(result.result);
+        self.widget_parent.sidebar_context().then(function (context) {
+            var additional_context = _.extend({
+                active_id: ids[0],
+                active_ids: ids,
+                active_model: self.widget_parent.dataset.model
+            }, context);
+            self.rpc("/web/action/load", {
+                action_id: item.action.id,
+                context: additional_context
+            }, function(result) {
+                result.result.context = _.extend(result.result.context || {},
+                    additional_context);
+                result.result.flags = result.result.flags || {};
+                result.result.flags.new_window = true;
+                self.do_action(result.result);
+            });
         });
     },
     do_fold: function() {
@@ -979,6 +981,9 @@ session.web.View = session.web.Widget.extend(/** @lends session.web.View# */{
         });
     },
     on_sidebar_view_log: function() {
+    },
+    sidebar_context: function () {
+        return $.Deferred().resolve({}).promise();
     }
 });
 
diff --git a/doc/source/addons.rst b/doc/source/addons.rst
index 3b749ff529c..5bd2870baa8 100644
--- a/doc/source/addons.rst
+++ b/doc/source/addons.rst
@@ -292,7 +292,8 @@ to help you get started:
 .. toctree::
     :maxdepth: 1
 
-    guides/client-action.rst
+    guides/client-action
+    guides/sidebar-protocol
 
 Utility behaviors
 -----------------
diff --git a/doc/source/guides/sidebar-protocol.rst b/doc/source/guides/sidebar-protocol.rst
new file mode 100644
index 00000000000..83626c32fc3
--- /dev/null
+++ b/doc/source/guides/sidebar-protocol.rst
@@ -0,0 +1,78 @@
+Adding a sidebar to a view
+==========================
+
+Initialization
+--------------
+
+Each view has the responsibility to create its sidebar (or not) if and only if
+the ``sidebar`` flag is set in its options.
+
+In that case, it should use the ``sidebar_id`` value (from its options) to
+initialize the sidebar at the right position in the DOM:
+
+.. code-block:: javascript
+
+    if (this.options.sidebar && this.options.sidebar_id) {
+        this.sidebar = new openerp.web.Sidebar(this, this.options.sidebar_id);
+        this.sidebar.start();
+    }
+
+Because the sidebar is an old-style widget, it must be started after being
+initialized.
+
+Sidebar communication protocol
+------------------------------
+
+In order to behave correctly, a sidebar needs informations from its parent
+view.
+
+This information is extracted via a very basic protocol consisting of a
+property and two methods:
+
+.. js:attribute:: dataset
+
+    the view's dataset, used to fetch the currently active model and provide it
+    to remote action handlers as part of the basic context
+
+.. js:function:: get_selected_ids()
+
+    Used to query the parent view for the set of currently available record
+    identifiers. Used to setup the basic context's ``active_id`` and
+    ``active_ids`` keys.
+
+    .. warning::
+
+        :js:func:`get_selected_ids` must return at least one id
+
+    :returns: an array of at least one id
+    :rtype: Array<Number>
+
+.. js:function:: sidebar_context()
+
+    Queries the view for additional context data to provide to the sidebar.
+
+    :js:class:`~openerp.base.View` provides a default NOOP implementation,
+    which simply resolves to an empty object.
+
+    :returns: a promise yielding an object on success, this object is mergeed
+              into the sidebar's own context
+    :rtype: $.Deferred<Object>
+
+Programmatic folding and unfolding
+----------------------------------
+
+The sidebar object starts folded. It provides three methods to handle its
+folding status:
+
+.. js:function:: do_toggle
+
+    Toggles the status of the sidebar
+
+.. js:function:: do_fold
+
+    Forces the sidebar closed if it's currently open
+
+.. js:function:: do_unfold
+
+    Forces the sidebar open if it's currently closed
+