doc/book/en/devweb/js.rst
author Aurelien Campeas <aurelien.campeas@logilab.fr>
Fri, 23 Apr 2010 17:31:46 +0200
branchstable
changeset 5394 105011657405
parent 5186 doc/book/en/development/devweb/js.rst@f3c2cb460ad9
child 5400 b7ab099b128a
permissions -rw-r--r--
[doc/book] move devweb up from development, turn development into devrepo (much better structure)
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     2
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
Javascript
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
----------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     6
*CubicWeb* uses quite a bit of javascript in its user interface and
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
     7
ships with jquery (1.3.x) and parts of the jquery UI library, plus a
5186
f3c2cb460ad9 [doc] note on pytestconf, fixlets
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5157
diff changeset
     8
number of homegrown files and also other third party libraries.
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     9
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    10
All javascript files are stored in cubicweb/web/data/. There are
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    11
around thirty js files there. In a cube it goes to data/.
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    12
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    13
Obviously one does not want javascript pieces to be loaded all at
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    14
once, hence the framework provides a number of mechanisms and
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    15
conventions to deal with javascript resources.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    16
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    17
Conventions
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    18
~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    19
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    20
It is good practice to name cube specific js files after the name of
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    21
the cube, like this : 'cube.mycube.js', so as to avoid name clashes.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    22
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    23
XXX external_resources variable (which needs love)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    24
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    25
CubicWeb javascript API
3581
669854258b90 [doc] various fixes
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 3441
diff changeset
    26
~~~~~~~~~~~~~~~~~~~~~~~
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    27
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    28
Javascript resources are typically loaded on demand, from views. The
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3581
diff changeset
    29
