[doc] undocument user_callback

1      function triggerLoad(divid) {
2          jQuery('#lazy-' + divd).trigger('load_' + divid);
3      }
4 
5 
6 -python/ajax dynamic callbacks
7 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8 -
9 -CubicWeb provides a way to dynamically register a function and make it
10 -callable from the javascript side. The typical use case for this is a
11 -situation where you have everything at hand to implement an action
12 -(whether it be performing a RQL query or executing a few python
13 -statements) that you'd like to defer to a user click in the web
14 -interface.  In other words, generate an HTML ``<a href=...`` link that
15 -would execute your few lines of code.
16 -
17 -The trick is to create a python function and store this function in
18 -the user's session data. You will then be able to access it later.
19 -While this might sound hard to implement, it's actually quite easy
20 -thanks to the ``_cw.user_callback()``. This method takes a function,
21 -registers it and returns a javascript instruction suitable for
22 -``href`` or ``onclick`` usage. The call is then performed
23 -asynchronously.
24 -
25 -Here's a simplified example taken from the vcreview_ cube that will
26 -generate a link to change an entity state directly without the
27 -standard intermediate *comment / validate* step:
28 -
29 -.. sourcecode:: python
30 -
31 -    def entity_call(self, entity):
32 -        # [...]
33 -        def change_state(req, eid):
34 -            entity = req.entity_from_eid(eid)
35 -            entity.cw_adapt_to('IWorkflowable').fire_transition('done')
36 -        url = self._cw.user_callback(change_state, (entity.eid,))
37 -        self.w(tags.input(type='button', onclick=url, value=self._cw._('mark as done')))
38 -
39 -
40 -The ``change_state`` callback function is registered with
41 -``self._cw.user_callback()`` which returns the ``url`` value directly
42 -used for the ``onclick`` attribute of the button. On the javascript
43 -side, the ``userCallback()`` function is used but you most probably
44 -won't have to bother with it.
45 -
46 -Of course, when dealing with session data, the question of session
47 -cleaning pops up immediately. If you use ``user_callback()``, the
48 -registered function will be deleted automatically at some point
49 -as any other session data. If you want your function to be deleted once
50 -the web page is unloaded or when the user has clicked once on your link, then
51 -``_cw.register_onetime_callback()`` is what you need. It behaves as
52 -``_cw.user_callback()`` but stores the function in page data instead
53 -of global session data.
54 -
55 -
56 -.. Warning::
57 -
58 -  Be careful when registering functions with closures, keep in mind that
59 -  enclosed data will be kept in memory until the session gets cleared. Also,
60 -  if you keep entities or any object referecing the current ``req`` object, you
61 -  might have problems reusing them later because the underlying session
62 -  might have been closed at the time the callback gets executed.
63 -
64 -
65 -.. _vcreview: http://www.cubicweb.org/project/cubicweb-vcreview
66 -
67  Javascript library: overview
68  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69 
70  * jquery.* : jquery and jquery UI library
71 

72  be displayed. The 'submenu' attribute is only used for actions in the
73  action box.
74 
75  The most important method from a developper point of view in the
76  :meth:'Action.url' method, which returns a URL on which the navigation
77 -should directed to perform the action.  There are two common ways of
78 -writing that method:
79 -
80 -* do nothing special and simply return a URL to the current rset with
81 -  a special view (with `self._cw.build_url(...)` for instance)
82 -
83 -* define an inner function `callback_func(req, *args)` which will do
84 -  the work and call it through `self._cw.user_callback(callback_func,
85 -  args, msg)`: this method will return a URL which calls the inner
86 -  function, and displays the message in the web interface when the
87 -  callback has completed (and report any exception occuring in the
88 -  callback too)
89 -
90 -Many examples of the first approach are available in :mod:`cubicweb.web.views.actions`.
91 -
92 -Here is an example of the second approach:
93 -
94 -.. sourcecode:: python
95 +should be directed to perform the action.  The common way of
96 +writing that method is to simply return a URL to the current rset with a
97 +special view (with `self._cw.build_url(...)` for instance) 
98 
99 - from cubicweb.web import action
100 - class SomeAction(action.Action):
101 -     __regid__ = 'mycube_some_action'
102 -     title = _(some action)
103 -     __select__ = action.Action.__select__ & is_instance('TargetEntity')
104 - 
105 -     def url(self):
106 -         if self.cw_row is None:
107 -             eids = [row[0] for row in self.cw_rset]
108 -         else:
109 -             eids = (self.cw_rset[self.cw_row][self.cw_col or 0],)
110 -         def do_action(req, eids):
111 -             for eid in eids:
112 -                 entity = req.entity_from_eid(eid, 'TargetEntity')
113 -                 entity.perform_action()
114 -         msg = self._cw._('some_action performed')
115 -         return self._cw.user_callback(do_action, (eids,), msg)
116 -
117 +Many examples are available in :mod:`cubicweb.web.views.actions`.
118  """
119 
120  __docformat__ = "restructuredtext en"
121  _ = unicode
122