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 three sections where attributes and relations can be displayed (represented in pink in the image above):
- ‘attributes’
- ‘relations’
- ‘sideboxes’
- Attributes can only be displayed in the attributes section (default
- behavior). They can also be hidden. By default, attributes of type Password and Bytes are hidden.
For instance, to hide the title
attribute of the Blog
entity:
from cubicweb.web.views 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 objecttag_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
pv_section = uicfg.primaryview_section
# hide every relation `entry_of` in the `Blog` primary view
pv_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden')
# display `entry_of` relations in the `relations`
# section in the `BlogEntry` primary view
pv_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’ viewrelations
section: ‘autolimited’ viewsideboxes
section: ‘sidebox’ view
- If
order
: int used to control order within a section. When not specified, automatically set according to order in which tags are added.label
: label for the relations section or side boxshowlabel
: boolean telling whether the label is displayed
# let us remind the schema of a blog entry
class BlogEntry(EntityType):
title = String(required=True, fulltextindexed=True, maxsize=256)
publish_date = Date(default='TODAY')
content = String(required=True, fulltextindexed=True)
entry_of = SubjectRelation('Blog', cardinality='?*')
# now, we want to show attributes
# with an order different from that in the schema definition
view_ctrl = uicfg.primaryview_display_ctrl
for index, attr in enumerate('title', 'content', 'publish_date'):
view_ctrl.tag_attribute(('BlogEntry', attr), {'order': index})
By default, relations displayed in the ‘relations’ section are being displayed by the ‘autolimited’ view. This view will use comma separated values, or list view and/or limit your rset if there is too much items in it (and generate the “view all” link in this case).
You can control this view by setting the following values in the primaryview_display_ctrl relation tag:
- limit, maximum number of entities to display. The value of the ‘navigation.related-limit’ cwproperty is used by default (which is 8 by default). If None, no limit.
- use_list_limit, number of entities until which they should be display as a list (eg using the ‘list’ view). Below that limit, the ‘csv’ view is used. If None, display using ‘csv’ anyway.
- subvid, the subview identifier (eg view that should be used of each item in the list)
Notice you can also use the filter key to set up a callback taking the related result set as argument and returning it filtered, to do some arbitrary filtering that can’t be done using rql for instance.
pv_section = uicfg.primaryview_section
# in `CWUser` primary view, display `created_by`
# relations in relations section
pv_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations')
# display this relation as a list, sets the label,
# limit the number of results and filters on comments
def filter_comment(rset):
return rset.filtered_rset(lambda x: x.e_schema == 'Comment')
pv_ctrl = uicfg.primaryview_display_ctrl
pv_ctrl.tag_object_of(('*', 'created_by', 'CWUser'),
{'vid': 'list', 'label': _('latest comment(s):'),
'limit': True,
'filter': filter_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
'*'
.
Public API of the PrimaryView class¶
-
class
cubicweb.web.views.primary.
PrimaryView
(req=None, rset=None, **kwargs)[source]¶ The basic layout of a primary view is as in the Layout section. This layout is actually drawn by the render_entity method.
The methods you may want to modify while customizing a
PrimaryView
are:-
render_entity_title
(entity)[source]¶ Renders the entity title, by default using entity’s
dc_title()
method.
-
render_entity_attributes
(entity)[source]¶ Renders all attributes and relations in the ‘attributes’ section.
-
render_side_boxes
(boxes)[source]¶ Renders side boxes on the right side of the content. This will generate a box for each relation in the ‘sidebox’ section, as well as explicit box appobjects selectable in this context.
The placement of relations in the relations section or in side boxes can be controlled through the Primary view configuration mechanism.
This method is applicable only for entity type implementing the interface IPrevNext. This interface is for entities which can be linked to a previous and/or next entity. This method will render the navigation links between entities of this type, either at the top or at the bottom of the page given the context (navcontent{top|bottom}).
Also, please note that by setting the following attributes in your subclass, you can already customize some of the rendering:
show_attr_label
- Renders the attribute label next to the attribute value if set to True. Otherwise, does only display the attribute value.
show_rel_label
- Renders the relation label next to the relation value if set to True. Otherwise, does only display the relation value.
main_related_section
- Renders the relations of the entity if set to True.
A good practice is for you to identify the content of your entity type for which the default rendering does not answer your need so that you can focus on the specific method (from the list above) that needs to be modified. We do not advise you to overwrite
render_entity
unless you want a completely different layout.-
Views that may be used to display an entity’s attribute or relation¶
Yoy may easily the display of an attribute or relation by simply configuring the view using one of primaryview_display_ctrl or reledit_ctrl to use one of the views describled below. For instance:
primaryview_display_ctrl.tag_attribute(('Foo', 'bar'), {'vid': 'attribute'})
-
class
cubicweb.web.views.primary.
AttributeView
(req=None, rset=None, **kwargs)[source]¶ __regid__: attribute This view is generally used to disable the reledit feature. It works on both relations and attributes.
-
class
cubicweb.web.views.primary.
URLAttributeView
(req=None, rset=None, **kwargs)[source]¶ __regid__: urlattr This view will wrap an attribute value (hence expect a string) into an ‘<a>’ HTML tag to display a clickable link.
-
class
cubicweb.web.views.primary.
VerbatimAttributeView
(req=None, rset=None, **kwargs)[source]¶ __regid__: verbatimattr This view will wrap an attribute value into an ‘<pre>’ HTML tag to display arbitrary text where EOL will be respected. It usually make sense for attributes whose value is a multi-lines string where new lines matters.