[ADD] guide for developing client actions
bzr revid: xmo@openerp.com-20110920095657-9rk9ktekn1uuf36d
This commit is contained in:
parent
26289189f5
commit
0ad6c7ea78
|
@ -282,6 +282,18 @@ view managers can correctly communicate with them:
|
|||
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.
|
||||
|
||||
Frequent development tasks
|
||||
--------------------------
|
||||
|
||||
There are a number of tasks which OpenERP Web developers do or will need to
|
||||
perform quite regularly. To make these easier, we have written a few guides
|
||||
to help you get started:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
guides/client-action.rst
|
||||
|
||||
Utility behaviors
|
||||
-----------------
|
||||
|
||||
|
|
|
@ -0,0 +1,92 @@
|
|||
Creating a new client action
|
||||
============================
|
||||
|
||||
Client actions are the client-side of OpenERP's "Server Actions": instead of
|
||||
allowing for semi-arbitrary code to be executed in the server, they allow
|
||||
for execution of client-customized code.
|
||||
|
||||
On the server side, a client action is an action of type ``ir.actions.client``,
|
||||
which has (at most) two properties: a mandatory ``tag``, which is an arbitrary
|
||||
string by which the client will identify the action, and an optional ``params``
|
||||
which is simply a map of keys and values sent to the client as-is (this way,
|
||||
client actions can be made generic and reused in multiple contexts).
|
||||
|
||||
General Structure
|
||||
-----------------
|
||||
|
||||
In the OpenERP Web code, a client action only requires two pieces of
|
||||
information:
|
||||
|
||||
* Mapping the action's ``tag`` to an OpenERP Web object
|
||||
|
||||
* The OpenERP Web object itself, which must inherit from
|
||||
:js:class:`openerp.web.Widget`
|
||||
|
||||
Our example will be the actual code for the widgets client action (a client
|
||||
action displaying a ``res.widget`` object, used in the homepage dashboard of
|
||||
the web client):
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
// Registers the object 'openerp.web_dashboard.Widget' to the client
|
||||
// action tag 'board.home.widgets'
|
||||
openerp.web.client_actions.add(
|
||||
'board.home.widgets', 'openerp.web_dashboard.Widget');
|
||||
// This object inherits from View, but only Widget is required
|
||||
openerp.web_dashboard.Widget = openerp.web.View.extend({
|
||||
template: 'HomeWidget'
|
||||
});
|
||||
|
||||
At this point, the generic ``Widget`` lifecycle takes over, the template is
|
||||
rendered, inserted in the client DOM, bound on the object's ``$element``
|
||||
property and the object is started.
|
||||
|
||||
If the client action takes parameters, these parameters are passed in as a
|
||||
second positional parameter to the constructor:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
init: function (parent, params) {
|
||||
// execute the Widget's init
|
||||
this._super(parent);
|
||||
// board.home.widgets only takes a single param, the identifier of the
|
||||
// res.widget object it should display. Store it for later
|
||||
this.widget_id = params.widget_id;
|
||||
}
|
||||
|
||||
More complex initialization (DOM manipulations, RPC requests, ...) should be
|
||||
performed in the ``start()`` method.
|
||||
|
||||
.. note::
|
||||
As required by ``Widget``'s contract, if ``start`` executes any
|
||||
asynchronous code it should return a ``$.Deferred`` so callers know when
|
||||
it's ready for interaction.
|
||||
|
||||
Although generally speaking client actions are not really interacted with.
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
start: function () {
|
||||
return $.when(
|
||||
this._super(),
|
||||
// Simply read the res.widget object this action should display
|
||||
new openerp.web.DataSet(this, 'res.widget').read_ids(
|
||||
[this.widget_id], ['title'], this.on_widget_loaded));
|
||||
}
|
||||
|
||||
The client action can then behave exactly as it wishes to within its root
|
||||
(``this.$element``). In this case, it performs further renderings once its
|
||||
widget's content is retrieved:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
on_widget_loaded: function (widgets) {
|
||||
var widget = widgets[0];
|
||||
var url = _.sprintf(
|
||||
'/web_dashboard/widgets/content?session_id=%s&widget_id=%d',
|
||||
this.session.session_id, widget.id);
|
||||
this.$element.html(QWeb.render('HomeWidget.content', {
|
||||
widget: widget,
|
||||
url: url
|
||||
}));
|
||||
}
|
Loading…
Reference in New Issue