cubicweb: comparison doc/book/en/devweb/js.rst

equal deleted inserted replaced

-:7070250bf50d
+:0a927fe4541b
 A simple example with asyncRemoteExec
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In the python side, we have to extend the ``BaseController``
+On the python side, we have to define an
-class. The ``@jsonize`` decorator ensures that the return value of the
+:class:`cubicweb.web.views.ajaxcontroller.AjaxFunction` object. The
-method is encoded as JSON data. By construction, the JSonController
+simplest way to do that is to use the
-inputs everything in JSON format.
+:func:`cubicweb.web.views.ajaxcontroller.ajaxfunc` decorator (for more
+details on this, refer to :ref:`ajax`).
 .. sourcecode: python
-from cubicweb.web.views.basecontrollers import JSonController, jsonize
+from cubicweb.web.views.ajaxcontroller import ajaxfunc
-@monkeypatch(JSonController)
+# serialize output to json to get it back easily on the javascript side
-@jsonize
+@ajaxfunc(output_type='json')
 def js_say_hello(self, name):
 return u'hello %s' % name
-In the javascript side, we do the asynchronous call. Notice how it
+On the javascript side, we do the asynchronous call. Notice how it
 creates a `deferred` object. Proper treatment of the return value or
 error handling has to be done through the addCallback and addErrback
 methods.
 .. sourcecode: javascript
 A simple reloadComponent example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The server side implementation of `reloadComponent` is the
-js_component method of the JSonController.
+:func:`cubicweb.web.views.ajaxcontroller.component` *AjaxFunction* appobject.
 The following function implements a two-steps method to delete a
 standard bookmark and refresh the UI, while keeping the UI responsive.
 .. sourcecode:: javascript
 .. _`jQuery.load`: http://api.jquery.com/load/
 * `url` (mandatory) should be a complete url (typically referencing
-the JSonController, but this is not strictly mandatory)
+the :class:`cubicweb.web.views.ajaxcontroller.AjaxController`,
+but this is not strictly mandatory)
 * `data` (optional) is a dictionary of values given to the
 controller specified through an `url` argument; some keys may have a
 special meaning depending on the choosen controller (such as `fname`
 for the JSonController); the `callback` key, if present, must refer
 injected in the live DOM. The view will be of course selected
 server-side using an entity eid provided by the client side.
 .. sourcecode:: python
-from cubicweb import typed_eid
+from cubicweb.web.views.ajaxcontroller import ajaxfunc
-from cubicweb.web.views.basecontrollers import JSonController, xhtmlize
+@ajaxfunc(output_type='xhtml')
-@monkeypatch(JSonController)
-@xhtmlize
 def js_frob_status(self, eid, frobname):
-entity = self._cw.entity_from_eid(typed_eid(eid))
+entity = self._cw.entity_from_eid(eid)
 return entity.view('frob', name=frobname)
 .. sourcecode:: javascript
