doc/book/en/B1030-form-management.en.txt
changeset 288 487bcc269d50
parent 192 46b24614282c
child 301 e47150482ac1
equal deleted inserted replaced
287:adbf9a24c41e 288:487bcc269d50
       
     1 .. -*- coding: utf-8 -*-
       
     2 
       
     3 Forms handling
       
     4 ==============
       
     5 
       
     6 Automatically generated forms management for handled entities
       
     7 -------------------------------------------------------------
       
     8 
       
     9 XXX FILLME
       
    10 
       
    11 * forms ``edition`` and ``creation``
       
    12 
       
    13 The form generated by default does not fit your needs? You are not
       
    14 required to re-do all by hands! :)
       
    15 
       
    16 * rtags primary, secondary, generated, generic, 
       
    17   `Entity.relation_category(rtype, x='subject')`
       
    18 * inline_view (now a rtag?)
       
    19 * widget specification
       
    20 
       
    21 Editing controller behavior by default (id: `edit`)
       
    22 ---------------------------------------------------
       
    23 
       
    24 Editing control
       
    25 ```````````````
       
    26 
       
    27 Re-requisites: the parameters related to entities to edit are
       
    28 specified as follows ::
       
    29 
       
    30   <field name>:<entity eid>
       
    31 
       
    32 where entity eid could be a letter in case of an entity to create. We
       
    33 name those parameters as *qualified*.
       
    34 
       
    35 1. Retrieval of entities to edit by looking for the forms parameters
       
    36    starting by `eid:` and also having a parameter `__type` associated
       
    37    (also *qualified* by eid)
       
    38 
       
    39 2. For all the attributes and the relations of an entity to edit: 
       
    40    
       
    41    1. search for a parameter `edits-<relation name>` or `edito-<relation name>`
       
    42       qualified in the case of a relation where the entity is object
       
    43    2. if found, the value returned is considered as the initial value
       
    44       for this relaiton and we then look for the new value(s)  in the parameter
       
    45       <relation name> (qualified)
       
    46    3. if the value returned is different from the initial value, an database update
       
    47       request is done
       
    48 
       
    49 3. For each entity to edit:
       
    50 
       
    51    1. if a qualified parameter `__linkto` is specified, its value has to be
       
    52       a string (or a list of string) such as: ::
       
    53         
       
    54         <relation type>:<eids>:<target>
       
    55       
       
    56       where <target> is either `subject` or `object` and each eid could be
       
    57       separated from the others by a `_`. Target specifies if the *edited entity*
       
    58       is subject or object of the relation and each relation specified will
       
    59       be inserted.
       
    60 
       
    61     2. if a qualified parameter `__clone_eid` is specified for an entity, the
       
    62        relations of the specified entity passed as value of this parameter are 
       
    63        copied on the edited entity.
       
    64 
       
    65     3. if a qualified parameter `__delete` is specified, its value must be
       
    66        a string or a list of string such as follows: ::
       
    67           
       
    68           <ssubjects eids>:<relation type>:<objects eids>
       
    69 
       
    70        where each eid subject or object can be seperated from the other 
       
    71        by `_`. Each relation specified will be deleted.
       
    72 
       
    73     4. if a qualified parameter `__insert` is specified, its value should
       
    74        follow the same pattern as `__delete`, but each relation specified is
       
    75        inserted.
       
    76 
       
    77 4. If the parameters `__insert` and/or `__delete` are found not qualified,
       
    78    they are interpreted as explained above (independantly from the number
       
    79    of entities edited).
       
    80 
       
    81 5. If no entity is edited but the form contains the parameters `__linkto`
       
    82    and `eid`, this one is interpreted by using the value specified for `eid`
       
    83    to designate the entity on which to add the relations.
       
    84 
       
    85 
       
    86 .. note::
       
    87    
       
    88    * If the parameter `__action_delete` is found, all the entities specified
       
    89      as to be edited will be deleted.
       
    90    
       
    91    * If the parameter`__action_cancel` is found, no action is completed.
       
    92 
       
    93    * If the parameter `__action_apply` is found, the editing is applied 
       
    94      normally but the redirection is done on the form 
       
    95      (see :ref:`RedirectionControl`).
       
    96 
       
    97    * The parameter `__method` is also supported as for the main template
       
    98      (XXX not very consistent, maybe __method should be dealed in the view
       
    99      controller).
       
   100 
       
   101    * If no entity is found to be edited and if there is no parameter
       
   102      `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or
       
   103      `__insert`, an error is raised.
       
   104 
       
   105    * Using the parameter `__message` in the form will allow to use its value
       
   106      as a message to provide the user once the editing is completed.
       
   107 
       
   108 
       
   109 .. _RedirectionControl:
       
   110 
       
   111 Redirection control
       
   112 ```````````````````
       
   113 Once editing is completed, there is still an issue left: where should we go
       
   114 now? If nothing is specified, the controller will do his job but it does not
       
   115 mean we will be happy with the result. We can control that by using the
       
   116 following parameters:
       
   117 
       
   118 * `__redirectpath`: path of the URL (relative to the root URL of the site,
       
   119   no form parameters
       
   120 
       
   121 * `__redirectparams`: forms parameters to add to the path
       
   122 
       
   123 * `__redirectrql`: redirection RQL request 
       
   124 
       
   125 * `__redirectvid`: redirection view identifier
       
   126 
       
   127 * `__errorurl`: initial form URL, used for redirecting in case a validation
       
   128   error is raised during editing. If this one is not specified, an error page
       
   129   is displayed instead of going back to the form (which is, if necessarry,
       
   130   responsible for displaying the errors)
       
   131 
       
   132 * `__form_id`: initial view form identifier, used if `__action_apply` is
       
   133   found
       
   134 
       
   135 In general we use either `__redirectpath` and `__redirectparams` or 
       
   136 `__redirectrql` and `__redirectvid`.
       
   137