[REF] web: update widget to new guidelines

- make delegate/undelegate events private
- remove $el before start
- make replaceElement private
- remove one _ from __render_and_insert... method
- update documentation
- remove make and improve make_descriptive (also, it is private)
- ...

1 files changed, 18 insertions, 13 deletions

diff --git a/addons/web/static/src/js/views/basic/basic_renderer.js b/addons/web/static/src/js/views/basic/basic_renderer.js
index 21fabbc2274..a6d5172bfe1 100644
--- a/addons/web/static/src/js/views/basic/basic_renderer.js
+++ b/addons/web/static/src/js/views/basic/basic_renderer.js
@@ -483,15 +483,18 @@ var BasicRenderer = AbstractRenderer.extend({
      * rendering of the widget will be started and the associated deferred will
      * be added to the 'defs' attribute. This is supposed to be created and
      * deleted by the calling code if necessary.
-     * Note: for this implementation to work, AbstractField willStart methods
-     * *must* be synchronous.
+     *
+     * Note: we always return a $el.  If the field widget is asynchronous, this
+     * $el will be replaced by the real $el, whenever the widget is ready (start
+     * method is done).  This means that this is not the correct place to make
+     * changes on the widget $el.  For this, @see _postProcessField method
      *
      * @private
      * @param {Object} node
      * @param {Object} record
      * @param {Object} [options]
      * @param {Object} [modifiersOptions]
-     * @returns {AbstractField}
+     * @returns {jQueryElement}
      */
     _renderFieldWidget: function (node, record, options, modifiersOptions) {
         var fieldName = node.attrs.name;
@@ -516,8 +519,10 @@ var BasicRenderer = AbstractRenderer.extend({
         widget.__node = node; // TODO get rid of this if possible one day
 
         // Prepare widget rendering and save the related deferred
-        var def = widget.__widgetRenderAndInsert(function () {});
-        if (def.state() === 'pending') {
+        var def = widget._widgetRenderAndInsert(function () {});
+        var async = def.state() === 'pending';
+        var $el = async ? $('<div>') : widget.$el;
+        if (async) {
             this.defs.push(def);
         }
 
@@ -526,6 +531,9 @@ var BasicRenderer = AbstractRenderer.extend({
         // associated to new widget)
         var self = this;
         def.then(function () {
+            if (async) {
+                $el.replaceWith(widget.$el);
+            }
             self._registerModifiers(node, record, widget, _.extend({
                 callback: function (element, modifiers, record) {
                     element.$el.toggleClass('o_field_empty', !!(
@@ -538,7 +546,7 @@ var BasicRenderer = AbstractRenderer.extend({
             self._postProcessField(widget, node);
         });
 
-        return widget;
+        return $el;
     },
     /**
      * Renders the nocontent helper.
@@ -583,7 +591,7 @@ var BasicRenderer = AbstractRenderer.extend({
         var widget = new Widget(this, record);
 
         // Prepare widget rendering and save the related deferred
-        var def = widget.__widgetRenderAndInsert(function () {});
+        var def = widget._widgetRenderAndInsert(function () {});
         if (def.state() === 'pending') {
             this.defs.push(def);
         }
@@ -602,20 +610,17 @@ var BasicRenderer = AbstractRenderer.extend({
      * @private
      * @param {Widget} widget
      * @param {Object} record
-     * @returns {AbstractField}
      */
     _rerenderFieldWidget: function (widget, record) {
         // Render the new field widget
-        var newWidget = this._renderFieldWidget(widget.__node, record);
-        widget.$el.replaceWith(newWidget.$el);
+        var $el = this._renderFieldWidget(widget.__node, record);
+        widget.$el.replaceWith($el);
 
         // Destroy the old widget and position the new one at the old one's
         var oldIndex = this._destroyFieldWidget(record.id, widget);
         var recordWidgets = this.allFieldWidgets[record.id];
+        var newWidget = recordWidgets.pop();
         recordWidgets.splice(oldIndex, 0, newWidget);
-        recordWidgets.pop();
-
-        return newWidget;
     },
     /**
      * Unregisters an element of the modifiers data associated to the given