1 .. _edit_controller:

     2 

     3 The `edit controller`

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

     5 

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

     7 controller processes data received from an html form to create or

     8 update entities.

     9 

    10 Edition handling

    11 ~~~~~~~~~~~~~~~~

    12 

    13 The parameters related to entities to edit are specified as follows

    14 (first seen in :ref:`attributes_section`)::

    15 

    16   <rtype-role>:<entity eid>

    17 

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

    19 name those parameters as *qualified*.

    20 

    21 * Retrieval of entities to edit is done by using the forms parameters

    22   `eid` and `__type`

    23 

    24 * For all the attributes and the relations of an entity to edit

    25   (attributes and relations are handled a bit differently but these

    26   details are not much relevant here) :

    27 

    28    * using the ``rtype``, ``role`` and ``__type`` information, fetch

    29      an appropriate field instance

    30 

    31    * check if the field has been modified (if not, proceed to the next

    32      relation)

    33 

    34    * build an rql expression to update the entity

    35 

    36 At the end, all rql expressions are executed.

    37 

    38 * For each entity to edit:

    39 

    40    * if a qualified parameter `__linkto` is specified, its value has

    41      to be a string (or a list of strings) such as: ::

    42 

    43         <relation type>:<eids>:<target>

    44 

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

    46      be separated from the others by a `_`. Target specifies if the

    47      *edited entity* is subject or object of the relation and each

    48      relation specified will be inserted.

    49 

    50     * if a qualified parameter `__clone_eid` is specified for an entity, the

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

    52       copied on the edited entity.

    53 

    54     * if a qualified parameter `__delete` is specified, its value must be

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

    56 

    57           <subjects eids>:<relation type>:<objects eids>

    58 

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

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

    61 

    62 

    63 * If no entity is edited but the form contains the parameters `__linkto`

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

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

    66 

    67 .. note::

    68 

    69    * if the parameter `__action_delete` is found, all the entities specified

    70      as to be edited will be deleted.

    71 

    72    * if the parameter `__action_cancel` is found, no action is completed.

    73 

    74    * if the parameter `__action_apply` is found, the editing is

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

    76      :ref:`RedirectionControl`).

    77 

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

    79      `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or

    80      `__insert`, an error is raised.

    81 

    82    * using the parameter `__message` in the form will allow to use its value

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

    84 

    85 

    86 .. _RedirectionControl:

    87 

    88 Redirection control

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

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

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

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

    93 following parameters:

    94 

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

    96   no form parameters

    97 

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

    99 

   100 * `__redirectrql`: redirection RQL request

   101 

   102 * `__redirectvid`: redirection view identifier

   103 

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

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

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

   107   responsible for displaying the errors)

   108 

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

   110   found

   111 

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

   113 `__redirectrql` and `__redirectvid`.