A :js:class:`~openerp.web.Widget` is responsible for a section of the
page materialized by the DOM root of the widget. The DOM root is
available via the :js:attr:`~openerp.web.Widget.el` and
-:js:attr:`~openerp.web.Widget.$el` attributes, which are respectively
-the raw DOM Element and the jQuery wrapper around the DOM element.
-
-.. note::
-
- both attributes are compatible with Backbone's equivalent, there
- is also the :js:attr:`~openerp.web.Widget.$element` attribute
- which aliases to :js:attr:`~openerp.web.Widget.$el` and remains
- for backwards compatiblity reasons.
+:js:attr:`~openerp.web.Widget.$element` attributes, which are
+respectively the raw DOM Element and the jQuery wrapper around the DOM
+element.
There are two main ways to define and generate this DOM root:
Any override to :js:func:`~openerp.web.Widget.renderElement` which
does not call its ``_super`` **must** call
:js:func:`~openerp.web.Widget.setElement` with whatever it
- generated or the widget's behavior is undefined.
+ generated or the widget's behavior is undefined.r
+
+ .. note::
+
+ The default :js:func:`~openerp.web.Widget.renderElement` can
+ be called repeatedly, it will *replace* the previous DOM root
+ (using ``replaceWith``). However, this requires that the
+ widget correctly sets and unsets its events (and children
+ widgets). Generally,
+ :js:func:`~openerp.web.Widget.renderElement` should not be
+ called repeatedly unless the widget advertizes this feature.
Accessing DOM content
~~~~~~~~~~~~~~~~~~~~~