Configuring the user interface

Relation tags

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.

# display ``entry_of`` relations in the ``relations`` section in the ``BlogEntry`` primary view
uicfg.primaryview_section.tag_subject_of(('BlogEntry', 'entry_of', '*'),

# 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

The uicfg module


The part of uicfg that deals with primary views is in the Primary view configuration chapter.

This module (cubicweb.web.views.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.

Index view configuration


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

  • application
  • system
  • schema
  • subobject (not displayed by default)

By default only entities on the application category are shown.

from cubicweb.web.views import uicfg
# force hiding
uicfg.indexview_etype_section['HideMe'] = 'subobject'
# force display
uicfg.indexview_etype_section['ShowMe'] = 'application'

Actions box configuration

 simple boolean relation tags used to control the “add entity” submenu. Relations whose rtag is True will appears, other won’t.
# 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)

The uihelper module

This module provide highlevel helpers to avoid uicfg boilerplate for most common tasks such as fields ordering, widget customization, etc.

Here are a few helpers to customize action box rendering:

cubicweb.web.uihelper.append_to_addmenu(*args, **kwargs)
cubicweb.web.uihelper.remove_from_addmenu(*args, **kwargs)

and a few other ones for form configuration:

cubicweb.web.uihelper.set_fields_order(*args, **kwargs)
cubicweb.web.uihelper.hide_field(*args, **kwargs)
cubicweb.web.uihelper.hide_fields(*args, **kwargs)
cubicweb.web.uihelper.set_field_kwargs(*args, **kwargs)
cubicweb.web.uihelper.set_field(*args, **kwargs)
cubicweb.web.uihelper.edit_inline(*args, **kwargs)
cubicweb.web.uihelper.edit_as_attr(*args, **kwargs)
cubicweb.web.uihelper.set_muledit_editable(*args, **kwargs)

The module also provides a FormConfig base class that lets you gather uicfg declaration in the scope of a single class, which can sometimes be clearer to read than a bunch of sequential function calls.

class cubicweb.web.uihelper.FormConfig[source]

helper base class to define uicfg rules on a given entity type.

In all descriptions below, attributes list can either be a list of attribute names of a list of 2-tuples (relation name, role of the edited entity in the relation).


which entity type the form config is for. This attribute is mandatory
the formtype the class tries toc customize (i.e. main, inlined, or muledit), default is main.
the list of attributes or relations to hide.
the list of attributes to edit in the attributes section.
the list of attributes to edit in the inlined section.
the list of attributes to edit, in the desired order. Unspecified fields will be displayed after specified ones, their order being consistent with the schema definition.
a dictionary mapping attribute names to widget instances.
a dictionary mapping attribute names to field instances.
an instance of cubicweb.web.uicfg.AutoformSectionRelationTags Default is None, meaning cubicweb.web.uicfg.autoform_section is used.
an instance of cubicweb.web.uicfg.AutoformFieldTags Default is None, meaning cubicweb.web.uicfg.autoform_field is used.
an instance of cubicweb.web.uicfg.AutoformFieldKwargsTags Default is None, meaning cubicweb.web.uicfg.autoform_field_kwargs is used.


from cubicweb.web import uihelper, formwidgets as fwdgs

class LinkFormConfig(uihelper.FormConfig):
    etype = 'Link'
    hidden = ('title', 'description', 'embed')
    widgets = dict(

class UserFormConfig(uihelper.FormConfig):
    etype = 'CWUser'
    hidden = ('login',)
    rels_as_attrs = ('in_group',)
    fields_order = ('firstname', 'surname', 'in_group', 'use_email')
    inlined = ('use_email',)

Table Of Contents

Previous topic

Online documentation system

Next topic