320 python/ajax dynamic callbacks

   321 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   322 

   323 CubicWeb provides a way to dynamically register a function and make it

   324 callable from the javascript side. The typical use case for this is a

   325 situation where you have everything at hand to implement an action

   326 (whether it be performing a RQL query or executing a few python

   327 statements) that you'd like to defer to a user click in the web

   328 interface.  In other words, generate an HTML ``<a href=...`` link that

   329 would execute your few lines of code.

   330 

   331 The trick is to create a python function and store this function in

   332 the user's session data. You will then be able to access it later.

   333 While this might sound hard to implement, it's actually quite easy

   334 thanks to the ``_cw.user_callback()``. This method takes a function,

   335 registers it and returns a javascript instruction suitable for

   336 ``href`` or ``onclick`` usage. The call is then performed

   337 asynchronously.

   338 

   339 Here's a simplified example taken from the vcreview_ cube that will

   340 generate a link to change an entity state directly without the

   341 standard intermediate *comment / validate* step:

   342 

   343 .. sourcecode:: python

   344 

   345     def entity_call(self, entity):

   346         # [...]

   347         def change_state(req, eid):

   348             entity = req.entity_from_eid(eid)

   349             entity.cw_adapt_to('IWorkflowable').fire_transition('done')

   350         url = self._cw.user_callback(change_state, (entity.eid,))

   351         self.w(tags.input(type='button', onclick=url, value=self._cw._('mark as done')))

   352 

   353 

   354 The ``change_state`` callback function is registered with

   355 ``self._cw.user_callback()`` which returns the ``url`` value directly

   356 used for the ``onclick`` attribute of the button. On the javascript

   357 side, the ``userCallback()`` function is used but you most probably

   358 won't have to bother with it.

   359 

   360 Of course, when dealing with session data, the question of session

   361 cleaning pops up immediately. If you use ``user_callback()``, the

   362 registered function will be deleted automatically at some point

   363 as any other session data. If you want your function to be deleted once

   364 the web page is unloaded or when the user has clicked once on your link, then

   365 ``_cw.register_onetime_callback()`` is what you need. It behaves as

   366 ``_cw.user_callback()`` but stores the function in page data instead

   367 of global session data.

   368 

   369 

   370 .. Warning::

   371 

   372   Be careful when registering functions with closures, keep in mind that

   373   enclosed data will be kept in memory until the session gets cleared. Also,

   374   if you keep entities or any object referecing the current ``req`` object, you

   375   might have problems reusing them later because the underlying session

   376   might have been closed at the time the callback gets executed.

   377 

   378 

   379 .. _vcreview: http://www.cubicweb.org/project/cubicweb-vcreview

   380