backport stable
authorSylvain Thénault <sylvain.thenault@logilab.fr>
Wed, 17 Mar 2010 11:37:47 +0100
changeset 4934 0dfd86d2cd98
parent 4933 433174d9394f (current diff)
parent 4932 dce5ebe5d598 (diff)
child 4938 b1a4fe480de5
backport stable
web/views/editcontroller.py
--- a/doc/book/en/development/devweb/rtags.rst	Wed Mar 17 11:36:47 2010 +0100
+++ b/doc/book/en/development/devweb/rtags.rst	Wed Mar 17 11:37:47 2010 +0100
@@ -2,13 +2,13 @@
 -----------------------------------
 
 
-The "Relation tags" structure
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Relation tags
+~~~~~~~~~~~~~
 .. automodule:: cubicweb.rtags
-   :members:
 
 
-The `uicfg` module (:mod:`cubicweb.web.uicfg`)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``uicfg`` module
+~~~~~~~~~~~~~~~~~~
 .. automodule:: cubicweb.web.uicfg
-   :members:
+
Binary file doc/book/en/images/primaryview_template.png has changed
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/images/primaryview_template.svg	Wed Mar 17 11:37:47 2010 +0100
@@ -0,0 +1,254 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="1036.6421"
+   height="845.07812"
+   id="svg2"
+   sodipodi:version="0.32"
+   inkscape:version="0.46"
+   sodipodi:docname="primaryview_template.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape"
+   version="1.0"
+   inkscape:export-filename="/home/steph/local/fcubicweb/cubicweb/doc/book/en/images/primaryview_template.png"
+   inkscape:export-xdpi="43.451603"
+   inkscape:export-ydpi="43.451603">
+  <defs
+     id="defs4">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="0 : 526.18109 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="744.09448 : 526.18109 : 1"
+       inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
+       id="perspective10" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.49497475"
+     inkscape:cx="432.61573"
+     inkscape:cy="370.11733"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="824"
+     inkscape:window-height="1094"
+     inkscape:window-x="0"
+     inkscape:window-y="45" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Calque 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(162.2968,90.697922)">
+    <rect
+       style="fill:#ffffff;fill-rule:evenodd;stroke:#ff0000;stroke-width:3.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3301"
+       width="842.59973"
+       height="562.81085"
+       x="28.555748"
+       y="53.761448" />
+    <rect
+       style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect2383"
+       width="629.62366"
+       height="54.69112"
+       x="54.112095"
+       y="73.831123" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="500.19885"
+       y="104.27108"
+       id="text2385"><tspan
+         sodipodi:role="line"
+         x="500.19885"
+         y="104.27108"
+         id="tspan3163">navcontenttop</tspan></text>
+    <rect
+       style="fill:#ffd5d5;fill-rule:evenodd;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3167"
+       width="628.2298"
+       height="165.69759"
+       x="54.809006"
+       y="142.37053" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="311.65164"
+       y="283.88312"
+       id="text3169"><tspan
+         sodipodi:role="line"
+         x="311.65164"
+         y="283.88312"
+         id="tspan3171">view.render_entity_attributes()</tspan></text>
+    <rect
+       style="fill:#ffd5d5;fill-rule:evenodd;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3173"
+       width="627.95807"
+       height="193.9873"
+       x="56.373432"
+       y="320.51138" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="320.29282"
+       y="488.45456"
+       id="text3175"><tspan
+         sodipodi:role="line"
+         x="320.29282"
+         y="488.45456"
+         id="tspan3177">view.render_entity_relations()</tspan></text>
+    <rect
+       style="fill:#ffd5d5;fill-rule:evenodd;stroke:#000000;stroke-width:1.76090598;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3185"
+       width="145.94266"
+       height="499.44452"
+       x="702.43958"
+       y="70.384262" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="74.177475"
+       y="-823.00977"
+       id="text3187"
+       transform="matrix(0,1,-1,0,0,0)"><tspan
+         sodipodi:role="line"
+         x="74.177475"
+         y="-823.00977"
+         id="tspan3189">view.render_side_boxes()</tspan></text>
+    <rect
+       style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:2.50000024;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3191"
+       width="629.62366"
+       height="45.386246"
+       x="54.112095"
+       y="524.98816" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="456.07504"
+       y="561.66559"
+       id="text3181"><tspan
+         sodipodi:role="line"
+         x="456.07504"
+         y="561.66559"
+         id="tspan3183">navcontentbottom</tspan></text>
+    <rect
+       style="fill:#dfdfdf;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:2.50000024;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3240"
+       width="1031.1713"
+       height="55.714287"
+       x="-161.0468"
+       y="-89.447922" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="757.85767"
+       y="-51.771908"
+       id="text3264"><tspan
+         sodipodi:role="line"
+         x="757.85767"
+         y="-51.771908"
+         id="tspan3266">header</tspan></text>
+    <rect
+       style="fill:#dfdfdf;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.76090598;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3270"
+       width="167.89117"
+       height="696.74976"
+       x="-160.03128"
+       y="-13.70227" />
+    <rect
+       style="fill:#dfdfdf;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3279"
+       width="842.59979"
+       height="55.714287"
+       x="28.328695"
+       y="-13.41731" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="668.23749"
+       y="25.321617"
+       id="text3281"><tspan
+         sodipodi:role="line"
+         x="668.23749"
+         y="25.321617"
+         id="tspan3283">contentheader</tspan></text>
+    <rect
+       style="fill:#dfdfdf;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3285"
+       width="1032.5997"
+       height="55.714287"
+       x="-159.50443"
+       y="697.41589" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="770.28204"
+       y="736.52045"
+       id="text3287"><tspan
+         sodipodi:role="line"
+         x="770.28204"
+         y="736.52045"
+         id="tspan3289">footer</tspan></text>
+    <rect
+       style="fill:#dfdfdf;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       id="rect3291"
+       width="844.62012"
+       height="55.714287"
+       x="27.850754"
+       y="627.44647" />
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="680.66193"
+       y="669.04254"
+       id="text3293"><tspan
+         sodipodi:role="line"
+         x="680.66193"
+         y="669.04254"
+         id="tspan3295">contentfooter</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="-130.25735"
+       y="24.239677"
+       id="text3297"><tspan
+         sodipodi:role="line"
+         x="-130.25735"
+         y="24.239677"
+         id="tspan3299">leftcolumn</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:23.38711166px;font-style:normal;font-weight:normal;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="373.18518"
+       y="610.24188"
+       id="text3351"><tspan
+         sodipodi:role="line"
+         x="373.18518"
+         y="610.24188"
+         id="tspan3353">view.render()</tspan></text>
+  </g>
+</svg>
--- a/rtags.py	Wed Mar 17 11:36:47 2010 +0100
+++ b/rtags.py	Wed Mar 17 11:37:47 2010 +0100
@@ -1,9 +1,26 @@
-"""relation tags store
+#:organization: Logilab
+#:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
+#:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+#:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+
+"""
+A RelationTag object is an object which allows to link a configuration information to a relation definition. For instance, the standard primary view uses a RelationTag object (uicfg.primaryview_section) to get the section to display relations.
+
+.. sourcecode:: python
 
