doc/book/en/development/devweb/controllers.rst
author Aurelien Campeas <aurelien.campeas@logilab.fr>
Thu, 15 Apr 2010 10:58:21 +0200
branchstable
changeset 5266 84f285d96363
parent 5263 196eb979318f
permissions -rw-r--r--
[doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
     1
.. _controllers:
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
     2
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
Controllers
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
-----------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     6
Overview
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     7
++++++++
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     8
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
     9
Controllers are responsible for taking action upon user requests
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    10
(loosely following the terminology of the MVC meta pattern).
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    11
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    12
The following controllers are provided out-of-the box in CubicWeb. We
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    13
list them by category.
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    14
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    15
`Browsing`:
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    16
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    17
* the View controller (web/views/basecontrollers.py) is associated
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    18
  with most browsing actions within a CubicWeb application: it always
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    19
  instantiates a `main template` and lets the ResultSet/Views dispatch
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    20
  system build up the whole content; it handles ObjectNotFound and
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    21
  NoSelectableObject errors that may bubble up to its entry point, in
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    22
  an end-user-friendly way (but other programming errors will slip
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    23
  through)
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    24
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    25
* the JSon controller (web/views/basecontrollers.py) provides services
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    26
  for Ajax calls, typically using JSON as a serialization format for
4743
026a89520184 [book] a few autoclasses for renderers, misc tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4741
diff changeset
    27
  input, and sometimes using either JSON or XML for output;
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    28
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    29
* the Login/Logout controllers (web/views/basecontrollers.py) make
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    30
  effective user login or logout requests
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    31
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    32
`Edition`:
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    33
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    34
* the Edit controller (see :ref:`edit_controller`) handles CRUD
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    35
  operations in response to a form being submitted; it works in close
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    36
  association with the Forms, to which it delegates some of the work
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    37
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    38
* the Form validator controller (web/views/basecontrollers.py)
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    39
  provides form validation from Ajax context, using the Edit
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    40
  controller, to implement the classic form handling loop (user edits,
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    41
  hits 'submit/apply', validation occurs server-side by way of the
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    42
  Form validator controller, and the UI is decorated with failure
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    43
  information, either global or per-field , until it is valid)
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    44
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    45
`Other`:
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    46
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    47
* the SendMail controller (web/views/basecontrollers.py) is reponsible
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    48
  for outgoing email notifications
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    49
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    50
* the MailBugReport controller (web/views/basecontrollers.py) allows
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    51
  to quickly have a `repotbug` feature in one's application
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    52
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    53
Registration
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    54
++++++++++++
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    55
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    56
All controllers (should) live in the 'controllers' namespace within
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    57
the global registry.
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    58
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    59
API
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    60
+++
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    61
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    62
Most API details should be resolved by source code inspection, as the
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    63
various controllers have differing goals.
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    64
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    65
`web/controller.py` contains the top-level abstract Controller class and
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    66
its (NotImplemented) entry point `publish(rset=None)` method.
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    67
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    68
A handful of helpers are also provided there:
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    69
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    70
* process_rql builds a result set from an rql query typically issued
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    71
  from the browser (and available through _cw.form['rql'])
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    72
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    73
* validate_cache will force cache validation handling with respect to
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    74
  the HTTP Cache directives (that were typically originally issued
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    75
  from a previous server -> client response); concrete Controller
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    76
  implementations dealing with HTTP (thus, for instance, not the
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    77
  SendMail controller) may very well call this in their publication
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    78
  process.
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    79
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    80
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    81
.. _edit_controller:
4741
f9a176ebe090 [book/controllers] add some content (overview, api super sketch) for the cubicweb controllers
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 1714
diff changeset
    82
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    83
The `edit controller`
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    84
+++++++++++++++++++++
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    85
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    86
It can be found in (:mod:`cubicweb.web.views.editcontroller`).
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    87
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    88
Editing control
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    89
~~~~~~~~~~~~~~~~
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    90
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    91
Re-requisites: the parameters related to entities to edit are
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    92
specified as follows ::
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    93
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    94
  <field name>:<entity eid>
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    95
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    96
where entity eid could be a letter in case of an entity to create. We
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    97
name those parameters as *qualified*.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    98
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
    99
1. Retrieval of entities to edit by looking for the forms parameters
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   100
   starting by `eid:` and also having a parameter `__type` associated
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   101
   (also *qualified* by eid)
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   102
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   103
2. For all the attributes and the relations of an entity to edit:
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   104
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   105
   1. search for a parameter `edits-<relation name>` or `edito-<relation name>`
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   106
      qualified in the case of a relation where the entity is object
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   107
   2. if found, the value returned is considered as the initial value
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   108
      for this relaiton and we then look for the new value(s)  in the parameter
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   109
      <relation name> (qualified)
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   110
   3. if the value returned is different from the initial value, an database update
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   111
      request is done
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   112
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   113
3. For each entity to edit:
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   114
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   115
   1. if a qualified parameter `__linkto` is specified, its value has to be
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   116
      a string (or a list of string) such as: ::
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   117
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   118
        <relation type>:<eids>:<target>
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   119
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   120
      where <target> is either `subject` or `object` and each eid could be
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   121
      separated from the others by a `_`. Target specifies if the *edited entity*
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   122
      is subject or object of the relation and each relation specified will
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   123
      be inserted.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   124
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   125
    2. if a qualified parameter `__clone_eid` is specified for an entity, the
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   126
       relations of the specified entity passed as value of this parameter are
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   127
       copied on the edited entity.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   128
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   129
    3. if a qualified parameter `__delete` is specified, its value must be
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   130
       a string or a list of string such as follows: ::
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   131
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   132
          <ssubjects eids>:<relation type>:<objects eids>
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   133
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   134
       where each eid subject or object can be seperated from the other
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   135
       by `_`. Each relation specified will be deleted.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   136
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   137
    4. if a qualified parameter `__insert` is specified, its value should
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   138
       follow the same pattern as `__delete`, but each relation specified is
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   139
       inserted.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   140
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   141
4. If the parameters `__insert` and/or `__delete` are found not qualified,
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   142
   they are interpreted as explained above (independantly from the number
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   143
   of entities edited).
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   144
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   145
5. If no entity is edited but the form contains the parameters `__linkto`
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   146
   and `eid`, this one is interpreted by using the value specified for `eid`
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   147
   to designate the entity on which to add the relations.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   148
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   149
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   150
.. note::
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   151
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   152
   * If the parameter `__action_delete` is found, all the entities specified
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   153
     as to be edited will be deleted.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   154
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5263
diff changeset
   155
   * If the parameter `__action_cancel` is found, no action is completed.
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   156
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5263
diff changeset
   157
   * If the parameter `__action_apply` is found, the editing is
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5263
diff changeset
   158
     applied normally but the redirection is done on the form (see
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5263
diff changeset
   159
     :ref:`RedirectionControl`).
5263
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   160
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   161
   * The parameter `__method` is also supported as for the main template
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   162
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   163
   * If no entity is found to be edited and if there is no parameter
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   164
     `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   165
     `__insert`, an error is raised.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   166
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   167
   * Using the parameter `__message` in the form will allow to use its value
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   168
     as a message to provide the user once the editing is completed.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   169
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   170
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   171
.. _RedirectionControl:
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   172
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   173
Redirection control
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   174
~~~~~~~~~~~~~~~~~~~
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   175
Once editing is completed, there is still an issue left: where should we go
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   176
now? If nothing is specified, the controller will do his job but it does not
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   177
mean we will be happy with the result. We can control that by using the
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   178
following parameters:
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   179
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   180
* `__redirectpath`: path of the URL (relative to the root URL of the site,
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   181
  no form parameters
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   182
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   183
* `__redirectparams`: forms parameters to add to the path
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   184
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   185
* `__redirectrql`: redirection RQL request
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   186
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   187
* `__redirectvid`: redirection view identifier
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   188
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   189
* `__errorurl`: initial form URL, used for redirecting in case a validation
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   190
  error is raised during editing. If this one is not specified, an error page
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   191
  is displayed instead of going back to the form (which is, if necessary,
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   192
  responsible for displaying the errors)
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   193
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   194
* `__form_id`: initial view form identifier, used if `__action_apply` is
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   195
  found
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   196
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   197
In general we use either `__redirectpath` and `__redirectparams` or
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   198
`__redirectrql` and `__redirectvid`.
196eb979318f [doc/book] merge controller/editcontroller
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4743
diff changeset
   199