.. highlight:: javascript .. default-domain:: js ========== Javascript ========== Widgets ======= .. class:: openerp.Widget This is the base class for all visual components. It corresponds to an MVC view. It provides a number of services to handle a section of a page: * Rendering with QWeb * Parenting-child relations * Life-cycle management (including facilitating children destruction when a parent object is removed) * DOM insertion, via jQuery-powered insertion methods. Insertion targets can be anything the corresponding jQuery method accepts (generally selectors, DOM nodes and jQuery objects): :func:`~openerp.Widget.appendTo` Renders the widget and inserts it as the last child of the target, uses `.appendTo()`_ :func:`~openerp.Widget.prependTo` Renders the widget and inserts it as the first child of the target, uses `.prependTo()`_ :func:`~openerp.Widget.insertAfter` Renders the widget and inserts it as the preceding sibling of the target, uses `.insertAfter()`_ :func:`~openerp.Widget.insertBefore` Renders the widget and inserts it as the following sibling of the target, uses `.insertBefore()`_ * Backbone-compatible shortcuts .. _widget-dom_root: DOM Root -------- A :class:`~openerp.Widget` is responsible for a section of the page materialized by the DOM root of the widget. A widget's DOM root is available via two attributes: .. attribute:: openerp.Widget.el raw DOM element set as root to the widget .. attribute:: openerp.Widget.$el jQuery wrapper around :attr:`~openerp.Widget.el` There are two main ways to define and generate this DOM root: .. attribute:: openerp.Widget.template Should be set to the name of a :ref:`QWeb template `. If set, the template will be rendered after the widget has been initialized but before it has been started. The root element generated by the template will be set as the DOM root of the widget. .. attribute:: openerp.Widget.tagName Used if the widget has no template defined. Defaults to ``div``, will be used as the tag name to create the DOM element to set as the widget's DOM root. It is possible to further customize this generated DOM root with the following attributes: .. attribute:: openerp.Widget.id Used to generate an ``id`` attribute on the generated DOM root. .. attribute:: openerp.Widget.className Used to generate a ``class`` attribute on the generated DOM root. .. attribute:: openerp.Widget.attributes Mapping (object literal) of attribute names to attribute values. Each of these k:v pairs will be set as a DOM attribute on the generated DOM root. None of these is used in case a template is specified on the widget. The DOM root can also be defined programmatically by overridding .. function:: openerp.Widget.renderElement Renders the widget's DOM root and sets it. The default implementation will render a set template or generate an element as described above, and will call :func:`~openerp.Widget.setElement` on the result. Any override to :func:`~openerp.Widget.renderElement` which does not call its ``_super`` **must** call :func:`~openerp.Widget.setElement` with whatever it generated or the widget's behavior is undefined. .. note:: The default :func:`~openerp.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, :func:`~openerp.Widget.renderElement` should not be called repeatedly unless the widget advertizes this feature. Using a widget '''''''''''''' A widget's lifecycle has 3 main phases: * creation and initialization of the widget instance .. function:: openerp.Widget.init(parent) initialization method of widgets, synchronous, can be overridden to take more parameters from the widget's creator/parent :param parent: the current widget's parent, used to handle automatic destruction and even propagation. Can be ``null`` for the widget to have no parent. :type parent: :class:`~openerp.Widget` * DOM injection and startup, this is done by calling one of: .. function:: openerp.Widget.appendTo(element) Renders the widget and inserts it as the last child of the target, uses `.appendTo()`_ .. function:: openerp.Widget.prependTo(element) Renders the widget and inserts it as the first child of the target, uses `.prependTo()`_ .. function:: openerp.Widget.insertAfter(element) Renders the widget and inserts it as the preceding sibling of the target, uses `.insertAfter()`_ .. function:: openerp.Widget.insertBefore(element) Renders the widget and inserts it as the following sibling of the target, uses `.insertBefore()`_ All of these methods accept whatever the corresponding jQuery method accepts (CSS selectors, DOM nodes or jQuery objects). They all return a promise and are charged with three tasks: * render the widget's root element via :func:`~openerp.Widget.renderElement` * insert the widget's root element in the DOM using whichever jQuery method they match * start the widget, and return the result of starting it .. function:: openerp.Widget.start() asynchronous startup of the widget once it's been injected in the DOM, generally used to perform asynchronous RPC calls to fetch whatever remote data is necessary for the widget to do its work. Must return a deferred_ to indicate when its work is done. A widget is *not guaranteed* to work correctly until its :func:`~openerp.Widget.start` method has finished executing. The widget's parent/creator must wait for a widget to be fully started before interacting with it :returns: deferred_ object * widget destruction and cleanup .. function:: openerp.Widget.destroy() destroys the widget's children, unbinds its events and removes its root from the DOM. Automatically called when the widget's parent is destroyed, must be called explicitly if the widget has no parents or if it is removed but its parent remains. A widget being destroyed is automatically unlinked from its parent. Because a widget can be destroyed at any time, widgets also have utility methods to handle this case: .. function:: openerp.Widget.alive(deferred[, reject=false]) A significant issue with RPC and destruction is that an RPC call may take a long time to execute and return while a widget is being destroyed or after it has been destroyed, trying to execute its operations on a widget in a broken/invalid state. This is a frequent source of errors or strange behaviors. :func:`~openerp.Widget.alive` can be used to wrap an RPC call, ensuring that whatever operations should be executed when the call ends are only executed if the widget is still alive:: this.alive(this.model.query().all()).then(function (records) { // would break if executed after the widget is destroyed, wrapping // rpc in alive() prevents execution _.each(records, function (record) { self.$el.append(self.format(record)); }); }); :param deferred: a deferred_ object to wrap :param reject: by default, if the RPC call returns after the widget has been destroyed the returned deferred_ is left in limbo (neither resolved nor rejected). If ``reject`` is set to ``true``, the deferred_ will be rejected instead. :returns: deferred_ object .. function:: openerp.Widget.isDestroyed() :returns: ``true`` if the widget is being or has been destroyed, ``false`` otherwise Accessing DOM content ''''''''''''''''''''' Because a widget is only responsible for the content below its DOM root, there is a shortcut for selecting sub-sections of a widget's DOM: .. function:: openerp.Widget.$(selector) Applies the CSS selector specified as parameter to the widget's DOM root. :: this.$(selector); is functionally identical to:: this.$el.find(selector); :param String selector: CSS selector :returns: jQuery object .. note:: this helper method is compatible with ``Backbone.View.$`` Resetting the DOM root '''''''''''''''''''''' .. function:: openerp.Widget.setElement(element) Re-sets the widget's DOM root to the provided element, also handles re-setting the various aliases of the DOM root as well as unsetting and re-setting delegated events. :param Element element: a DOM element or jQuery object to set as the widget's DOM root .. note:: should be mostly compatible with `Backbone's setElement`_ DOM events handling ------------------- A widget will generally need to respond to user action within its section of the page. This entails binding events to DOM elements. To this end, :class:`~openerp.Widget` provides an shortcut: .. attribute:: openerp.Widget.events Events are a mapping of ``event selector`` (an event name and a CSS selector separated by a space) to a callback. The callback can be the name of a widget's method or a function object. In either case, the ``this`` will be set to the widget:: events: { 'click p.oe_some_class a': 'some_method', 'change input': function (e) { e.stopPropagation(); } }, The selector is used for jQuery's `event delegation`_, the callback will only be triggered for descendants of the DOM root matching the selector\ [#eventsdelegation]_. If the selector is left out (only an event name is specified), the event will be set directly on the widget's DOM root. .. function:: openerp.Widget.delegateEvents This method is in charge of binding :attr:`~openerp.Widget.events` to the DOM. It is automatically called after setting the widget's DOM root. It can be overridden to set up more complex events than the :attr:`~openerp.Widget.events` map allows, but the parent should always be called (or :attr:`~openerp.Widget.events` won't be handled correctly). .. function:: openerp.Widget.undelegateEvents This method is in charge of unbinding :attr:`~openerp.Widget.events` from the DOM root when the widget is destroyed or the DOM root is reset, in order to avoid leaving "phantom" events. It should be overridden to un-set any event set in an override of :func:`~openerp.Widget.delegateEvents`. .. note:: this behavior should be compatible with `Backbone's delegateEvents`_, apart from not accepting any argument. Subclassing Widget ------------------ :class:`~openerp.Widget` is subclassed in the standard manner (via the :func:`~openerp.Class.extend` method), and provides a number of abstract properties and concrete methods (which you may or may not want to override). Creating a subclass looks like this:: var MyWidget = openerp.Widget.extend({ // QWeb template to use when rendering the object template: "MyQWebTemplate", events: { // events binding example 'click .my-button': 'handle_click', }, init: function(parent) { this._super(parent); // insert code to execute before rendering, for object // initialization }, start: function() { var sup = this._super(); // post-rendering initialization code, at this point // allows multiplexing deferred objects return $.when( // propagate asynchronous signal from parent class sup, // return own's asynchronous signal this.rpc(/* … */)) } }); The new class can then be used in the following manner:: // Create the instance var my_widget = new MyWidget(this); // Render and insert into DOM my_widget.appendTo(".some-div"); After these two lines have executed (and any promise returned by :func:`~openerp.Widget.appendTo` has been resolved if needed), the widget is ready to be used. .. note:: the insertion methods will start the widget themselves, and will return the result of :func:`~openerp.Widget.start()`. If for some reason you do not want to call these methods, you will have to first call :func:`~openerp.Widget.render()` on the widget, then insert it into your DOM and start it. If the widget is not needed anymore (because it's transient), simply terminate it:: my_widget.destroy(); will unbind all DOM events, remove the widget's content from the DOM and destroy all widget data. .. _.appendTo(): http://api.jquery.com/appendTo/ .. _.prependTo(): http://api.jquery.com/prependTo/ .. _.insertAfter(): http://api.jquery.com/insertAfter/ .. _.insertBefore(): http://api.jquery.com/insertBefore/ .. _event delegation: http://api.jquery.com/delegate/ .. _Backbone's setElement: http://backbonejs.org/#View-setElement .. _Backbone's delegateEvents: http://backbonejs.org/#View-delegateEvents .. _deferred: http://api.jquery.com/category/deferred-object/ RPC === .. _reference/javascript/client: Web Client ========== .. [#eventsdelegation] not all DOM events are compatible with events delegation