1 .. _primary:

     2 

     3 The default 'primary' view (:mod:`cubicweb.web.views.primary`)

     4 ---------------------------------------------------------------

     5 

     6 The primary view of an entity is the view called by default when a single

     7 entity is in the result set and needs to be displayed.

     8 

     9 This view is supposed to render a maximum of informations about the entity.

    10 

    11 Beware when overriding this top level `cell_call` in a primary because

    12 you will loose a bunch of functionnality that automatically comes with

    13 it : `in-context` boxes, related boxes, some navigation, some

    14 displaying of the metadata, etc. It might be interresting to

    15 understand the implementation fo the `cell_call` to override specifics

    16 bits of it.

    17 

    18 Rendering methods and attributes for ``PrimaryView``

    19 ----------------------------------------------------

    20 

    21 By default, *CubicWeb* provides a primary view for every available

    22 entity type. This is the first view you might be interested in

    23 modifying.

    24 

    25 Let's have a quick look at the EntityView ``PrimaryView`` as well as

    26 its rendering method

    27 

    28 .. sourcecode:: python

    29 

    30     class PrimaryView(EntityView):

    31         """the full view of an non final entity"""

    32         __regid__ = 'primary'

    33         title = _('primary')

    34         show_attr_label = True

    35         show_rel_label = True

    36         skip_none = True

    37         rsection = uicfg.primaryview_section

    38         display_ctrl = uicfg.primaryview_display_ctrl

    39         main_related_section = True

    40 

    41         ...

    42 

    43     def cell_call(self, row, col):

    44         self.row = row

    45         self.maxrelated = self._cw.property_value('navigation.related-limit')

    46         entity = self.complete_entity(row, col)

    47         self.render_entity(entity)

    48 

    49     def render_entity(self, entity):

    50         self.render_entity_title(entity)

    51         self.render_entity_metadata(entity)

    52         # entity's attributes and relations, excluding meta data

    53         # if the entity isn't meta itself

    54         boxes = self._prepare_side_boxes(entity)

    55         if boxes or hasattr(self, 'render_side_related'):

    56             self.w(u'<table width="100%"><tr><td style="width: 75%">')

    57         self.render_entity_summary(entity)

    58         self.w(u'<div class="mainInfo">')

    59         self.content_navigation_components('navcontenttop')

    60         self.render_entity_attributes(entity)

    61         if self.main_related_section:

    62             self.render_entity_relations(entity)

    63         self.w(u'</div>')

    64         # side boxes

    65         if boxes or hasattr(self, 'render_side_related'):

    66             self.w(u'</td><td>')

    67             self.w(u'<div class="primaryRight">')

    68             if hasattr(self, 'render_side_related'):

    69                 warn('render_side_related is deprecated')

    70                 self.render_side_related(entity, [])

    71             self.render_side_boxes(boxes)

    72             self.w(u'</div>')

    73             self.w(u'</td></tr></table>')

    74         self.content_navigation_components('navcontentbottom')

    75 

    76     ...

    77 

    78 ``cell_call`` is executed for each entity of a result set.

    79 

    80 The methods you want to modify while customizing a ``PrimaryView`` are:

    81 

    82 *render_entity_title(self, entity)*

    83     Renders the entity title based on the assumption that the method

    84     ``def dc_title(self)`` is implemented for the given entity type.

    85 

    86 *render_entity_metadata(self, entity)*

    87     Renders the entity metadata by calling the 'metadata' view on the

    88     entity. This generic view is in cubicweb.views.baseviews.

    89 

    90 *render_entity_attributes(self, entity)*

    91     Renders all the attribute of an entity with the exception of

    92     attribute of type `Password` and `Bytes`. The skip_none class

    93     attribute controls the display of None valued attributes.

    94 

    95 *content_navigation_components(self, context)*

    96     This method is applicable only for entity type implementing the interface

    97     `IPrevNext`. This interface is for entities which can be linked to a previous

    98     and/or next entity. This methods will render the navigation links between

    99     entities of this type, either at the top or at the bottom of the page

   100     given the context (navcontent{top|bottom}).

   101 

   102 *render_entity_relations(self, entity)*

   103     Renders all the relations of the entity in the main section of the page.

   104 

   105 *render_side_boxes(self, entity, boxes)*

   106     Renders all the relations of the entity in a side box. This is equivalent

   107     to *render_entity_relations* in addition to render the relations

   108     in a box.

   109 

   110 Also, please note that by setting the following attributes in your class,

   111 you can already customize some of the rendering:

   112 

   113 *show_attr_label*

   114     Renders the attribute label next to the attribute value if set to True.

   115     Otherwise, does only display the attribute value.

   116 

   117 *show_rel_label*

   118     Renders the relation label next to the relation value if set to True.

   119     Otherwise, does only display the relation value.

   120 

   121 *skip_none*

   122     Does not render an attribute value that is None if set to True.

   123 

   124 *main_related_section*

   125     Renders the relations of the entity if set to True.

   126 

   127 A good practice is for you to identify the content of your entity type for which

   128 the default rendering does not answer your need so that you can focus on the specific

   129 method (from the list above) that needs to be modified. We do not recommand you to

   130 overwrite ``render_entity`` as you might potentially loose the benefits of the side

   131 boxes handling.

   132 

   133 .. XXX talk about uicfg.rdisplay