[FIX] race condition between graph view loading and search request: View.start() should return a promise if it makes an async call, so caller (ViewManager in this case) knows when the graph view is ready for action

Also inherit from View

bzr revid: xmo@openerp.com-20110620143946-tv0qx84e0y06zxu7

addons/base/static/src/js/views.js

@@ -117,8 +117,8 @@ openerp.base.ViewManager =  openerp.base.Controller.extend({
         var view = this.views[view_type];
         if (!view.controller) {
             // Lazy loading of views
-            var controllerclass = openerp.base.views.get_object(view_type);
-            var controller = new controllerclass( this, this.session, this.element_id + "_view_" + view_type, this.dataset, view.view_id);
+            var ControllerClass = openerp.base.views.get_object(view_type);
+            var controller = new ControllerClass( this, this.session, this.element_id + "_view_" + view_type, this.dataset, view.view_id);
             if (view.embedded_view) {
                 controller.set_embedded_view(view.embedded_view);
             }

addons/base_graph/static/src/js/graph.js

@@ -14,7 +14,7 @@ var COLOR_PALETTE = [
 
 QWeb.add_template('/base_graph/static/src/xml/base_graph.xml');
 openerp.base.views.add('graph', 'openerp.base_graph.GraphView');
-openerp.base_graph.GraphView = openerp.base.Controller.extend({
+openerp.base_graph.GraphView = openerp.base.View.extend({
 
     init: function(view_manager, session, element_id, dataset, view_id) {
         this._super(session, element_id);
@@ -31,7 +31,7 @@ openerp.base_graph.GraphView = openerp.base.Controller.extend({
         this.$element.hide();
     },
     start: function() {
-        this.rpc("/base_graph/graphview/load", {"model": this.model, "view_id": this.view_id}, this.on_loaded);
+        return this.rpc("/base_graph/graphview/load", {"model": this.model, "view_id": this.view_id}, this.on_loaded);
     },
     on_loaded: function(data) {
         this.all_fields = data.all_fields;

doc/source/addons.rst

@@ -110,6 +110,79 @@ initializing the addon.
         });
     }
 
+Creating new standard roles
+---------------------------
+
+Views
++++++
+
+Views are the standard high-level component in OpenERP. A view type corresponds
+to a way to display a set of data (coming from an OpenERP model).
+
+In OpenERP Web, views are standard objects registered against a dedicated
+object registry, so the :js:class:`~openerp.base.ViewManager` knows where to
+find and how to call them.
+
+Although not mandatory, it is recommended that views inherit from
+:js:class:`openerp.base.View`, which provides a view useful services to its
+children.
+
+Registering a view
+~~~~~~~~~~~~~~~~~~
+
+This is the first task to perform when creating a view, and the simplest by
+far: simply call ``openerp.base.views.add(name, object_path)`` to register
+the object of path ``object_path`` as the view for the view name ``name``.
+
+The view name is the name you gave to your new view in the OpenERP server.
+
+From that point onwards, OpenERP Web will be able to find your object and
+instantiate it.
+
+Standard view behaviors
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In the normal OpenERP Web flow, views have to implement a number of methods so
+view managers can correctly communicate with them:
+
+``start()``
+    This method will always be called after creating the view (via its
+    constructor), but not necessarily immediately.
+
+    It is called with no arguments and should handle the heavy setup work,
+    including remote call (to load the view's setup data from the server via
+    e.g. ``fields_view_get``, for instance).
+
+    ``start`` should return a `promise object`_ which *must* be resolved when
+    the view's setup is completed. This promise is used by view managers to
+    know when they can start interacting with the view.
+
+``do_hide()``
+    Called by the view manager when it wants to replace this view by an other
+    one, but wants to keep this view around to re-activate it later.
+
+    Should put the view in some sort of hibernation mode, and *must* hide its
+    DOM elements.
+
+``do_show()``
+    Called when the view manager wants to re-display the view after having
+    hidden it. The view should refresh its data display upon receiving this
+    notification
+
+``do_search(domains: Array, contexts: Array, groupbys: Array)``
+    If the view is searchable, this method is called to notify it of a search
+    against it.
+
+    It should use the provided query data to perform a search and refresh its
+    internal content (and display).
+
+    All views are searchable by default, but they can be made non-searchable
+    by setting the property ``searchable`` to ``false``.
+
+    This can be done either on the view class itself (at the same level as
+    defining e.g. the ``start`` method) or at the instance level (in the
+    class's ``init``), though you should generally set it on the class.
+
 Utility behaviors
 -----------------
 
@@ -423,3 +496,6 @@ Python
 
 .. _nose:
     http://somethingaboutorange.com/mrl/projects/nose/1.0.0/
+
+.. _promise object:
+    http://api.jquery.com/deferred.promise/