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

equal deleted inserted replaced

-:0ec436cba1a6
+:1202e6565aff
 Javascript
 ----------
 *CubicWeb* uses quite a bit of javascript in its user interface and
-ships with jquery (1.3.x) and parts of the jquery UI
+ships with jquery (1.3.x) and parts of the jquery UI library, plus a
-library, plus a number of homegrown files and also other thirparty
+number of homegrown files and also other thir party libraries.
-libraries.
 All javascript files are stored in cubicweb/web/data/. There are
 around thirty js files there. In a cube it goes to data/.
 Obviously one does not want javascript pieces to be loaded all at
 It is good practice to name cube specific js files after the name of
 the cube, like this : 'cube.mycube.js', so as to avoid name clashes.
 XXX external_resources variable (which needs love)
-CubicWeb javascript api
+CubicWeb javascript API
 ~~~~~~~~~~~~~~~~~~~~~~~
 Javascript resources are typically loaded on demand, from views. The
 request object (available as self._cw from most application objects,
 for instance views and entities objects) has a few methods to do that:
 requests.
 Important AJAX APIS
 ~~~~~~~~~~~~~~~~~~~
+* `asyncRemoteExec` and `remoteExec` are the base building blocks for
+doing arbitrary async (resp. sync) communications with the server
+* `reloadComponent` is a convenience function to replace a DOM node
+with server supplied content coming from a specific registry (this
+is quite handy to refresh the content of some boxes for instances)
 * `jQuery.fn.loadxhtml` is an important extension to jQuery which
-allow proper loading and in-place DOM update of xhtml views. It is
+allows proper loading and in-place DOM update of xhtml views. It is
 suitably augmented to trigger necessary events, and process CubicWeb
 specific elements such as the facet system, fckeditor, etc.
-* `asyncRemoteExec` and `remoteExec` are the base building blocks for
-doing arbitrary async (resp. sync) communications with the server
 A simple example with asyncRemoteExec
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In the python side, we have to extend the BaseController class. The
 error handling has to be done through the addCallback and addErrback
 methods.
 .. sourcecode: javascript
