1 .. _primary: |
|
2 |
|
3 The Primary View |
|
4 ----------------- |
|
5 |
|
6 (:mod:`cubicweb.web.views.primary`) |
|
7 |
|
8 By default, *CubicWeb* provides a view that fits every available |
|
9 entity type. This is the first view you might be interested in |
|
10 modifying. It is also one of the richest and most complex. |
|
11 |
|
12 It is automatically selected on a one line result set containing an |
|
13 entity. |
|
14 |
|
15 This view is supposed to render a maximum of informations about the |
|
16 entity. |
|
17 |
|
18 .. _primary_view_layout: |
|
19 |
|
20 Layout |
|
21 `````` |
|
22 |
|
23 The primary view has the following layout. |
|
24 |
|
25 .. image:: ../../images/primaryview_template.png |
|
26 |
|
27 .. _primary_view_configuration: |
|
28 |
|
29 Primary view configuration |
|
30 `````````````````````````` |
|
31 |
|
32 If you want to customize the primary view of an entity, overriding the primary |
|
33 view class may not be necessary. For simple adjustments (attributes or relations |
|
34 display locations and styles), a much simpler way is to use uicfg. |
|
35 |
|
36 Attributes/relations display location |
|
37 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
38 |
|
39 In the primary view, there are 3 sections where attributes and |
|
40 relations can be displayed (represented in pink in the image above): |
|
41 |
|
42 * attributes |
|
43 * relations |
|
44 * sideboxes |
|
45 |
|
46 **Attributes** can only be displayed in the attributes section (default |
|
47 behavior). They can also be hidden. |
|
48 |
|
49 For instance, to hide the ``title`` attribute of the ``Blog`` entity: |
|
50 |
|
51 .. sourcecode:: python |
|
52 |
|
53 from cubicweb.web import uicfg |
|
54 uicfg.primaryview_section.tag_attribute(('Blog', 'title'), 'hidden') |
|
55 |
|
56 **Relations** can be either displayed in one of the three sections or hidden. |
|
57 |
|
58 For relations, there are two methods: |
|
59 |
|
60 * ``tag_object_of`` for modifying the primary view of the object |
|
61 * ``tag_subject_of`` for modifying the primary view of the subject |
|
62 |
|
63 These two methods take two arguments: |
|
64 |
|
65 * a triplet ``(subject, relation_name, object)``, where subject or object can be replaced with ``'*'`` |
|
66 * the section name or ``hidden`` |
|
67 |
|
68 .. sourcecode:: python |
|
69 |
|
70 pv_section = uicfg.primaryview_section |
|
71 # hide every relation `entry_of` in the `Blog` primary view |
|
72 pv_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden') |
|
73 |
|
74 # display `entry_of` relations in the `relations` |
|
75 # section in the `BlogEntry` primary view |
|
76 pv_section.tag_subject_of(('BlogEntry', 'entry_of', '*'), 'relations') |
|
77 |
|
78 |
|
79 Display content |
|
80 ^^^^^^^^^^^^^^^ |
|
81 |
|
82 You can use ``primaryview_display_ctrl`` to customize the display of attributes |
|
83 or relations. Values of ``primaryview_display_ctrl`` are dictionaries. |
|
84 |
|
85 |
|
86 Common keys for attributes and relations are: |
|
87 |
|
88 * ``vid``: specifies the regid of the view for displaying the attribute or the relation. |
|
89 |
|
90 If ``vid`` is not specified, the default value depends on the section: |
|
91 * ``attributes`` section: 'reledit' view |
|
92 * ``relations`` section: 'autolimited' view |
|
93 * ``sideboxes`` section: 'sidebox' view |
|
94 |
|
95 * ``order``: int used to control order within a section. When not specified, |
|
96 automatically set according to order in which tags are added. |
|
97 |
|
98 .. sourcecode:: python |
|
99 |
|
100 # let us remind the schema of a blog entry |
|
101 class BlogEntry(EntityType): |
|
102 title = String(required=True, fulltextindexed=True, maxsize=256) |
|
103 publish_date = Date(default='TODAY') |
|
104 content = String(required=True, fulltextindexed=True) |
|
105 entry_of = SubjectRelation('Blog', cardinality='?*') |
|
106 |
|
107 # now, we want to show attributes |
|
108 # with an order different from that in the schema definition |
|
109 view_ctrl = uicfg.primaryview_display_ctrl |
|
110 for index, attr in enumerate('title', 'content', 'publish_date'): |
|
111 view_ctrl.tag_attribute(('BlogEntry', attr), {'order': index}) |
|
112 |
|
113 Keys for relations only: |
|
114 |
|
115 * ``label``: label for the relations section or side box |
|
116 |
|
117 * ``showlabel``: boolean telling whether the label is displayed |
|
118 |
|
119 * ``limit``: boolean telling if the results should be limited. If so, a link to all results is displayed |
|
120 |
|
121 * ``filter``: callback taking the related result set as argument and returning it filtered |
|
122 |
|
123 .. sourcecode:: python |
|
124 |
|
125 pv_section = uicfg.primaryview_section |
|
126 # in `CWUser` primary view, display `created_by` |
|
127 # relations in relations section |
|
128 pv_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations') |
|
129 |
|
130 # display this relation as a list, sets the label, |
|
131 # limit the number of results and filters on comments |
|
132 def filter_comment(rset): |
|
133 return rset.filtered_rset(lambda x: x.e_schema == 'Comment') |
|
134 pv_ctrl = uicfg.primaryview_display_ctrl |
|
135 pv_ctrl.tag_object_of(('*', 'created_by', 'CWUser'), |
|
136 {'vid': 'list', 'label': _('latest comment(s):'), |
|
137 'limit': True, |
|
138 'filter': filter_comment}) |
|
139 |
|
140 .. warning:: with the ``primaryview_display_ctrl`` rtag, the subject or the |
|
141 object of the relation is ignored for respectively ``tag_object_of`` or |
|
142 ``tag_subject_of``. To avoid warnings during execution, they should be set to |
|
143 ``'*'``. |
|
144 |
|
145 Rendering methods and attributes |
|
146 ```````````````````````````````` |
|
147 |
|
148 The basic layout of a primary view is as in the |
|
149 :ref:`primary_view_layout` section. This layout is actually drawn by |
|
150 the `render_entity` method. |
|
151 |
|
152 The methods you may want to modify while customizing a ``PrimaryView`` |
|
153 are: |
|
154 |
|
155 *render_entity_title(self, entity)* |
|
156 Renders the entity title using the ``def dc_title(self)`` method. |
|
157 |
|
158 *render_entity_metadata(self, entity)* |
|
159 Renders the entity metadata by calling the ``metadata`` view on the |
|
160 entity. This generic view is in cubicweb.views.baseviews. |
|
161 |
|
162 *render_entity_attributes(self, entity)* |
|
163 Renders all the attribute of an entity with the exception of |
|
164 attribute of type `Password` and `Bytes`. The skip_none class |
|
165 attribute controls the display of None valued attributes. |
|
166 |
|
167 *render_entity_relations(self, entity)* |
|
168 Renders all the relations of the entity in the main section of the page. |
|
169 |
|
170 *render_side_boxes(self, entity, boxes)* |
|
171 Renders relations of the entity in a side box. |
|
172 |
|
173 The placement of relations in the relations section or in side boxes |
|
174 can be controlled through the :ref:`primary_view_configuration` mechanism. |
|
175 |
|
176 *content_navigation_components(self, context)* |
|
177 This method is applicable only for entity type implementing the interface |
|
178 `IPrevNext`. This interface is for entities which can be linked to a previous |
|
179 and/or next entity. This method will render the navigation links between |
|
180 entities of this type, either at the top or at the bottom of the page |
|
181 given the context (navcontent{top|bottom}). |
|
182 |
|
183 Also, please note that by setting the following attributes in your |
|
184 subclass, you can already customize some of the rendering: |
|
185 |
|
186 *show_attr_label* |
|
187 Renders the attribute label next to the attribute value if set to True. |
|
188 Otherwise, does only display the attribute value. |
|
189 |
|
190 *show_rel_label* |
|
191 Renders the relation label next to the relation value if set to True. |
|
192 Otherwise, does only display the relation value. |
|
193 |
|
194 *skip_none* |
|
195 Does not render an attribute value that is None if set to True. |
|
196 |
|
197 *main_related_section* |
|
198 Renders the relations of the entity if set to True. |
|
199 |
|
200 A good practice is for you to identify the content of your entity type for which |
|
201 the default rendering does not answer your need so that you can focus on the specific |
|
202 method (from the list above) that needs to be modified. We do not advise you to |
|
203 overwrite ``render_entity`` unless you want a completely different layout. |
|