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.