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

---------------------------------------------------------------

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

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

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

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

you will loose a bunch of functionnality that automatically comes with

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

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

understand the implementation fo the `cell_call` to override specifics

bits of it.

Rendering methods and attributes for ``PrimaryView``

----------------------------------------------------

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

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

modifying.

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

its rendering method

.. sourcecode:: python

    class PrimaryView(EntityView):

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

        __regid__ = 'primary'

        title = _('primary')

        show_attr_label = True

        show_rel_label = True

        skip_none = True

        rsection = uicfg.primaryview_section

        display_ctrl = uicfg.primaryview_display_ctrl

        main_related_section = True

        ...

    def cell_call(self, row, col):

        self.row = row

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

        entity = self.complete_entity(row, col)

        self.render_entity(entity)

    def render_entity(self, entity):

        self.render_entity_title(entity)

        self.render_entity_metadata(entity)

        # entity's attributes and relations, excluding meta data

        # if the entity isn't meta itself

        boxes = self._prepare_side_boxes(entity)

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

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

        self.render_entity_summary(entity)

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

        self.content_navigation_components('navcontenttop')

        self.render_entity_attributes(entity)

        if self.main_related_section:

            self.render_entity_relations(entity)

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

        # side boxes

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

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

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

            if hasattr(self, 'render_side_related'):

                warn('render_side_related is deprecated')

                self.render_side_related(entity, [])

            self.render_side_boxes(boxes)

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

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

        self.content_navigation_components('navcontentbottom')

    ...

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

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

*render_entity_title(self, entity)*

    Renders the entity title based on the assumption that the method

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

*render_entity_metadata(self, entity)*

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

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

*render_entity_attributes(self, entity)*

    Renders all the attribute of an entity with the exception of

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

    attribute controls the display of None valued attributes.

*content_navigation_components(self, context)*

    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 methods 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}).

*render_entity_relations(self, entity)*

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

*render_side_boxes(self, entity, boxes)*

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

    to *render_entity_relations* in addition to render the relations

    in a box.

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

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.

*skip_none*

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

*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 recommand you to

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

boxes handling.

.. XXX talk about uicfg.rdisplay