1 """This module regroups a set of structures that may be used to configure

     1 #:organization: Logilab

     2 various places of the generated web interface.

     2 #:copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.

     3 #:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr

     4 #:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses

     5 

     6 """This module (``cubicweb.web.uicfg``) regroups a set of structures that may be used to configure

     7 various options of the generated web interface.

     8 

     9 To configure the interface generation, we use ``RelationTag`` objects.

     6 :primaryview_section:

    13 

     7    where to display a relation in primary view. Value may be one of:

    14 If you want to customize the primary view of an entity, overriding the

     8    * 'attributes', display in the attributes section

    15 primary view class may not be necessary. For simple adjustments

     9    * 'relations', display in the relations section (below attributes)

    16 (attributes or relations display locations and styles), a much simpler

    10    * 'sideboxes', display in the side boxes (beside attributes)

    17 way is to use uicfg.

    11    * 'hidden', don't display

    18 

    12 

    19 Attributes/relations display location

    13 :primaryview_display_ctrl:

    20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    14 

    21 

    15    how to display a relation in primary view. Values are dict with some of the

    22 In the primary view, there are 3 sections where attributes and

    16    following keys:

    23 relations can be displayed (represented in pink in the image below):

    17 

    24    * attributes

    18    :vid:

    25    * relations

    19       identifier of a view to use to display the result set. Defaults depends on

    26    * sideboxes

    20       the section:

    27 

    21       * 'attributes' section: 'reledit' view

    28  .. image:: ../../images/primaryview_template.png

    22       * 'relations' section: 'autolimited' view

    29 

    23       * 'sideboxes' section: 'sidebox' view

    30 

    24 

    31 **Attributes** can only be displayed in the attributes section (default behavior). They can also be hidden.

    25    :label:

    32 

    26      label for the relations section or side box

    33 For instance, to hide the ``title`` attribute of the ``Blog`` entity:

    27 

    34 

    28    :limit:

    35 .. sourcecode:: python

    29       boolean telling if the results should be limited according to the

    36 

    30       configuration

    37    from cubicweb.web import uicfg

    31 

    38    uicfg.primaryview_section.tag_attribute(('Blog', 'title'), 'hidden')

    32    :filter:

    39 

    33       callback taking the related result set as argument and returning it

    40 

    34       filtered

    41 **Relations** can be either displayed in one of the three sections or hidden.

    35 

    42 

    36    :order:

    43 For relations, there are two methods:

    37       int used to control order within a section. When not specified,

    44    * ``tag_object_of`` for modifying the primary view of the object

    38       automatically set according to order in which tags are added.

    45    * ``tag_subject_of`` for modifying the primary view of the subject

    39 

    46 

    40    Notice those values are only considered if the relation is in a displayed

    47 These two methods take two arguments:

    41    section (controlled by :attr:`primaryview_section`)

    48    * a triplet ``(subject, relation_name, object)``, where subject or object can be replaced with ``'*'``

    49    * the section name or ``hidden``

    50 

    51 .. sourcecode:: python

    52 

    53    # hide every relation ``entry_of`` in the ``Blog`` primary view

    54    uicfg.primaryview_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden')

    55 

    56    # display ``entry_of`` relations in the ``relations`` section in the ``BlogEntry`` primary view

    57    uicfg.primaryview_section.tag_subject_of(('BlogEntry', 'entry_of', '*'),

    58                                              'relations')

    59 

    60 

    61 Display content

    62 ^^^^^^^^^^^^^^^

    63 

    64 You can use ``primaryview_display_ctrl`` to customize the display of attributes or relations. Values of ``primaryview_display_ctrl`` are dictionaries.

    65 

    66 

    67 Common keys for attributes and relations are:

    68    * ``vid``: specifies the regid of the view for displaying the attribute or the relation.

    69 

    70      If ``vid`` is not specified, the default value depends on the section:

    71        * ``attributes`` section: 'reledit' view

    72        * ``relations`` section: 'autolimited' view

    73        * ``sideboxes`` section: 'sidebox' view

    74 

    75    * ``order``: int used to control order within a section. When not specified, automatically set according to order in which tags are added.

    76 

    77 

    78 Keys for relations only:

    79 

    80    * ``label``: label for the relations section or side box

    81 

    82    * ``showlabel``: boolean telling whether the label is displayed

    83 

    84    * ``limit``: boolean telling if the results should be limited. If so, a link to all results is displayed

    85 

    86    * ``filter``: callback taking the related result set as argument and returning it filtered

    87 

    88 .. sourcecode:: python

    89 

    90    # in ``CWUser`` primary view, display ``created_by`` relations in relations section

    91    uicfg.primaryview_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations')

    92 

    93    # displays this relation as a list, sets the label, limits the number of results and filters on comments

    94    uicfg.primaryview_display_ctrl.tag_object_of(

    95        ('*', 'created_by', 'CWUser'),

    96        {'vid': 'list', 'label': _('latest comment(s):'), 'limit': True,

    97         'filter': lambda rset: rset.filtered_rset(lambda x: x.e_schema == 'Comment')})

    98 

    99 .. 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 ``'*'``.

    47    entity type category in the index/manage page. May be one of

   105    entity type category in the index/manage page. May be one of:

    48    * 'application'

   106       * ``application``

    49    * 'system'

   107       * ``system``

    50    * 'schema'

   108       * ``schema``

    51    * 'subobject' (not displayed by default)

   109       * ``subobject`` (not displayed by default)

    63 :autoform_section:

   127 

    64    where to display a relation in entity form, according to form type.

   128 Attributes/relations display location

    65    `tag_attribute`, `tag_subject_of` and `tag_object_of` methods for this

   129 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    66     relation tags expect two arguments additionaly to the relation key: a

   130 

    67    `formtype` and a `section`.

   131 ``uicfg.autoform_section`` specifies where to display a relation in creation/edition entity form for a given form type.

    68 

   132 ``tag_attribute``, ``tag_subject_of`` and ``tag_object_of`` methods for this

    69    formtype may be one of:

   133 relation tag expect two arguments additionally to the relation key: a

    70    * 'main', the main entity form

   134 ``formtype`` and a ``section``.

    71    * 'inlined', the form for an entity inlined into another's one

   135 

    72    * 'muledit', the multiple entity (table) form

   136 formtype may be one of:

    73 

   137    * ``main``, the main entity form (via the modify action)

    74    section may be one of:

   138    * ``inlined``, the form for an entity inlined into another form

    75    * 'hidden', don't display

   139    * ``muledit``, the table form to edit multiple entities

    76    * 'attributes', display in the attributes section

   140 

    77    * 'relations', display in the relations section, using the generic relation

   141 section may be one of:

   142    * ``hidden``, don't display

   143    * ``attributes``, display in the attributes section

   144    * ``relations``, display in the relations section, using the generic relation

    80    * 'inlined', display target entity of the relation in an inlined form

   147    * ``inlined``, display target entity of the relation in an inlined form

    82    * 'metadata', display in a special metadata form (NOT YET IMPLEMENTED,

   149    * ``metadata``, display in a special metadata form (NOT YET IMPLEMENTED,

    85 :autoform_field:

   152 By default, mandatory relations are displayed in the ``attributes`` section, others in ``relations`` section.

    86   specify a custom field instance to use for a relation

   153 

    87 

   154 Change default fields

    88 :autoform_field_kwargs:

   155 ^^^^^^^^^^^^^^^^^^^^^

    89   specify a dictionnary of arguments to give to the field constructor for a

   156 

    90   relation. You usually want to use either `autoform_field` or

   157 Use ``autoform_field`` to replace the default field type of an attribute.

    91   `autoform_field_kwargs`, not both. The later won't have any effect if the

   158 

    92   former is specified for a relation.

   159 .. warning: ``autoform_field_kwargs`` should usually be used instead of ``autoform_field``. Do not use both methods for the same relation!

    93 

   160 

    94 :autoform_permissions_overrides:

   161 

    95 

   162 Customize field options

    96   provide a way to by-pass security checking for dark-corner case where it can't

   163 ^^^^^^^^^^^^^^^^^^^^^^^

    97   be verified properly. XXX documents.

   164 

    98 

   165 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.

    99 

   166 

   100 :organization: Logilab

   167 .. sourcecode:: python

   101 :copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.

   168 

   102 :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr

   169    # Change the content of the combobox

   103 :license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses

   170    # here ``ticket_done_in_choices`` is a function which returns a list of elements to populate the combobox

   171    uicfg.autoform_field_kwargs.tag_subject_of(('Ticket', 'done_in', '*'), {'sort': False,

   172                                                   'choices': ticket_done_in_choices})

   173 

   174 

   175 

   176 Overriding permissions

   177 ^^^^^^^^^^^^^^^^^^^^^^

   178 

   179 ``autoform_permissions_overrides`` provides a way to by-pass security checking for dark-corner case where it can't

   180 be verified properly. XXX documents.

   181