doc/book/en/development/devweb/views/primary.rst
author Aurelien Campeas <aurelien.campeas@logilab.fr>
Thu, 15 Apr 2010 10:58:21 +0200
branchstable
changeset 5266 84f285d96363
parent 5262 doc/book/en/development/webstdlib/primary.rst@ebd90d2a5639
child 5312 d2dbba898a96
permissions -rw-r--r--
[doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5262
diff changeset
     1
.. _primary_view:
4936
a4b772a0d801 Fixed some of the documentation warnings when building the book with sphinx.
Adrien Chauve <adrien.chauve@logilab.fr>
parents: 4751
diff changeset
     2
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
     3
The Primary View
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
     4
-----------------
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
     5
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
     6
(:mod:`cubicweb.web.views.primary`)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     7
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
     8
By default, *CubicWeb* provides a view that fits every available
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
     9
entity type. This is the first view you might be interested in
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    10
modifying. It is also one of the richest and most complex.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    11
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    12
It is automatically selected on a one line result set containing an
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    13
entity.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    14
5222
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
    15
This view is supposed to render a maximum of informations about the
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
    16
entity.
4430
0b6a069eb29e le patch added_tips a été importé
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3258
diff changeset
    17
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    18
.. _primary_view_layout:
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    19
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    20
Layout
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    21
``````
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    22
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    23
The primary view has the following layout.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    24
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5262
diff changeset
    25
.. image:: ../../../images/primaryview_template.png
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    26
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    27
.. _primary_view_configuration:
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    28
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    29
Primary view configuration
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    30
``````````````````````````
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    31
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    32
If you want to customize the primary view of an entity, overriding the primary
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    33
view class may not be necessary. For simple adjustments (attributes or relations
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    34
display locations and styles), a much simpler way is to use uicfg.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    35
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    36
Attributes/relations display location
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    37
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    38
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    39
In the primary view, there are 3 sections where attributes and
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    40
relations can be displayed (represented in pink in the image above):
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    41
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    42
* attributes
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    43
* relations
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    44
* sideboxes
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    45
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    46
**Attributes** can only be displayed in the attributes section (default
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    47
  behavior). They can also be hidden.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    48
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    49
For instance, to hide the ``title`` attribute of the ``Blog`` entity:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    50
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    51
.. sourcecode:: python
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    52
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    53
   from cubicweb.web import uicfg
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    54
   uicfg.primaryview_section.tag_attribute(('Blog', 'title'), 'hidden')
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    55
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    56
**Relations** can be either displayed in one of the three sections or hidden.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    57
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    58
For relations, there are two methods:
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    59
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    60
* ``tag_object_of`` for modifying the primary view of the object
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    61
* ``tag_subject_of`` for modifying the primary view of the subject
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    62
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    63
These two methods take two arguments:
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    64
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    65
* a triplet ``(subject, relation_name, object)``, where subject or object can be replaced with ``'*'``
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    66
* the section name or ``hidden``
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    67
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    68
.. sourcecode:: python
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    69
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    70
   pv_section = uicfg.primaryview_section
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    71
   # hide every relation `entry_of` in the `Blog` primary view
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    72
   pv_section.tag_object_of(('*', 'entry_of', 'Blog'), 'hidden')
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    73
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    74
   # display `entry_of` relations in the `relations`
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    75
   # section in the `BlogEntry` primary view
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    76
   pv_section.tag_subject_of(('BlogEntry', 'entry_of', '*'), 'relations')
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    77
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    78
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    79
Display content
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    80
^^^^^^^^^^^^^^^
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    81
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    82
You can use ``primaryview_display_ctrl`` to customize the display of attributes
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    83
or relations. Values of ``primaryview_display_ctrl`` are dictionaries.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    84
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    85
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    86
Common keys for attributes and relations are:
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    87
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    88
* ``vid``: specifies the regid of the view for displaying the attribute or the relation.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    89
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    90
  If ``vid`` is not specified, the default value depends on the section:
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    91
    * ``attributes`` section: 'reledit' view
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    92
    * ``relations`` section: 'autolimited' view
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    93
    * ``sideboxes`` section: 'sidebox' view
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    94
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    95
* ``order``: int used to control order within a section. When not specified,
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    96
  automatically set according to order in which tags are added.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    97
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    98
.. sourcecode:: python
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
    99
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   100
   # let us remind the schema of a blog entry
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   101
   class BlogEntry(EntityType):
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   102
       title = String(required=True, fulltextindexed=True, maxsize=256)
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   103
       publish_date = Date(default='TODAY')
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   104
       content = String(required=True, fulltextindexed=True)
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   105
       entry_of = SubjectRelation('Blog', cardinality='?*')
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   106
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   107
   # now, we want to show attributes
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   108
   # with an order different from that in the schema definition
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   109
   view_ctrl = uicfg.primaryview_display_ctrl
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   110
   for index, attr in enumerate('title', 'content', 'publish_date'):
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   111
       view_ctrl.tag_attribute(('BlogEntry', attr), {'order': index})
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   112
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   113
Keys for relations only:
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   114
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   115
* ``label``: label for the relations section or side box
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   116
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   117
* ``showlabel``: boolean telling whether the label is displayed
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   118
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   119
* ``limit``: boolean telling if the results should be limited. If so, a link to all results is displayed
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   120
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   121
* ``filter``: callback taking the related result set as argument and returning it filtered
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   122
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   123
.. sourcecode:: python
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   124
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   125
   pv_section = uicfg.primaryview_section
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   126
   # in `CWUser` primary view, display `created_by`
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   127
   # relations in relations section
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   128
   pv_section.tag_object_of(('*', 'created_by', 'CWUser'), 'relations')
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   129
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   130
   # display this relation as a list, sets the label,
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   131
   # limit the number of results and filters on comments
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   132
   def filter_comment(rset):
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   133
       return rset.filtered_rset(lambda x: x.e_schema == 'Comment')
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   134
   pv_ctrl = uicfg.primaryview_display_ctrl
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   135
   pv_ctrl.tag_object_of(('*', 'created_by', 'CWUser'),
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   136
                         {'vid': 'list', 'label': _('latest comment(s):'),
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   137
                          'limit': True,
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   138
                          'filter': filter_comment})
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   139
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   140
.. warning:: with the ``primaryview_display_ctrl`` rtag, the subject or the
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   141
   object of the relation is ignored for respectively ``tag_object_of`` or
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   142
   ``tag_subject_of``. To avoid warnings during execution, they should be set to
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   143
   ``'*'``.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   144
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   145
Rendering methods and attributes
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   146
````````````````````````````````
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   147
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   148
The basic layout of a primary view is as in the
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   149
:ref:`primary_view_layout` section. This layout is actually drawn by
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   150
the `render_entity` method.
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   151
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   152
The methods you may want to modify while customizing a ``PrimaryView``
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   153
are:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   154
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   155
*render_entity_title(self, entity)*
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   156
    Renders the entity title using the ``def dc_title(self)`` method.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   157
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   158
*render_entity_metadata(self, entity)*
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   159
    Renders the entity metadata by calling the ``metadata`` view on the
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2545
diff changeset
   160
    entity. This generic view is in cubicweb.views.baseviews.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   161
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2545
diff changeset
   162
*render_entity_attributes(self, entity)*
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2545
diff changeset
   163
    Renders all the attribute of an entity with the exception of
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2545
diff changeset
   164
    attribute of type `Password` and `Bytes`. The skip_none class
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2545
diff changeset
   165
    attribute controls the display of None valued attributes.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   166
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2545
diff changeset
   167
*render_entity_relations(self, entity)*
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   168
    Renders all the relations of the entity in the main section of the page.
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   169
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2545
diff changeset
   170
*render_side_boxes(self, entity, boxes)*
5222
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   171
    Renders relations of the entity in a side box.
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   172
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   173
The placement of relations in the relations section or in side boxes
5227
ed1c138299f2 [doc/book] primary view section enhancements
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5222
diff changeset
   174
can be controlled through the :ref:`primary_view_configuration` mechanism.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   175
5222
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   176
*content_navigation_components(self, context)*
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   177
    This method is applicable only for entity type implementing the interface
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   178
    `IPrevNext`. This interface is for entities which can be linked to a previous
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   179
    and/or next entity. This method will render the navigation links between
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   180
    entities of this type, either at the top or at the bottom of the page
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   181
    given the context (navcontent{top|bottom}).
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   182
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   183
Also, please note that by setting the following attributes in your
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   184
subclass, you can already customize some of the rendering:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   185
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   186
*show_attr_label*
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   187
    Renders the attribute label next to the attribute value if set to True.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   188
    Otherwise, does only display the attribute value.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   189
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   190
*show_rel_label*
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   191
    Renders the relation label next to the relation value if set to True.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   192
    Otherwise, does only display the relation value.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   193
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   194
*skip_none*
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   195
    Does not render an attribute value that is None if set to True.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   196
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   197
*main_related_section*
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   198
    Renders the relations of the entity if set to True.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   199
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   200
A good practice is for you to identify the content of your entity type for which
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   201
the default rendering does not answer your need so that you can focus on the specific
5222
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   202
method (from the list above) that needs to be modified. We do not advise you to
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4936
diff changeset
   203
overwrite ``render_entity`` unless you want a completely different layout.
5262
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   204
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   205
Example of customization and creation
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   206
-------------------------------------
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   207
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   208
We'll show you now an example of a ``primary`` view and how to customize it.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   209
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   210
We continue along the basic tutorial :ref:`tuto_blog`.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   211
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   212
If you want to change the way a ``BlogEntry`` is displayed, just override
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   213
the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py``:
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   214
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   215
.. sourcecode:: python
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   216
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   217
  from cubicweb.selectors import implements
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   218
  from cubicweb.web.views.primary improt Primaryview
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   219
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   220
  class BlogEntryPrimaryView(PrimaryView):
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   221
    __select__ = PrimaryView.__select__ & implements('BlogEntry')
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   222
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   223
      def render_entity_attributes(self, entity):
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   224
          self.w(u'<p>published on %s</p>' %
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   225
                 entity.publish_date.strftime('%Y-%m-%d'))
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   226
          super(BlogEntryPrimaryView, self).render_entity_attributes(entity)
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   227
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   228
The above source code defines a new primary view for
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   229
``BlogEntry``. The `id` class attribute is not repeated there since it
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   230
is inherited through the `primary.PrimaryView` class.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   231
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   232
The selector for this view chains the selector of the inherited class
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   233
with its own specific criterion.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   234
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   235
The view method ``self.w()`` is used to output data. Here `lines
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   236
08-09` output HTML for the publication date of the entry.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   237
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5262
diff changeset
   238
.. image:: ../../../images/lax-book.09-new-view-blogentry.en.png
5262
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   239
   :alt: blog entries now look much nicer
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   240
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   241
Let us now improve the primary view of a blog
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   242
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   243
.. sourcecode:: python
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   244
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   245
 from logilab.mtconverter import xml_escape
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   246
 from cubicweb.selectors import implements, one_line_rset
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   247
 from cubicweb.web.views.primary import Primaryview
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   248
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   249
 class BlogPrimaryView(PrimaryView):
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   250
     __regid__ = 'primary'
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   251
     __select__ = PrimaryView.__select__ & implements('Blog')
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   252
     rql = 'Any BE ORDERBY D DESC WHERE BE entry_of B, BE publish_date D, B eid %(b)s'
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   253
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   254
     def render_entity_relations(self, entity):
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   255
         rset = self._cw.execute(self.rql, {'b' : entity.eid})
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   256
         for entry in rset.entities():
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   257
             self.w(u'<p>%s</p>' % entry.view('inblogcontext'))
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   258
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   259
 class BlogEntryInBlogView(EntityView):
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   260
     __regid__ = 'inblogcontext'
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   261
     __select__ = implements('BlogEntry')
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   262
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   263
     def cell_call(self, row, col):
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   264
         entity = self.cw_rset.get_entity(row, col)
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   265
         self.w(u'<a href="%s" title="%s">%s</a>' %
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   266
                entity.absolute_url(),
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   267
                xml_escape(entity.content[:50]),
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   268
                xml_escape(entity.description))
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   269
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   270
This happens in two places. First we override the
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   271
render_entity_relations method of a Blog's primary view. Here we want
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   272
to display our blog entries in a custom way.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   273
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   274
At `line 10`, a simple request is made to build a result set with all
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   275
the entities linked to the current ``Blog`` entity by the relationship
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   276
``entry_of``. The part of the framework handling the request knows
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   277
about the schema and infers that such entities have to be of the
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   278
``BlogEntry`` kind and retrieves them (in the prescribed publish_date
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   279
order).
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   280
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   281
The request returns a selection of data called a result set. Result
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   282
set objects have an .entities() method returning a generator on
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   283
requested entities (going transparently through the `ORM` layer).
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   284
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   285
At `line 13` the view 'inblogcontext' is applied to each blog entry to
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   286
output HTML. (Note that the 'inblogcontext' view is not defined
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   287
whatsoever in *CubicWeb*. You are absolutely free to define whole view
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   288
families.) We juste arrange to wrap each blogentry output in a 'p'
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   289
html element.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   290
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   291
Next, we define the 'inblogcontext' view. This is NOT a primary view,
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   292
with its well-defined sections (title, metadata, attribtues,
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   293
relations/boxes). All a basic view has to define is cell_call.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   294
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   295
Since views are applied to result sets which can be tables of data, we
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   296
have to recover the entity from its (row,col)-coordinates (`line
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   297
20`). Then we can spit some HTML.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   298
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   299
.. warning::
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   300
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   301
  Be careful: all strings manipulated in *CubicWeb* are actually
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   302
  unicode strings. While web browsers are usually tolerant to
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   303
  incoherent encodings they are being served, we should not abuse
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   304
  it. Hence we have to properly escape our data. The xml_escape()
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   305
  function has to be used to safely fill (X)HTML elements from Python
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   306
  unicode strings.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   307
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   308
Assuming we added entries to the blog titled `MyLife`, displaying it
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   309
now allows to read its description and all its entries.
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   310
5266
84f285d96363 [doc/book] regroup views chapters under common umbrella (in the development part) & some fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5262
diff changeset
   311
.. image:: ../../../images/lax-book.10-blog-with-two-entries.en.png
5262
ebd90d2a5639 [doc/book] move a big chunk of primary view customisation example in the primary view chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5227
diff changeset
   312
   :alt: a blog and all its entries