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.

    14 

    15 `Browsing`:

    16 

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

    18   with most browsing actions within a CubicWeb application: it always

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

    20   system build up the whole content; it handles ObjectNotFound and

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

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

    23   through)

    24 

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

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

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

    28 

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

    30   effective user login or logout requests

    31 

    32 `Edition`:

    33 

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

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

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

    37 

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

    39   provides form validation from Ajax context, using the Edit

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

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

    42   Form validator controller, and the UI is decorated with failure

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

    44 

    45 `Other`:

    46 

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

    48   for outgoing email notifications

    49 

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

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

    52 

    53 Registration

    54 ++++++++++++

    55 

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

    57 the global registry.

    58 

    59 API

    60 +++

    61 

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

    63 various controllers have differing goals.

    64 

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

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

    67 

    68 A handful of helpers are also provided there:

    69 

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

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

    72 

    73 * validate_cache will force cache validation handling with respect to

    74   the HTTP Cache directives (that were typically originally issued

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

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

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

    78   process.

    79 

    80 

    81 .. _edit_controller:

    82 

    83 The `edit controller`

    84 +++++++++++++++++++++

    85 

    86 It can be found in (:mod:`cubicweb.web.views.editcontroller`).

    87 

    88 Editing control

    89 ~~~~~~~~~~~~~~~~

    90 

    91 Re-requisites: the parameters related to entities to edit are

    92 specified as follows ::

    93 

    94   <field name>:<entity eid>

    95 

    96 where entity eid could be a letter in case of an entity to create. We

    97 name those parameters as *qualified*.

    98 

    99 1. Retrieval of entities to edit by looking for the forms parameters

   100    starting by `eid:` and also having a parameter `__type` associated

   101    (also *qualified* by eid)

   102 

   103 2. For all the attributes and the relations of an entity to edit:

   104 

   105    1. search for a parameter `edits-<relation name>` or `edito-<relation name>`

   106       qualified in the case of a relation where the entity is object

   107    2. if found, the value returned is considered as the initial value

   108       for this relaiton and we then look for the new value(s)  in the parameter

   109       <relation name> (qualified)

   110    3. if the value returned is different from the initial value, an database update

   111       request is done

   112 

   113 3. For each entity to edit:

   114 

   115    1. if a qualified parameter `__linkto` is specified, its value has to be

   116       a string (or a list of string) such as: ::

   117 

   118         <relation type>:<eids>:<target>

   119 

   120       where <target> is either `subject` or `object` and each eid could be

   121       separated from the others by a `_`. Target specifies if the *edited entity*

   122       is subject or object of the relation and each relation specified will

   123       be inserted.

   124 

   125     2. if a qualified parameter `__clone_eid` is specified for an entity, the

   126        relations of the specified entity passed as value of this parameter are

   127        copied on the edited entity.

   128 

   129     3. if a qualified parameter `__delete` is specified, its value must be

   130        a string or a list of string such as follows: ::

   131 

   132           <ssubjects eids>:<relation type>:<objects eids>

   133 

   134        where each eid subject or object can be seperated from the other

   135        by `_`. Each relation specified will be deleted.

   136 

   137     4. if a qualified parameter `__insert` is specified, its value should

   138        follow the same pattern as `__delete`, but each relation specified is

   139        inserted.

   140 

   141 4. If the parameters `__insert` and/or `__delete` are found not qualified,

   142    they are interpreted as explained above (independantly from the number

   143    of entities edited).

   144 

   145 5. If no entity is edited but the form contains the parameters `__linkto`

   146    and `eid`, this one is interpreted by using the value specified for `eid`

   147    to designate the entity on which to add the relations.

   148 

   149 

   150 .. note::

   151 

   152    * If the parameter `__action_delete` is found, all the entities specified

   153      as to be edited will be deleted.

   154 

   155    * If the parameter `__action_cancel` is found, no action is completed.

   156 

   157    * If the parameter `__action_apply` is found, the editing is

   158      applied normally but the redirection is done on the form (see

   159      :ref:`RedirectionControl`).

   160 

   161    * The parameter `__method` is also supported as for the main template

   162 

   163    * If no entity is found to be edited and if there is no parameter

   164      `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or

   165      `__insert`, an error is raised.

   166 

   167    * Using the parameter `__message` in the form will allow to use its value

   168      as a message to provide the user once the editing is completed.

   169 

   170 

   171 .. _RedirectionControl:

   172 

   173 Redirection control

   174 ~~~~~~~~~~~~~~~~~~~

   175 Once editing is completed, there is still an issue left: where should we go

   176 now? If nothing is specified, the controller will do his job but it does not

   177 mean we will be happy with the result. We can control that by using the

   178 following parameters:

   179 

   180 * `__redirectpath`: path of the URL (relative to the root URL of the site,

   181   no form parameters

   182 

   183 * `__redirectparams`: forms parameters to add to the path

   184 

   185 * `__redirectrql`: redirection RQL request

   186 

   187 * `__redirectvid`: redirection view identifier

   188 

   189 * `__errorurl`: initial form URL, used for redirecting in case a validation

   190   error is raised during editing. If this one is not specified, an error page

   191   is displayed instead of going back to the form (which is, if necessary,

   192   responsible for displaying the errors)

   193 

   194 * `__form_id`: initial view form identifier, used if `__action_apply` is

   195   found

   196 

   197 In general we use either `__redirectpath` and `__redirectparams` or

   198 `__redirectrql` and `__redirectvid`.

   199