--- a/web/uicfg.py Wed Mar 17 09:21:58 2010 +0100
+++ b/web/uicfg.py Wed Mar 17 09:58:37 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"