diff -r ebd90d2a5639 -r 196eb979318f doc/book/en/development/devweb/controllers.rst --- a/doc/book/en/development/devweb/controllers.rst Wed Apr 14 18:10:47 2010 +0200 +++ b/doc/book/en/development/devweb/controllers.rst Wed Apr 14 18:24:17 2010 +0200 @@ -1,3 +1,5 @@ +.. _controllers: + Controllers ----------- @@ -10,7 +12,7 @@ The following controllers are provided out-of-the box in CubicWeb. We list them by category. -Browsing: +`Browsing`: * the View controller (web/views/basecontrollers.py) is associated with most browsing actions within a CubicWeb application: it always @@ -27,9 +29,9 @@ * the Login/Logout controllers (web/views/basecontrollers.py) make effective user login or logout requests -Edition: +`Edition`: -* the Edit controller (web/views/editcontroller.py) handles CRUD +* 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 @@ -40,7 +42,7 @@ Form validator controller, and the UI is decorated with failure information, either global or per-field , until it is valid) -Other: +`Other`: * the SendMail controller (web/views/basecontrollers.py) is reponsible for outgoing email notifications @@ -76,4 +78,124 @@ process. +.. _edit_controller: +The `edit controller` ++++++++++++++++++++++ + +It can be found in (:mod:`cubicweb.web.views.editcontroller`). + +Editing control +~~~~~~~~~~~~~~~~ + +Re-requisites: the parameters related to entities to edit are +specified as follows :: + + : + +where entity eid could be a letter in case of an entity to create. We +name those parameters as *qualified*. + +1. Retrieval of entities to edit by looking for the forms parameters + starting by `eid:` and also having a parameter `__type` associated + (also *qualified* by eid) + +2. For all the attributes and the relations of an entity to edit: + + 1. search for a parameter `edits-` or `edito-` + qualified in the case of a relation where the entity is object + 2. if found, the value returned is considered as the initial value + for this relaiton and we then look for the new value(s) in the parameter + (qualified) + 3. if the value returned is different from the initial value, an database update + request is done + +3. For each entity to edit: + + 1. if a qualified parameter `__linkto` is specified, its value has to be + a string (or a list of string) such as: :: + + :: + + where is either `subject` or `object` and each eid could be + separated from the others by a `_`. Target specifies if the *edited entity* + is subject or object of the relation and each relation specified will + be inserted. + + 2. if a qualified parameter `__clone_eid` is specified for an entity, the + relations of the specified entity passed as value of this parameter are + copied on the edited entity. + + 3. if a qualified parameter `__delete` is specified, its value must be + a string or a list of string such as follows: :: + + :: + + where each eid subject or object can be seperated from the other + by `_`. Each relation specified will be deleted. + + 4. if a qualified parameter `__insert` is specified, its value should + follow the same pattern as `__delete`, but each relation specified is + inserted. + +4. If the parameters `__insert` and/or `__delete` are found not qualified, + they are interpreted as explained above (independantly from the number + of entities edited). + +5. If no entity is edited but the form contains the parameters `__linkto` + and `eid`, this one is interpreted by using the value specified for `eid` + to designate the entity on which to add the relations. + + +.. note:: + + * If the parameter `__action_delete` is found, all the entities specified + as to be edited will be deleted. + + * If the parameter`__action_cancel` is found, no action is completed. + + * If the parameter `__action_apply` is found, the editing is applied + normally but the redirection is done on the form + (see :ref:`RedirectionControl`). + + * The parameter `__method` is also supported as for the main template + (XXX not very consistent, maybe __method should be dealed in the view + controller). + + * If no entity is found to be edited and if there is no parameter + `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or + `__insert`, an error is raised. + + * Using the parameter `__message` in the form will allow to use its value + as a message to provide the user once the editing is completed. + + +.. _RedirectionControl: + +Redirection control +~~~~~~~~~~~~~~~~~~~ +Once editing is completed, there is still an issue left: where should we go +now? If nothing is specified, the controller will do his job but it does not +mean we will be happy with the result. We can control that by using the +following parameters: + +* `__redirectpath`: path of the URL (relative to the root URL of the site, + no form parameters + +* `__redirectparams`: forms parameters to add to the path + +* `__redirectrql`: redirection RQL request + +* `__redirectvid`: redirection view identifier + +* `__errorurl`: initial form URL, used for redirecting in case a validation + error is raised during editing. If this one is not specified, an error page + is displayed instead of going back to the form (which is, if necessary, + responsible for displaying the errors) + +* `__form_id`: initial view form identifier, used if `__action_apply` is + found + +In general we use either `__redirectpath` and `__redirectparams` or +`__redirectrql` and `__redirectvid`. +