-function async_hello(name) {
+function asyncHello(name) {
 var deferred = asyncRemoteExec('say_hello', name);
 deferred.addCallback(function (response) {
 alert(response);
 });
-deferred.addErrback(function () {
+deferred.addErrback(function (error) {
 alert('something fishy happened');
 });
 }
-function sync_hello(name) {
+function syncHello(name) {
 alert( remoteExec('say_hello', name) );
 }
+Anatomy of a reloadComponent call
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`reloadComponent` allows to dynamically replace some DOM node with new
+elements. It has the following signature:
+* `compid` (mandatory) is the name of the component to be reloaded
+* `rql` (optional) will be used to generate a result set given as
+argument to the selected component
+* `registry` (optional) defaults to 'components' but can be any other
+valid registry name
+* `nodeid` (optional) defaults to compid + 'Component' but can be any
+explicitly specified DOM node id
+* `extraargs` (optional) should be a dictionary of values that will be
+given to the cell_call method of the component
+A simple reloadComponent example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The server side implementation of `reloadComponent` is the
+js_component method of the JSonController.
+The following function implements a two-steps method to delete a
+standard bookmark and refresh the UI, while keeping the UI responsive.
+.. sourcecode:: javascript
+function removeBookmark(beid) {
+d = asyncRemoteExec('delete_bookmark', beid);
+d.addCallback(function(boxcontent) {
+	    reloadComponent('bookmarks_box', '', 'boxes', 'bookmarks_box');
+document.location.hash = '#header';
+updateMessage(_("bookmark has been removed"));
+});
+}
+`reloadComponent` is called with the id of the bookmark box as
+argument, no rql expression (because the bookmarks display is actually
+independant of any dataset context), a reference to the 'boxes'
+registry (which hosts all left, right and contextual boxes) and
+finally an explicit 'bookmarks_box' nodeid argument that stipulates
+the target DOM node.
+Anatomy of a loadxhtml call
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`jQuery.fn.loadxhtml` is an important extension to jQuery which allows
+proper loading and in-place DOM update of xhtml views. The existing
+`jQuery.load`_ function does not handle xhtml, hence the addition. The
+API of loadxhtml is roughly similar to that of `jQuery.load`_.
+.. _`jQuery.load`: http://api.jquery.com/load/
+* `url` (mandatory) should be a complete url (typically referencing
+the JSonController, 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
+to a function to be called at the end of loadxhtml (more on this
+below)
+* `reqtype` (optional) specifies the request method to be used (get or
+post); if the argument is 'post', then the post method is used,
+otherwise the get method is used
+* `mode` (optional) is one of `replace` (the default) which means the
+loaded node will replace the current node content, `swap` to replace
+the current node with the loaded node, and `append` which will
+append the loaded node to the current node content
+About the `callback` option:
+* it is called with two parameters: the current node, and a list
+containing the loaded (and post-processed node)
+* whenever is returns another function, this function is called in
+turn with the same parameters as above
+This mechanism allows callback chaining.
 A simple example with loadxhtml
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Here we are concerned with the retrieval of a specific view to be
 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
+.. sourcecode:: python
 from cubicweb import typed_eid
 from cubicweb.web.views.basecontrollers import JSonController, xhtmlize
 @monkeypatch(JSonController)
 @xhtmlize
 def js_frob_status(self, eid, frobname):
 entity = self._cw.entity_from_eid(typed_eid(eid))
 return entity.view('frob', name=frobname)
-.. sourcecode: javascript
+.. sourcecode:: javascript
 function update_some_div(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
-encoded in the `params` dictionnary using the `fname` key.
+encoded in the `params` dictionary using the `fname` key.
 A more real-life example from CubicWeb
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A frequent use case of Web 2 applications is the delayed (or
 and proper use of loadxhtml.
 We present here a skeletal version of the mecanism used in CubicWeb
 and available in web/views/tabs.py, in the `LazyViewMixin` class.
-.. sourcecode: python
+.. sourcecode:: python
 def lazyview(self, vid, rql=None):
 """ a lazy version of wview """
 w = self.w
 self._cw.add_js('cubicweb.lazy.js')
 self._cw.add_onload(u"""
 jQuery('#lazy-%(vid)s').bind('%(event)s', function() {
 load_now('#lazy-%(vid)s');});"""
 % {'event': 'load_%s' % vid, 'vid': vid})
-This creates a `div` with an specific event associated to it.
+This creates a `div` with a specific event associated to it.
 The full version deals with:
 * optional parameters such as an entity eid, an rset
 * handling of browsers that do not support ajax (search engines,
 text-based browsers such as lynx, etc.)
 The javascript side is quite simple, due to loadxhtml awesomeness.
-.. sourcecode: javascript
+.. sourcecode:: javascript
 function load_now(eltsel) {
 var lazydiv = jQuery(eltsel);
 lazydiv.loadxhtml(lazydiv.attr('cubicweb:loadurl'));
 }
 Given all this, it is easy to add a small nevertheless useful feature
 to force the loading of a lazy view (for instance, a very
 computation-intensive web page could be scinded into one fast-loading
 part and a delayed part).
-In the server side, a simple call to a javascript function is
+On the server side, a simple call to a javascript function is
 sufficient.
-.. sourcecode: python
+.. sourcecode:: python
 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)
 The browser-side definition follows.
-.. sourcecode: javascript
+.. sourcecode:: javascript
 function trigger_load(divid) {
 jQuery('#lazy-' + divd).trigger('load_' + divid);
 }
-Anatomy of a lodxhtml call
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+XXX reloadComponent
-The loadxhtml extension to jQuery accept many parameters with rich
+XXX userCallback / user_callback
-semantics. Let us detail these.
-* `url` (mandatory) should be a complete url, typically based on the
-JSonController, but this is not strictly mandatory
-* `data` (optional) is a dictionnary 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
-to a function to be called at the end of loadxhtml (more on this
-below)
-* `reqtype` (optional) specifies the request method to be used (get or
-post); if the argument is 'post', then the post method is used,
-otherwise the get method is used
-* `mode` (optional) is one of `replace` (the default) which means the
-loaded node will replace the current node content, `swap` to replace
-the current node with the loaded node, and `append` which will
-append the loaded node to the current node content
-About the `callback` option:
-* it is called with two parameters: the current node, and a list
-containing the loaded (and post-processed node)
-* whenever is returns another function, this function is called in
-turn with the same parameters as above
-This mecanism allows callback chaining.
 Javascript library: overview
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * jquery.* : jquery and jquery UI library

branch	stable
changeset 5157	1202e6565aff
parent 5152	35e6878e2fd0
child 5186	f3c2cb460ad9