-function update_some_div(divid, eid, frobname) {
+function updateSomeDiv(divid, eid, frobname) {
 var params = {fname:'frob_status', eid: eid, frobname:frobname};
 jQuery('#'+divid).loadxhtml(JSON_BASE_URL, params, 'post');
 }
 In this example, the url argument is the base json url of a cube
 instance (it should contain something like
-`http://myinstance/json?`). The actual JSonController method name is
+`http://myinstance/ajax?`). The actual AjaxController method name is
 encoded in the `params` dictionary using the `fname` key.
 A more real-life example
 ~~~~~~~~~~~~~~~~~~~~~~~~
 w(u'<div id="lazy-%s" cubicweb:loadurl="%s">' % (
 vid, xml_escape(self._cw.build_url('json', **urlparams))))
 w(u'</div>')
 self._cw.add_onload(u"""
 jQuery('#lazy-%(vid)s').bind('%(event)s', function() {
-load_now('#lazy-%(vid)s');});"""
+loadNow('#lazy-%(vid)s');});"""
 % {'event': 'load_%s' % vid, 'vid': vid})
 This creates a `div` with a specific event associated to it.
 The full version deals with:
 The javascript side is quite simple, due to loadxhtml awesomeness.
 .. sourcecode:: javascript
-function load_now(eltsel) {
+function loadNow(eltsel) {
 var lazydiv = jQuery(eltsel);
 lazydiv.loadxhtml(lazydiv.attr('cubicweb:loadurl'));
 }
 This is all significantly different of the previous `simple example`
 def forceview(self, vid):
 """trigger an event that will force immediate loading of the view
 on dom readyness
 """
-self._cw.add_onload("trigger_load('%s');" % vid)
+self._cw.add_onload("triggerLoad('%s');" % vid)
 The browser-side definition follows.
 .. sourcecode:: javascript
-function trigger_load(divid) {
+function triggerLoad(divid) {
 jQuery('#lazy-' + divd).trigger('load_' + divid);
 }
-.. XXX userCallback / user_callback
+python/ajax dynamic callbacks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+CubicWeb provides a way to dynamically register a function and make it
+callable from the javascript side. The typical use case for this is a
+situation where you have everything at hand to implement an action
+(whether it be performing a RQL query or executing a few python
+statements) that you'd like to defer to a user click in the web
+interface.  In other words, generate an HTML ``<a href=...`` link that
+would execute your few lines of code.
+The trick is to create a python function and store this function in
+the user's session data. You will then be able to access it later.
+While this might sound hard to implement, it's actually quite easy
+thanks to the ``_cw.user_callback()``. This method takes a function,
+registers it and returns a javascript instruction suitable for
+``href`` or ``onclick`` usage. The call is then performed
+asynchronously.
+Here's a simplified example taken from the vcreview_ cube that will
+generate a link to change an entity state directly without the
+standard intermediate *comment / validate* step:
+.. sourcecode:: python
+def entity_call(self, entity):
+# [...]
+def change_state(req, eid):
+entity = req.entity_from_eid(eid)
+entity.cw_adapt_to('IWorkflowable').fire_transition('done')
+url = self._cw.user_callback(change_state, (entity.eid,))
+self.w(tags.input(type='button', onclick=url, value=self._cw._('mark as done')))
+The ``change_state`` callback function is registered with
+``self._cw.user_callback()`` which returns the ``url`` value directly
+used for the ``onclick`` attribute of the button. On the javascript
+side, the ``userCallback()`` function is used but you most probably
+won't have to bother with it.
+Of course, when dealing with session data, the question of session
+cleaning pops up immediately. If you use ``user_callback()``, the
+registered function will be deleted automatically at some point
+as any other session data. If you want your function to be deleted once
+the web page is unloaded or when the user has clicked once on your link, then
+``_cw.register_onetime_callback()`` is what you need. It behaves as
+``_cw.user_callback()`` but stores the function in page data instead
+of global session data.
+.. Warning::
+Be careful when registering functions with closures, keep in mind that
+enclosed data will be kept in memory until the session gets cleared. Also,
+if you keep entities or any object referecing the current ``req`` object, you
+might have problems reusing them later because the underlying session
+might have been closed at the time the callback gets executed.
+.. _vcreview: http://www.cubicweb.org/project/cubicweb-vcreview
 Javascript library: overview
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * jquery.* : jquery and jquery UI library
 API
 ~~~
 .. toctree::
 :maxdepth: 1
 js_api/index
 Testing javascript
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
 You with the ``cubicweb.qunit.QUnitTestCase`` can include standard Qunit tests
 inside the python unittest run . You simply have to define a new class that
 inherit from ``QUnitTestCase`` and register your javascript test file in the
 ``all_js_tests`` lclass attribut. This  ``all_js_tests`` is a sequence a

changeset 8128	0a927fe4541b
parent 5742	74c19dac29cf
child 8987	d9195dce3a5b