1 .. _controllers:

     2 

     3 Controllers

     4 -----------

     5 

     6 Overview

     7 ++++++++

     8 

     9 Controllers are responsible for taking action upon user requests

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

    11 

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

    13 list them by category. They are all defined in

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

    15 

    16 `Browsing`:

    17 

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

    19   CubicWeb application: it always instantiates a

    20   :ref:`the_main_template_layout` and lets the ResultSet/Views dispatch system

    21   build up the whole content; it handles :exc:`ObjectNotFound` and

    22   :exc:`NoSelectableObject` errors that may bubble up to its entry point, in an

    23   end-user-friendly way (but other programming errors will slip through)

    24 

    25 * the JSonpController is a wrapper around the ``ViewController`` that

    26   provides jsonp_ services. Padding can be specified with the

    27   ``callback`` request parameter. Only *jsonexport* / *ejsonexport*

    28   views can be used. If another ``vid`` is specified, it will be

    29   ignored and replaced by *jsonexport*. Request is anonymized

    30   to avoid returning sensitive data and reduce the risks of CSRF attacks;

    31 

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

    33   requests

    34 

    35 

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

    37 

    38 `Edition`:

    39 

    40 * the Edit controller (see :ref:`edit_controller`) handles CRUD

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

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

    43 

    44 * the ``Form validator controller`` provides form validation from Ajax

    45   context, using the Edit controller, to implement the classic form

    46   handling loop (user edits, hits `submit/apply`, validation occurs

    47   server-side by way of the Form validator controller, and the UI is

    48   decorated with failure information, either global or per-field ,

    49   until it is valid)

    50 

    51 `Other`:

    52 

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

    54   for outgoing email notifications

    55 

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

    57   to quickly have a `reportbug` feature in one's application

    58 

    59 * the :class:`cubicweb.web.views.ajaxcontroller.AjaxController`

    60   (:mod:`cubicweb.web.views.ajaxcontroller`) provides

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

    62   for input, and sometimes using either JSON or XML for output. See

    63   :ref:`ajax` chapter for more information.

    64 

    65 

    66 Registration

    67 ++++++++++++

    68 

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

    70 the global registry.

    71 

    72 Concrete controllers

    73 ++++++++++++++++++++

    74 

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

    76 various controllers have differing goals. See for instance the

    77 :ref:`edit_controller` chapter.

    78 

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

    80 Controller class and its unimplemented entry point

    81 `publish(rset=None)` method.

    82 

    83 A handful of helpers are also provided there:

    84 

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

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

    87 

    88 * validate_cache will force cache validation handling with respect to

    89   the HTTP Cache directives (that were typically originally issued

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

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

    92   SendMail controller) may very well call this in their publication

    93   process.