.. _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_layout` 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 JSonpController is a wrapper around the ``ViewController`` that
  provides jsonp_ services. Padding can be specified with the
  ``callback`` request parameter. Only *jsonexport* / *ejsonexport*
  views can be used. If another ``vid`` is specified, it will be
  ignored and replaced by *jsonexport*. Request is anonymized
  to avoid returning sensitive data and reduce the risks of CSRF attacks;

* the Login/Logout controllers make effective user login or logout
  requests

.. warning::

  JsonController will probably be renamed into AjaxController soon since
  it has nothing to do with json per se.

.. _jsonp: http://en.wikipedia.org/wiki/JSONP

`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.