-:organization: Logilab
-:copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
-:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+   # display ``entry_of`` relations in the ``relations`` section in the ``BlogEntry`` primary view
+   uicfg.primaryview_section.tag_subject_of(('BlogEntry', 'entry_of', '*'),
+                                             'relations')
+
+   # hide every relation ``entry_of`` in the ``Blog`` primary view
+   uicfg.primaryview_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden')
+
+Three primitives are defined:
+   * ``tag_subject_of`` tag a relation in the subject's context
+   * ``tag_object_of`` tag a relation in the object's context
+   * ``tag_attribute`` shortcut for tag_subject_of
+
+
 """
 __docformat__ = "restructuredtext en"
 
--- a/web/uicfg.py	Wed Mar 17 11:36:47 2010 +0100
+++ b/web/uicfg.py	Wed Mar 17 11:37:47 2010 +0100
@@ -1,54 +1,112 @@
-"""This module regroups a set of structures that may be used to configure
-various places of the generated web interface.
+#:organization: Logilab
+#:copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
+#:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
+#:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+
+"""This module (``cubicweb.web.uicfg``) regroups a set of structures that may be used to configure
+various options of the generated web interface.
+
+To configure the interface generation, we use ``RelationTag`` objects.
 
 Primary view configuration
 ``````````````````````````
-:primaryview_section:
-   where to display a relation in primary view. Value may be one of:
-   * 'attributes', display in the attributes section
-   * 'relations', display in the relations section (below attributes)
-   * 'sideboxes', display in the side boxes (beside attributes)
-   * 'hidden', don't display
+
+If you want to customize the primary view of an entity, overriding the
+primary view class may not be necessary. For simple adjustments
+(attributes or relations display locations and styles), a much simpler
+way is to use uicfg.
+
+Attributes/relations display location
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the primary view, there are 3 sections where attributes and
+relations can be displayed (represented in pink in the image below):
+   * attributes
+   * relations
+   * sideboxes
+
+ .. image:: ../../images/primaryview_template.png
+
+
+**Attributes** can only be displayed in the attributes section (default behavior). They can also be hidden.
 
-:primaryview_display_ctrl:
+For instance, to hide the ``title`` attribute of the ``Blog`` entity:
+
+.. sourcecode:: python
+
+   from cubicweb.web import uicfg
+   uicfg.primaryview_section.tag_attribute(('Blog', 'title'), 'hidden')
+
+
+**Relations** can be either displayed in one of the three sections or hidden.
 
-   how to display a relation in primary view. Values are dict with some of the
-   following keys:
+For relations, there are two methods:
+   * ``tag_object_of`` for modifying the primary view of the object
+   * ``tag_subject_of`` for modifying the primary view of the subject
+
+These two methods take two arguments:
+   * a triplet ``(subject, relation_name, object)``, where subject or object can be replaced with ``'*'``
+   * the section name or ``hidden``
+
+.. sourcecode:: python
+
+   # hide every relation ``entry_of`` in the ``Blog`` primary view
+   uicfg.primaryview_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden')
 
-   :vid:
-      identifier of a view to use to display the result set. Defaults depends on
-      the section:
-      * 'attributes' section: 'reledit' view
-      * 'relations' section: 'autolimited' view
-      * 'sideboxes' section: 'sidebox' view
+   # display ``entry_of`` relations in the ``relations`` section in the ``BlogEntry`` primary view
+   uicfg.primaryview_section.tag_subject_of(('BlogEntry', 'entry_of', '*'),
+                                             'relations')
+
+
+Display content
+^^^^^^^^^^^^^^^
+
+You can use ``primaryview_display_ctrl`` to customize the display of attributes or relations. Values of ``primaryview_display_ctrl`` are dictionaries.
+
 
-   :label:
-     label for the relations section or side box
+Common keys for attributes and relations are:
+   * ``vid``: specifies the regid of the view for displaying the attribute or the relation.
+
+     If ``vid`` is not specified, the default value depends on the section:
+       * ``attributes`` section: 'reledit' view
+       * ``relations`` section: 'autolimited' view
+       * ``sideboxes`` section: 'sidebox' view
+
+   * ``order``: int used to control order within a section. When not specified, automatically set according to order in which tags are added.
+
 
-   :limit:
-      boolean telling if the results should be limited according to the
-      configuration
+Keys for relations only:
+
+   * ``label``: label for the relations section or side box
+
+   * ``showlabel``: boolean telling whether the label is displayed
+
+   * ``limit``: boolean telling if the results should be limited. If so, a link to all results is displayed
+
+   * ``filter``: callback taking the related result set as argument and returning it filtered
 
-   :filter:
-      callback taking the related result set as argument and returning it
-      filtered
+.. sourcecode:: python
+
+   # in ``CWUser`` primary view, display ``created_by`` relations in relations section
+   uicfg.primaryview_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations')
 
-   :order:
-      int used to control order within a section. When not specified,
-      automatically set according to order in which tags are added.
+   # displays this relation as a list, sets the label, limits the number of results and filters on comments
+   uicfg.primaryview_display_ctrl.tag_object_of(
+       ('*', 'created_by', 'CWUser'),
+       {'vid': 'list', 'label': _('latest comment(s):'), 'limit': True,
+        'filter': lambda rset: rset.filtered_rset(lambda x: x.e_schema == 'Comment')})
 
-   Notice those values are only considered if the relation is in a displayed
-   section (controlled by :attr:`primaryview_section`)
+.. warning:: with the ``primaryview_display_ctrl`` rtag, the subject or the object of the relation is ignored for respectively ``tag_object_of`` or  ``tag_subject_of``. To avoid warnings during execution, they should be set to ``'*'``.
 
 
 Index view configuration
 ````````````````````````
 :indexview_etype_section:
-   entity type category in the index/manage page. May be one of
-   * 'application'
-   * 'system'
-   * 'schema'
-   * 'subobject' (not displayed by default)
+   entity type category in the index/manage page. May be one of:
+      * ``application``
+      * ``system``
+      * ``schema``
+      * ``subobject`` (not displayed by default)
 
 
 Actions box configuration
@@ -57,50 +115,70 @@
   simple boolean relation tags used to control the "add entity" submenu.
   Relations whose rtag is True will appears, other won't.
 
+.. sourcecode:: python
+
+   # Adds all subjects of the entry_of relation in the add menu of the ``Blog`` primary view
+   uicfg.actionbox_appearsin_addmenu.tag_object_of(('*', 'entry_of', 'Blog'), True)
+
+
 
 Automatic form configuration
 ````````````````````````````
-:autoform_section:
-   where to display a relation in entity form, according to form type.
-   `tag_attribute`, `tag_subject_of` and `tag_object_of` methods for this
-    relation tags expect two arguments additionaly to the relation key: a
-   `formtype` and a `section`.
+
+Attributes/relations display location
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``uicfg.autoform_section`` specifies where to display a relation in creation/edition entity form for a given form type.
+``tag_attribute``, ``tag_subject_of`` and ``tag_object_of`` methods for this
+relation tag expect two arguments additionally to the relation key: a
+``formtype`` and a ``section``.
 
-   formtype may be one of:
-   * 'main', the main entity form
-   * 'inlined', the form for an entity inlined into another's one
-   * 'muledit', the multiple entity (table) form
+formtype may be one of:
+   * ``main``, the main entity form (via the modify action)
+   * ``inlined``, the form for an entity inlined into another form
+   * ``muledit``, the table form to edit multiple entities
 
-   section may be one of:
-   * 'hidden', don't display
-   * 'attributes', display in the attributes section
-   * 'relations', display in the relations section, using the generic relation
+section may be one of:
+   * ``hidden``, don't display
+   * ``attributes``, display in the attributes section
+   * ``relations``, display in the relations section, using the generic relation
      selector combobox (available in main form only, and not for attribute
      relation)
-   * 'inlined', display target entity of the relation in an inlined form
+   * ``inlined``, display target entity of the relation in an inlined form
      (available in main form only, and not for attribute relation)
-   * 'metadata', display in a special metadata form (NOT YET IMPLEMENTED,
+   * ``metadata``, display in a special metadata form (NOT YET IMPLEMENTED,
      subject to changes)
 
-:autoform_field:
-  specify a custom field instance to use for a relation
+By default, mandatory relations are displayed in the ``attributes`` section, others in ``relations`` section.
 
-:autoform_field_kwargs:
-  specify a dictionnary of arguments to give to the field constructor for a
-  relation. You usually want to use either `autoform_field` or
-  `autoform_field_kwargs`, not both. The later won't have any effect if the
-  former is specified for a relation.
+Change default fields
+^^^^^^^^^^^^^^^^^^^^^
 
-:autoform_permissions_overrides:
+Use ``autoform_field`` to replace the default field type of an attribute.
 
-  provide a way to by-pass security checking for dark-corner case where it can't
-  be verified properly. XXX documents.
+.. warning: ``autoform_field_kwargs`` should usually be used instead of ``autoform_field``. Do not use both methods for the same relation!
 
 
-:organization: Logilab
-:copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
-:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses
+Customize field options
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to customize field options (see :class:`cubicweb.web.formfields.Field` for a detailed list of options), use ``autoform_field_kwargs``. This rtag takes a relation triplet and a dictionary as arguments.
+
+.. sourcecode:: python
+
+   # Change the content of the combobox
+   # here ``ticket_done_in_choices`` is a function which returns a list of elements to populate the combobox
+   uicfg.autoform_field_kwargs.tag_subject_of(('Ticket', 'done_in', '*'), {'sort': False,
+                                                  'choices': ticket_done_in_choices})
+
+
+
+Overriding permissions
+^^^^^^^^^^^^^^^^^^^^^^
+
+``autoform_permissions_overrides`` provides a way to by-pass security checking for dark-corner case where it can't
+be verified properly. XXX documents.
+
 """
 __docformat__ = "restructuredtext en"
 
--- a/web/views/actions.py	Wed Mar 17 11:36:47 2010 +0100
+++ b/web/views/actions.py	Wed Mar 17 11:37:47 2010 +0100
@@ -8,6 +8,8 @@
 __docformat__ = "restructuredtext en"
 _ = unicode
 
+from warnings import warn
+
 from cubicweb.schema import display_name
 from cubicweb.appobject import objectify_selector
 from cubicweb.selectors import (EntitySelector, yes,
--- a/web/views/autoform.py	Wed Mar 17 11:36:47 2010 +0100
+++ b/web/views/autoform.py	Wed Mar 17 11:37:47 2010 +0100
@@ -9,6 +9,8 @@
 __docformat__ = "restructuredtext en"
 _ = unicode
 
+from warnings import warn
+
 from simplejson import dumps
 
 from logilab.mtconverter import xml_escape
--- a/web/views/editcontroller.py	Wed Mar 17 11:36:47 2010 +0100
+++ b/web/views/editcontroller.py	Wed Mar 17 11:37:47 2010 +0100
@@ -7,6 +7,8 @@
 """
 __docformat__ = "restructuredtext en"
 
+from warnings import warn
+
 from rql.utils import rqlvar_maker
 
 from logilab.common.textutils import splitstrip