diff -r 76ab3c71aff2 -r c67bcee93248 doc/book/en/devweb/edition/editcontroller.rst --- a/doc/book/en/devweb/edition/editcontroller.rst Mon Jul 06 17:39:35 2015 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,113 +0,0 @@ -.. _edit_controller: - -The `edit controller` ---------------------- - -It can be found in (:mod:`cubicweb.web.views.editcontroller`). This -controller processes data received from an html form to create or -update entities. - -Edition handling -~~~~~~~~~~~~~~~~ - -The parameters related to entities to edit are specified as follows -(first seen in :ref:`attributes_section`):: - - : - -where entity eid could be a letter in case of an entity to create. We -name those parameters as *qualified*. - -* Retrieval of entities to edit is done by using the forms parameters - `eid` and `__type` - -* For all the attributes and the relations of an entity to edit - (attributes and relations are handled a bit differently but these - details are not much relevant here) : - - * using the ``rtype``, ``role`` and ``__type`` information, fetch - an appropriate field instance - - * check if the field has been modified (if not, proceed to the next - relation) - - * build an rql expression to update the entity - -At the end, all rql expressions are executed. - -* For each entity to edit: - - * if a qualified parameter `__linkto` is specified, its value has - to be a string (or a list of strings) 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. - - * 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. - - * 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 specified relation will be deleted. - - -* 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`). - - * 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`.