# HG changeset patch # User Sylvain Thénault # Date 1268822267 -3600 # Node ID 0dfd86d2cd987a0a9d38c3a6b213f1ff5a28fd27 # Parent 433174d9394fcdeb90a2cea7a00192097c81942b# Parent dce5ebe5d598f86841f7f1f5cd74084705b0b988 backport stable diff -r 433174d9394f -r 0dfd86d2cd98 doc/book/en/development/devweb/rtags.rst --- 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: + diff -r 433174d9394f -r 0dfd86d2cd98 doc/book/en/images/primaryview_template.png Binary file doc/book/en/images/primaryview_template.png has changed diff -r 433174d9394f -r 0dfd86d2cd98 doc/book/en/images/primaryview_template.svg --- /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 @@ + + + diff -r 433174d9394f -r 0dfd86d2cd98 rtags.py --- 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" diff -r 433174d9394f -r 0dfd86d2cd98 web/uicfg.py --- 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" diff -r 433174d9394f -r 0dfd86d2cd98 web/views/actions.py --- 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, diff -r 433174d9394f -r 0dfd86d2cd98 web/views/autoform.py --- 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 diff -r 433174d9394f -r 0dfd86d2cd98 web/views/editcontroller.py --- 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