.. _controllers:

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. They are all defined in

(:mod:`cubicweb.web.views.basecontrollers`).

`Browsing`:

* the View controller is associated with most browsing actions within a

  CubicWeb application: it always instantiates a :ref:`the_main_template` and

  lets the ResultSet/Views dispatch system build up the whole content; it

  handles :exc:`ObjectNotFound` and :exc:`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 (same module) 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 make effective user login or logout

  requests

`Edition`:

* the Edit controller (see :ref:`edit_controller`) 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`` 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 `reportbug` feature in one's application

Registration

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

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

the global registry.

Concrete controllers

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

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

various controllers have differing goals. See for instance the

:ref:`edit_controller` chapter.

:mod:`cubicweb.web.controller` contains the top-level abstract

Controller class and its unimplemented 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.