doc/book/en/development/devweb/controllers.rst
author Aurelien Campeas <aurelien.campeas@logilab.fr>
Tue, 06 Apr 2010 15:25:56 +0200
branchstable
changeset 5152 35e6878e2fd0
parent 4743 026a89520184
child 5263 196eb979318f
permissions -rw-r--r--
[doc/book] adjust a bit
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
Controllers
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
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
     4
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
     5
++++++++
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
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
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
     8
(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
     9
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
The following controllers are provided out-of-the box in CubicWeb. We
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
list them by category.
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
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    13
Browsing:
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    14
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
* the View controller (web/views/basecontrollers.py) is associated
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    16
  with most browsing actions within a CubicWeb application: it always
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
  instantiates a `main template` and lets the ResultSet/Views dispatch
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    18
  system build up the whole content; it handles ObjectNotFound and
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    19
  NoSelectableObject errors that may bubble up to its entry point, in
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    20
  an end-user-friendly way (but other programming errors will slip
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    21
  through)
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    22
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    23
* the JSon controller (web/views/basecontrollers.py) provides services
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
  for Ajax calls, typically using JSON as a serialization format for
4743
026a89520184 [book] a few autoclasses for renderers, misc tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4741
diff changeset
    25
  input, and 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
    26
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    27
* the Login/Logout controllers (web/views/basecontrollers.py) make
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
  effective user login or logout 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
    29
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    30
Edition:
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    31
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    32
* the Edit controller (web/views/editcontroller.py) handles CRUD
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    33
  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
    34
  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
    35
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    36
* the Form validator controller (web/views/basecontrollers.py)
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    37
  provides form validation from Ajax context, using the Edit
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
  controller, to implement the classic form handling loop (user edits,
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    39
  hits 'submit/apply', validation occurs server-side by way of 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
    40
  Form validator controller, and the UI is decorated with failure
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    41
  information, either global or per-field , until it is valid)
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    42
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    43
Other:
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    44
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    45
* the SendMail controller (web/views/basecontrollers.py) is reponsible
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    46
  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
    47
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    48
* the MailBugReport controller (web/views/basecontrollers.py) allows
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
  to quickly have a `repotbug` feature in one's application
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
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
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
    52
++++++++++++
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    53
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    54
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
    55
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
    56
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    57
API
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
+++
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    59
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
Most API details should be resolved by source code inspection, as 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
    61
various controllers have differing goals.
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
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
`web/controller.py` contains the top-level abstract Controller class and
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
its (NotImplemented) entry point `publish(rset=None)` method.
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    65
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
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
    67
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
* 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
    69
  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
    70
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
* 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
    72
  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
    73
  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
    74
  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
    75
  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
    76
  process.
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    77
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    78
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