doc/book/en/devweb/controllers.rst
author Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
Tue, 27 Sep 2011 18:47:11 +0200
changeset 7876 df15d194a134
parent 7529 2fdc310be7cd
child 8128 0a927fe4541b
permissions -rw-r--r--
[views] implement json / jsonp export views (closes #1942658) Json export views are based on the same model as CSV export views. There are two distinct views : - *jsonexport* : direct conversion of the result set into json - *ejsonexport* : convert entities into json The JSONP parameter is named ``callback`` (same as on geonames, dbepdia and a lot of sites) An optional `_indent` request parameter can be passed to pretty print the results.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
     1
.. _controllers:
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
     2
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
Controllers
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
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     6
Overview
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     7
++++++++
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     8
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     9
Controllers are responsible for taking action upon user requests
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    10
(loosely following the terminology of the MVC meta pattern).
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    11
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    12
The following controllers are provided out-of-the box in CubicWeb. We
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    13
list them by category. They are all defined in
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    14
(:mod:`cubicweb.web.views.basecontrollers`).
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    15
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    16
`Browsing`:
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    17
6347
ef47a2100c66 exception: specify expected parameter in NoSelectableException
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 5459
diff changeset
    18
* the View controller is associated with most browsing actions within a
7529
2fdc310be7cd [book] add autoload section from code and fix sphinx warnings
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6347
diff changeset
    19
  CubicWeb application: it always instantiates a
2fdc310be7cd [book] add autoload section from code and fix sphinx warnings
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6347
diff changeset
    20
  :ref:`the_main_template_layout` and lets the ResultSet/Views dispatch system
2fdc310be7cd [book] add autoload section from code and fix sphinx warnings
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6347
diff changeset
    21
  build up the whole content; it handles :exc:`ObjectNotFound` and
2fdc310be7cd [book] add autoload section from code and fix sphinx warnings
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6347
diff changeset
    22
  :exc:`NoSelectableObject` errors that may bubble up to its entry point, in an
2fdc310be7cd [book] add autoload section from code and fix sphinx warnings
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 6347
diff changeset
    23
  end-user-friendly way (but other programming errors will slip through)
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    24
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    25
* the JSon controller (same module) provides services for Ajax calls,
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    26
  typically using JSON as a serialization format for input, and
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    27
  sometimes using either JSON or XML for output;
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    28
7876
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    29
* the JSonpController is a wrapper around the ``ViewController`` that
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    30
  provides jsonp_ services. Padding can be specified with the
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    31
  ``callback`` request parameter. Only *jsonexport* / *ejsonexport*
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    32
  views can be used. If another ``vid`` is specified, it will be
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    33
  ignored and replaced by *jsonexport*. Request is anonymized
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    34
  to avoid returning sensitive data and reduce the risks of CSRF attacks;
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    35
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    36
* the Login/Logout controllers make effective user login or logout
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    37
  requests
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    38
7876
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    39
.. warning::
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    40
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    41
  JsonController will probably be renamed into AjaxController soon since
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    42
  it has nothing to do with json per se.
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    43
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    44
.. _jsonp: http://en.wikipedia.org/wiki/JSONP
df15d194a134 [views] implement json / jsonp export views (closes #1942658)
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 7529
diff changeset
    45
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    46
`Edition`:
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    47
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    48
* the Edit controller (see :ref:`edit_controller`) handles CRUD
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    49
  operations in response to a form being submitted; it works in close
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    50
  association with the Forms, to which it delegates some of the work
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    51
5459
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    52
* the ``Form validator controller`` provides form validation from Ajax
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    53
  context, using the Edit controller, to implement the classic form
5459
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    54
  handling loop (user edits, hits `submit/apply`, validation occurs
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    55
  server-side by way of the Form validator controller, and the UI is
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    56
  decorated with failure information, either global or per-field ,
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    57
  until it is valid)
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    58
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    59
`Other`:
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    60
5459
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    61
* the ``SendMail controller`` (web/views/basecontrollers.py) is reponsible
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    62
  for outgoing email notifications
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    63
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    64
* the MailBugReport controller (web/views/basecontrollers.py) allows
6347
ef47a2100c66 exception: specify expected parameter in NoSelectableException
Julien Jehannet <julien.jehannet@logilab.fr>
parents: 5459
diff changeset
    65
  to quickly have a `reportbug` feature in one's application
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    66
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    67
Registration
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    68
++++++++++++
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    69
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    70
All controllers (should) live in the 'controllers' namespace within
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    71
the global registry.
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    72
5459
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    73
Concrete controllers
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    74
++++++++++++++++++++
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    75
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    76
Most API details should be resolved by source code inspection, as the
5459
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    77
various controllers have differing goals. See for instance the
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    78
:ref:`edit_controller` chapter.
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    79
5459
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    80
:mod:`cubicweb.web.controller` contains the top-level abstract
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    81
Controller class and its unimplemented entry point
6e561796804c [doc/book] regroup form/editcontroller stuff under an "edition control" chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    82
`publish(rset=None)` method.
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    83
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    84
A handful of helpers are also provided there:
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    85
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    86
* process_rql builds a result set from an rql query typically issued
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    87
  from the browser (and available through _cw.form['rql'])
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    88
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    89
* validate_cache will force cache validation handling with respect to
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    90
  the HTTP Cache directives (that were typically originally issued
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    91
  from a previous server -> client response); concrete Controller
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    92
  implementations dealing with HTTP (thus, for instance, not the
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    93
  SendMail controller) may very well call this in their publication
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    94
  process.