request object (available as self._cw from most application objects,
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    30
for instance views and entities objects) has a few methods to do that:
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    31
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    32
* `add_js(self, jsfiles, localfile=True)` which takes a sequence of
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    33
  javascript files and writes proper entries into the HTML header
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    34
  section. The localfile parameter allows to declare resources which
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    35
  are not from web/data (for instance, residing on a content delivery
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    36
  network).
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    37
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    38
* `add_onload(self, jscode)` which adds one raw javascript code
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    39
  snippet inline in the html headers. This is quite useful for setting
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    40
  up early jQuery(document).ready(...) initialisations.
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    41
4830
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    42
CubicWeb javascript events
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    43
~~~~~~~~~~~~~~~~~~~~~~~~~~
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    44
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    45
* ``server-response``: this event is triggered on HTTP responses (both
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    46
  standard and ajax). The two following extra parameters are passed
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    47
  to callbacks :
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    48
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    49
  - ``ajax``: a boolean that says if the reponse was issued by an
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    50
    ajax request
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    51
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    52
  - ``node``: the DOM node returned by the server in case of an
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    53
    ajax request, otherwise the document itself for standard HTTP
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    54
    requests.
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    55
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    56
Important AJAX APIS
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    57
~~~~~~~~~~~~~~~~~~~
4830
10e8bc190695 [javascript] fix #736185: add_onload / jQuery.bind() vs. jQuery.one()
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 4437
diff changeset
    58
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    59
* `asyncRemoteExec` and `remoteExec` are the base building blocks for
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    60
  doing arbitrary async (resp. sync) communications with the server
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    61
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    62
* `reloadComponent` is a convenience function to replace a DOM node
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    63
  with server supplied content coming from a specific registry (this
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    64
  is quite handy to refresh the content of some boxes for instances)
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    65
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    66
* `jQuery.fn.loadxhtml` is an important extension to jQuery which
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    67
  allows proper loading and in-place DOM update of xhtml views. It is
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    68
  suitably augmented to trigger necessary events, and process CubicWeb
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    69
  specific elements such as the facet system, fckeditor, etc.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    70
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    71
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    72
A simple example with asyncRemoteExec
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    73
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    74
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    75
In the python side, we have to extend the BaseController class. The
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    76
@jsonize decorator ensures that the `return value` of the method is
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    77
encoded as JSON data. By construction, the JSonController inputs
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    78
everything in JSON format.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    79
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    80
.. sourcecode: python
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    81
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    82
    from cubicweb.web.views.basecontrollers import JSonController, jsonize
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    83
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    84
    @monkeypatch(JSonController)
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    85
    @jsonize
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    86
    def js_say_hello(self, name):
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    87
        return u'hello %s' % name
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    88
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    89
In the javascript side, we do the asynchronous call. Notice how it
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    90
creates a `deferred` object. Proper treatment of the return value or
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    91
error handling has to be done through the addCallback and addErrback
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    92
methods.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    93
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    94
.. sourcecode: javascript
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    95
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
    96
    function asyncHello(name) {
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    97
        var deferred = asyncRemoteExec('say_hello', name);
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    98
        deferred.addCallback(function (response) {
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
    99
            alert(response);
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   100
        });
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   101
        deferred.addErrback(function (error) {
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   102
            alert('something fishy happened');
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   103
        });
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   104
     }
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   105
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   106
     function syncHello(name) {
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   107
         alert( remoteExec('say_hello', name) );
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   108
     }
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   109
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   110
Anatomy of a reloadComponent call
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   111
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   112
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   113
`reloadComponent` allows to dynamically replace some DOM node with new
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   114
elements. It has the following signature:
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   115
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   116
* `compid` (mandatory) is the name of the component to be reloaded
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   117
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   118
* `rql` (optional) will be used to generate a result set given as
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   119
  argument to the selected component
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   120
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   121
* `registry` (optional) defaults to 'components' but can be any other
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   122
  valid registry name
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   123
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   124
* `nodeid` (optional) defaults to compid + 'Component' but can be any
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   125
  explicitly specified DOM node id
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   126
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   127
* `extraargs` (optional) should be a dictionary of values that will be
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   128
  given to the cell_call method of the component
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   129
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   130
A simple reloadComponent example
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   131
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   132
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   133
The server side implementation of `reloadComponent` is the
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   134
js_component method of the JSonController.
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   135
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   136
The following function implements a two-steps method to delete a
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   137
standard bookmark and refresh the UI, while keeping the UI responsive.
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   138
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   139
.. sourcecode:: javascript
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   140
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   141
    function removeBookmark(beid) {
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   142
        d = asyncRemoteExec('delete_bookmark', beid);
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   143
        d.addCallback(function(boxcontent) {
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   144
	    reloadComponent('bookmarks_box', '', 'boxes', 'bookmarks_box');
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   145
            document.location.hash = '#header';
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   146
            updateMessage(_("bookmark has been removed"));
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   147
         });
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   148
    }
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   149
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   150
`reloadComponent` is called with the id of the bookmark box as
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   151
argument, no rql expression (because the bookmarks display is actually
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   152
independant of any dataset context), a reference to the 'boxes'
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   153
registry (which hosts all left, right and contextual boxes) and
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   154
finally an explicit 'bookmarks_box' nodeid argument that stipulates
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   155
the target DOM node.
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   156
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   157
Anatomy of a loadxhtml call
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   158
~~~~~~~~~~~~~~~~~~~~~~~~~~~
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   159
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   160
`jQuery.fn.loadxhtml` is an important extension to jQuery which allows
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   161
proper loading and in-place DOM update of xhtml views. The existing
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   162
`jQuery.load`_ function does not handle xhtml, hence the addition. The
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   163
API of loadxhtml is roughly similar to that of `jQuery.load`_.
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   164
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   165
.. _`jQuery.load`: http://api.jquery.com/load/
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   166
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   167
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   168
* `url` (mandatory) should be a complete url (typically referencing
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   169
  the JSonController, but this is not strictly mandatory)
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   170
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   171
* `data` (optional) is a dictionary of values given to the
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   172
  controller specified through an `url` argument; some keys may have a
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   173
  special meaning depending on the choosen controller (such as `fname`
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   174
  for the JSonController); the `callback` key, if present, must refer
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   175
  to a function to be called at the end of loadxhtml (more on this
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   176
  below)
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   177
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   178
* `reqtype` (optional) specifies the request method to be used (get or
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   179
  post); if the argument is 'post', then the post method is used,
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   180
  otherwise the get method is used
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   181
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   182
* `mode` (optional) is one of `replace` (the default) which means the
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   183
  loaded node will replace the current node content, `swap` to replace
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   184
  the current node with the loaded node, and `append` which will
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   185
  append the loaded node to the current node content
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   186
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   187
About the `callback` option:
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   188
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   189
* it is called with two parameters: the current node, and a list
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   190
  containing the loaded (and post-processed node)
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   191
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   192
* whenever is returns another function, this function is called in
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   193
  turn with the same parameters as above
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   194
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   195
This mechanism allows callback chaining.
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   196
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   197
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   198
A simple example with loadxhtml
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   199
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   200
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   201
Here we are concerned with the retrieval of a specific view to be
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   202
injected in the live DOM. The view will be of course selected
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   203
server-side using an entity eid provided by the client side.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   204
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   205
.. sourcecode:: python
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   206
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   207
    from cubicweb import typed_eid
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   208
    from cubicweb.web.views.basecontrollers import JSonController, xhtmlize
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   209
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   210
    @monkeypatch(JSonController)
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   211
    @xhtmlize
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   212
    def js_frob_status(self, eid, frobname):
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   213
        entity = self._cw.entity_from_eid(typed_eid(eid))
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   214
        return entity.view('frob', name=frobname)
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   215
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   216
.. sourcecode:: javascript
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   217
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   218
    function update_some_div(divid, eid, frobname) {
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   219
        var params = {fname:'frob_status', eid: eid, frobname:frobname};
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   220
        jQuery('#'+divid).loadxhtml(JSON_BASE_URL, params, 'post');
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   221
     }
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   222
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   223
In this example, the url argument is the base json url of a cube
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   224
instance (it should contain something like
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   225
`http://myinstance/json?`). The actual JSonController method name is
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   226
encoded in the `params` dictionary using the `fname` key.
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   227
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   228
A more real-life example from CubicWeb
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   229
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   230
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   231
A frequent use case of Web 2 applications is the delayed (or
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   232
on-demand) loading of pieces of the DOM. This is typically achieved
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   233
using some preparation of the initial DOM nodes, jQuery event handling
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   234
and proper use of loadxhtml.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   235
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   236
We present here a skeletal version of the mecanism used in CubicWeb
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   237
and available in web/views/tabs.py, in the `LazyViewMixin` class.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   238
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   239
.. sourcecode:: python
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   240
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   241
    def lazyview(self, vid, rql=None):
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   242
        """ a lazy version of wview """
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   243
        w = self.w
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   244
        self._cw.add_js('cubicweb.lazy.js')
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   245
        urlparams = {'vid' : vid, 'fname' : 'view'}
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   246
        if rql is not None:
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   247
            urlparams['rql'] = rql
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   248
        w(u'<div id="lazy-%s" cubicweb:loadurl="%s">' % (
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   249
            vid, xml_escape(self._cw.build_url('json', **urlparams))))
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   250
        w(u'</div>')
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   251
        self._cw.add_onload(u"""
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   252
            jQuery('#lazy-%(vid)s').bind('%(event)s', function() {
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   253
                   load_now('#lazy-%(vid)s');});"""
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   254
            % {'event': 'load_%s' % vid, 'vid': vid})
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   255
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   256
This creates a `div` with a specific event associated to it.
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   257
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   258
The full version deals with:
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   259
5152
35e6878e2fd0 [doc/book] adjust a bit
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5151
diff changeset
   260
