[imp] Mainly documentation and small modifications to Widget.

bzr revid: nicolas.vanhoren@openerp.com-20110728152456-2mgkbcqhm7d0zz3m

1 files changed, 55 insertions, 19 deletions

diff --git a/addons/base/static/src/js/controller.js b/addons/base/static/src/js/controller.js
index 2ed00f29ff9..7abf35c10ed 100644
--- a/addons/base/static/src/js/controller.js
+++ b/addons/base/static/src/js/controller.js
@@ -149,8 +149,10 @@ instance.base.generate_null_object_class = function(claz, add) {
 // OLD 
 // --------------------------------------------------------
 /**
- * Class for OpenERP session aware classes to extend. Also provides callback mechanism and logging
- * facility.
+ * Utility class that any class is allowed to extend to easy common manipulations.
+ * 
+ * It provides rpc calls, callback on all methods preceded by "on_" or "do_" and a
+ * logging facility.
  */
 instance.base.SessionAware = instance.base.Class.extend({
     init: function(session) {
@@ -214,6 +216,18 @@ instance.base.SessionAware = instance.base.Class.extend({
     }
 });
 
+/**
+ * Base class for all visual components. Provides a lot of functionalities helpful
+ * for the management of a part of the DOM.
+ * 
+ * Widget handles:
+ * - Rendering with QWeb.
+ * - Life-cycle management and parenting (when a parent is destroyed, all its children are
+ *     destroyed too).
+ * - Insertion in DOM.
+ * 
+ * Widget also extends SessionAware for ease of use.
+ */
 instance.base.Widget = instance.base.SessionAware.extend({
     /**
      * The name of the QWeb template that will be used for rendering. Must be
@@ -231,16 +245,24 @@ instance.base.Widget = instance.base.SessionAware.extend({
     identifier_prefix: 'generic-identifier',
     /**
      * @constructs
-     * rpc operations, event binding and callback calling should be done in
-     * start() instead of init so that events can be hooked in between.
+     * Construct the widget and set its parent if a parent is given.
+     * 
+     * @param {Widget} parent Binds the current instance to the given Widget instance.
+     * When that widget is destroyed by calling stop(), the current instance will be
+     * destroyed too. Can be null.
+     * @param {String} element_id Deprecated. Sets the element_id. Only useful when you want
+     * to bind the current Widget to an already existing part of the DOM, which is not compatible
+     * with the DOM insertion methods provided by the current implementation of Widget. So
+     * for new components this argument should not be provided any more.
      */
     init: function(parent, element_id) {
         this._super((parent || {}).session);
-        //TODO niv: get away the possibility to specify an id
         this.element_id = element_id;
         this.element_id = this.element_id || _.uniqueId(this.identifier_prefix);
         
-        this.$element = $('#' + element_id);
+        var tmp = document.getElementById(this.element_id);
+        this.$element = tmp ? $(tmp) : undefined;
+        // TODO niv: wtf??
         if (element_id) {
             instance.screen[element_id] = this;
         }
@@ -252,8 +274,8 @@ instance.base.Widget = instance.base.SessionAware.extend({
         }
     },
     /**
-     * Render the widget. This.template must be defined.
-     * The content of the current object is passed as context to the template.
+     * Renders the widget using QWeb, `this.template` must be defined.
+     * The context given to QWeb contains the "widget" key that references `this`.
      * 
      * @param {object} additional Additional context arguments to pass to the template.
      */
@@ -261,19 +283,24 @@ instance.base.Widget = instance.base.SessionAware.extend({
         return QWeb.render(this.template, _.extend({widget: this}, additional || {}));
     },
     /**
-     * Event binding, rpc and callback calling required to initialize the
-     * object should happen here
-     *
-     * Returns a promise object letting callers (subclasses and direct callers)
-     * know when this component is done starting
+     * Method called after rendering. Mostly used to bind actions, perform asynchronous
+     * calls, etc...
+     * 
+     * By convention, the method should return a promise to inform the caller when
+     * this widget has been initialized.
      *
      * @returns {jQuery.Deferred}
      */
     start: function() {
-        var tmp = document.getElementById(this.element_id);
-        this.$element = tmp ? $(tmp) : null;
+        if (!this.$element) {
+            var tmp = document.getElementById(this.element_id);
+            this.$element = tmp ? $(tmp) : undefined;
+        }
         return $.Deferred().done().promise();
     },
+    /**
+     * Destroys the current widget, also destory all its children before destroying itself.
+     */
     stop: function() {
         _.each(_.clone(this.widget_children), function(el) {
             el.stop();
@@ -286,14 +313,23 @@ instance.base.Widget = instance.base.SessionAware.extend({
         }
         this.widget_parent = null;
     },
+    /**
+     * Inform the action manager to do an action. Of course, this suppose that
+     * the action manager can be found amongst the ancestors of the current widget.
+     * If that's not the case this method will simply return `false`.
+     */
     do_action: function(action, on_finished) {
-        return this.widget_parent.do_action(action, on_finished);
+        if (this.widget_parent) {
+            return this.widget_parent.do_action(action, on_finished);
+        }
+        return false;
     }
 });
 
-/*
- * For retro compatibility only, the only difference with is that render takes
- * directly this instead of 
+/**
+ * @deprecated
+ * For retro compatibility only, the only difference with is that render() uses
+ * directly this instead of a {widget: this}.
  */
 instance.base.OldWidget = instance.base.Widget.extend({
     render: function (additional) {