Controllers

-----------

Overview

++++++++

Controllers are responsible for taking action upon user requests

(loosely following the terminology of the MVC meta pattern).

The following controllers are provided out-of-the box in CubicWeb. We

list them by category.

Browsing:

* the View controller (web/views/basecontrollers.py) is associated

  with most browsing actions within a CubicWeb application: it always

  instantiates a `main template` and lets the ResultSet/Views dispatch

  system build up the whole content; it handles ObjectNotFound and

  NoSelectableObject errors that may bubble up to its entry point, in

  an end-user-friendly way (but other programming errors will slip

  through)

* the JSon controller (web/views/basecontrollers.py) provides services

  for Ajax calls, typically using JSON as a serialization format for

  input, and sometimes using either JSON or XML for output;

* the Login/Logout controllers (web/views/basecontrollers.py) make

  effective user login or logout requests

Edition:

* the Edit controller (web/views/editcontroller.py) handles CRUD

  operations in response to a form being submitted; it works in close

  association with the Forms, to which it delegates some of the work

* the Form validator controller (web/views/basecontrollers.py)

  provides form validation from Ajax context, using the Edit

  controller, to implement the classic form handling loop (user edits,

  hits 'submit/apply', validation occurs server-side by way of the

  Form validator controller, and the UI is decorated with failure

  information, either global or per-field , until it is valid)

Other:

* the SendMail controller (web/views/basecontrollers.py) is reponsible

  for outgoing email notifications

* the MailBugReport controller (web/views/basecontrollers.py) allows

  to quickly have a `repotbug` feature in one's application

Registration

++++++++++++

All controllers (should) live in the 'controllers' namespace within

the global registry.

API

+++

Most API details should be resolved by source code inspection, as the

various controllers have differing goals.

`web/controller.py` contains the top-level abstract Controller class and

its (NotImplemented) entry point `publish(rset=None)` method.

A handful of helpers are also provided there:

* process_rql builds a result set from an rql query typically issued

  from the browser (and available through _cw.form['rql'])

* validate_cache will force cache validation handling with respect to

  the HTTP Cache directives (that were typically originally issued

  from a previous server -> client response); concrete Controller

  implementations dealing with HTTP (thus, for instance, not the

  SendMail controller) may very well call this in their publication

  process.