* optional parameters such as an entity eid, an rset
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   261
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   262
* the ability to further reload the fragment
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   263
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   264
* the ability to display a spinning wheel while the fragment is still
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   265
  not loaded
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   266
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   267
* handling of browsers that do not support ajax (search engines,
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   268
  text-based browsers such as lynx, etc.)
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   269
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   270
The javascript side is quite simple, due to loadxhtml awesomeness.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   271
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   272
.. sourcecode:: javascript
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   273
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   274
    function load_now(eltsel) {
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   275
        var lazydiv = jQuery(eltsel);
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   276
        lazydiv.loadxhtml(lazydiv.attr('cubicweb:loadurl'));
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   277
    }
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   278
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   279
This is all significantly different of the previous `simple example`
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   280
(albeit this example actually comes from real-life code).
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   281
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   282
Notice how the `cubicweb:loadurl` is used to convey the url
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   283
information. The base of this url is similar to the global javascript
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   284
JSON_BASE_URL. According to the pattern described earlier,
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   285
the `fname` parameter refers to the standard `js_view` method of the
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   286
JSonController. This method renders an arbitrary view provided a view
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   287
id (or `vid`) is provided, and most likely an rql expression yielding
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   288
a result set against which a proper view instance will be selected.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   289
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   290
The `cubicweb:loadurl` is one of the 29 attributes extensions to XHTML
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   291
in a specific cubicweb namespace. It is a means to pass information
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   292
without breaking HTML nor XHTML compliance and without resorting to
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   293
ungodly hacks.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   294
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   295
Given all this, it is easy to add a small nevertheless useful feature
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   296
to force the loading of a lazy view (for instance, a very
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   297
computation-intensive web page could be scinded into one fast-loading
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   298
part and a delayed part).
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   299
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   300
On the server side, a simple call to a javascript function is
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   301
sufficient.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   302
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   303
.. sourcecode:: python
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   304
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   305
    def forceview(self, vid):
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   306
        """trigger an event that will force immediate loading of the view
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   307
        on dom readyness
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   308
        """
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   309
        self._cw.add_onload("trigger_load('%s');" % vid)
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   310
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   311
The browser-side definition follows.
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   312
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   313
.. sourcecode:: javascript
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   314
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   315
    function trigger_load(divid) {
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   316
        jQuery('#lazy-' + divd).trigger('load_' + divid);
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   317
    }
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   318
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   319
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   320
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   321
5157
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   322
XXX reloadComponent
1202e6565aff [doc/book] talk about reloadComponent, misc tweaks and notes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5152
diff changeset
   323
