# HG changeset patch
# User Julien Cristau <julien.cristau@logilab.fr>
# Date 1394184434 -3600
# Fri Mar 07 10:27:14 2014 +0100
# Node ID b87c09f853d3cfe13174fb23f58960f45ac17e2c
# Parent 48f0ff3e2a32982ab6881ff81e6561079f13762b
[doc] undocument user_callback
Related to #3567793
# User Julien Cristau <julien.cristau@logilab.fr>
# Date 1394184434 -3600
# Fri Mar 07 10:27:14 2014 +0100
# Node ID b87c09f853d3cfe13174fb23f58960f45ac17e2c
# Parent 48f0ff3e2a32982ab6881ff81e6561079f13762b
[doc] undocument user_callback
Related to #3567793
@@ -315,71 +315,10 @@
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
@@ -23,47 +23,15 @@
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