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.

   204 

   205 Example of customization and creation

   206 -------------------------------------

   207 

   208 We'll show you now an example of a ``primary`` view and how to customize it.

   209 

   210 We continue along the basic tutorial :ref:`tuto_blog`.

   211 

   212 If you want to change the way a ``BlogEntry`` is displayed, just override

   213 the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py``:

   214 

   215 .. sourcecode:: python

   216 

   217   from cubicweb.selectors import implements

   218   from cubicweb.web.views.primary improt Primaryview

   219 

   220   class BlogEntryPrimaryView(PrimaryView):

   221     __select__ = PrimaryView.__select__ & implements('BlogEntry')

   222 

   223       def render_entity_attributes(self, entity):

   224           self.w(u'<p>published on %s</p>' %

   225                  entity.publish_date.strftime('%Y-%m-%d'))

   226           super(BlogEntryPrimaryView, self).render_entity_attributes(entity)

   227 

   228 The above source code defines a new primary view for

   229 ``BlogEntry``. The `id` class attribute is not repeated there since it

   230 is inherited through the `primary.PrimaryView` class.

   231 

   232 The selector for this view chains the selector of the inherited class

   233 with its own specific criterion.

   234 

   235 The view method ``self.w()`` is used to output data. Here `lines

   236 08-09` output HTML for the publication date of the entry.

   237 

   238 .. image:: ../../images/lax-book.09-new-view-blogentry.en.png

   239    :alt: blog entries now look much nicer

   240 

   241 Let us now improve the primary view of a blog

   242 

   243 .. sourcecode:: python

   244 

   245  from logilab.mtconverter import xml_escape

   246  from cubicweb.selectors import implements, one_line_rset

   247  from cubicweb.web.views.primary import Primaryview

   248 

   249  class BlogPrimaryView(PrimaryView):

   250      __regid__ = 'primary'

   251      __select__ = PrimaryView.__select__ & implements('Blog')

   252      rql = 'Any BE ORDERBY D DESC WHERE BE entry_of B, BE publish_date D, B eid %(b)s'

   253 

   254      def render_entity_relations(self, entity):

   255          rset = self._cw.execute(self.rql, {'b' : entity.eid})

   256          for entry in rset.entities():

   257              self.w(u'<p>%s</p>' % entry.view('inblogcontext'))

   258 

   259  class BlogEntryInBlogView(EntityView):

   260      __regid__ = 'inblogcontext'

   261      __select__ = implements('BlogEntry')

   262 

   263      def cell_call(self, row, col):

   264          entity = self.cw_rset.get_entity(row, col)

   265          self.w(u'<a href="%s" title="%s">%s</a>' %

   266                 entity.absolute_url(),

   267                 xml_escape(entity.content[:50]),

   268                 xml_escape(entity.description))

   269 

   270 This happens in two places. First we override the

   271 render_entity_relations method of a Blog's primary view. Here we want

   272 to display our blog entries in a custom way.

   273 

   274 At `line 10`, a simple request is made to build a result set with all

   275 the entities linked to the current ``Blog`` entity by the relationship

   276 ``entry_of``. The part of the framework handling the request knows

   277 about the schema and infers that such entities have to be of the

   278 ``BlogEntry`` kind and retrieves them (in the prescribed publish_date

   279 order).

   280 

   281 The request returns a selection of data called a result set. Result

   282 set objects have an .entities() method returning a generator on

   283 requested entities (going transparently through the `ORM` layer).

   284 

   285 At `line 13` the view 'inblogcontext' is applied to each blog entry to

   286 output HTML. (Note that the 'inblogcontext' view is not defined

   287 whatsoever in *CubicWeb*. You are absolutely free to define whole view

   288 families.) We juste arrange to wrap each blogentry output in a 'p'

   289 html element.

   290 

   291 Next, we define the 'inblogcontext' view. This is NOT a primary view,

   292 with its well-defined sections (title, metadata, attribtues,

   293 relations/boxes). All a basic view has to define is cell_call.

   294 

   295 Since views are applied to result sets which can be tables of data, we

   296 have to recover the entity from its (row,col)-coordinates (`line

   297 20`). Then we can spit some HTML.

   298 

   299 .. warning::

   300 

   301   Be careful: all strings manipulated in *CubicWeb* are actually

   302   unicode strings. While web browsers are usually tolerant to

   303   incoherent encodings they are being served, we should not abuse

   304   it. Hence we have to properly escape our data. The xml_escape()

   305   function has to be used to safely fill (X)HTML elements from Python

   306   unicode strings.

   307 

   308 Assuming we added entries to the blog titled `MyLife`, displaying it

   309 now allows to read its description and all its entries.

   310 

   311 .. image:: ../../images/lax-book.10-blog-with-two-entries.en.png

   312    :alt: a blog and all its entries