XXX userCallback / user_callback
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   324
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   325
Javascript library: overview
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   326
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   327
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   328
* jquery.* : jquery and jquery UI library
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   329
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   330
* cubicweb.ajax.js : concentrates all ajax related facilities (it
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   331
  extends jQuery with the loahxhtml function, provides a handfull of
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   332
  high-level ajaxy operations like asyncRemoteExec, reloadComponent,
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   333
  replacePageChunk, getDomFromResponse)
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   334
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   335
* cubicweb.python.js : adds a number of practical extension to stdanrd
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   336
  javascript objects (on Date, Array, String, some list and dictionary
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   337
  operations), and a pythonesque way to build classes. Defines a
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   338
  CubicWeb namespace.
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   339
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   340
* cubicweb.htmlhelpers.js : a small bag of convenience functions used
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   341
  in various other cubicweb javascript resources (baseuri, progress
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   342
  cursor handling, popup login box, html2dom function, etc.)
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   343
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   344
* cubicweb.widgets.js : provides a widget namespace and constructors
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   345
  and helpers for various widgets (mainly facets and timeline)
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   346
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   347
* cubicweb.edition.js : used by edition forms
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   348
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   349
* cubicweb.preferences.js : used by the preference form
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   350
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   351
* cubicweb.facets.js : used by the facets mechanism
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
   352
5151
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   353
There is also javascript support for massmailing, gmap (google maps),
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   354
fckcwconfig (fck editor), timeline, calendar, goa (CubicWeb over
2f70fa8b6854 [doc/book] expand the js chapter with an ajax story
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4830
diff changeset
   355
AppEngine), flot (charts drawing), tabs and bookmarks.