diff -r 02b52bf9f5f8 -r 0865e1e90674 web/uicfg.py --- a/web/uicfg.py Wed Mar 24 10:23:31 2010 +0100 +++ b/web/uicfg.py Wed Apr 28 11:54:13 2010 +0200 @@ -1,108 +1,30 @@ -#: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. +# copyright 2003-2010 LOGILAB S.A. (Paris, FRANCE), all rights reserved. +# contact http://www.logilab.fr/ -- mailto:contact@logilab.fr +# +# This file is part of CubicWeb. +# +# CubicWeb is free software: you can redistribute it and/or modify it under the +# terms of the GNU Lesser General Public License as published by the Free +# Software Foundation, either version 2.1 of the License, or (at your option) +# any later version. +# +# logilab-common is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more +# details. +# +# You should have received a copy of the GNU Lesser General Public License along +# with CubicWeb. If not, see . +"""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 -`````````````````````````` - -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. - -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. - -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') - - # 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. - - -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. - - -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 - -.. sourcecode:: python - - # in ``CWUser`` primary view, display ``created_by`` relations in relations section - uicfg.primaryview_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations') - - # 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')}) - -.. 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`` @@ -117,68 +39,11 @@ .. sourcecode:: python - # Adds all subjects of the entry_of relation in the add menu of the ``Blog`` primary view + # 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 -```````````````````````````` - -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 (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 - selector combobox (available in main form only, and not for attribute - relation) - * ``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, - subject to changes) - -By default, mandatory relations are displayed in the ``attributes`` section, others in ``relations`` section. - -Change default fields -^^^^^^^^^^^^^^^^^^^^^ - -Use ``autoform_field`` to replace the default field type of an attribute. - -.. warning: ``autoform_field_kwargs`` should usually be used instead of ``autoform_field``. Do not use both methods for the same relation! - - -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"