doc/book/en/B1020-define-views.en.txt
author Sandrine Ribeau <sandrine.ribeau@logilab.fr>
Tue, 23 Dec 2008 13:50:56 -0800
changeset 292 2d9e83c34b23
parent 288 487bcc269d50
child 301 e47150482ac1
permissions -rw-r--r--
[doc] Renaming of part II sub-sections accordingly.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     2
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     3
.. _DefinitionVues:
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     4
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     5
Views definition
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     6
================
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     7
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     8
Basic class for views
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     9
---------------------
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    10
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    11
Class `View` (`cubicweb.common.view`)
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    12
`````````````````````````````````````
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    13
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    14
A view writes in its output exit thanks to its attribute `w` (`UStreamIO`).
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    15
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    16
The basic interface for views is as follows:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    17
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    18
* `dispatch(**context)`, render the view by calling `call` or
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    19
  `cell_call` depending on the given parameters
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    20
* `call(**kwargs)`, call the view for a complete result set or null
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    21
* `cell_call(row, col, **kwargs)`, call the view for a given cell of a result set
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    22
* `url()`, returns the URL enabling us to get the view with the current
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    23
  result set 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    24
* `view(__vid, rset, __fallback_vid=None, **kwargs)`, call the view of identifier 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    25
  `__vid` on the given result set. It is possible to give a view identifier
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    26
  of fallback that will be used if the view requested is not applicable to the
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    27
  result set
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    28
  
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    29
* `wview(__vid, rset, __fallback_vid=None, **kwargs)`, similar to `view` except
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    30
  the flow is automatically passed in the parameters
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    31
  
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    32
* `html_headers()`, returns a list of HTML headers to set by the main template
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    33
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    34
* `page_title()`, returns the title to use in the HTML header `title`
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    35
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    36
* `creator(eid)`, returns the eid and the login of the entity creator of the entity
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    37
  having the eid given in the parameter 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    38
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    39
Other basic classes:
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    40
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    41
* `EntityView`, view applying to lines or cell containing an entity (e.g. an eid)
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    42
* `StartupView`, start view that does not require a result set to apply to
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    43
* `AnyRsetView`, view applied to any result set 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    44
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    45
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    46
The selection view principle
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    47
----------------------------
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    48
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    49
A view includes :
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    50
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    51
- an identifier (all objects in `LAX` are entered in a registry
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    52
  and this identifier will be used as a key)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    53
  
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    54
- a filter to select the resulsets it can be applied to
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    55
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    56
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    57
For a given identifier, multiple views can be defined. `CubicWeb` uses
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    58
a selector which computes scores so that it can identify and select the
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    59
best view to apply in context. The selector library is in 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    60
``cubicweb.common.selector`` and a library of the methods used to
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    61
compute scores is in ``cubicweb.vregistry.vreq``.
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    62
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    63
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    64
`CubicWeb` provides a lot of standard views, for a complete list, you
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    65
will have to read the code in directory ``cubicweb/web/views/`` (XXX
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    66
improve doc).
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    67
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    68
For example, the view named ``primary`` is the one used to display
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    69
a single entity.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    70
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    71
If you want to change the way a ``BlogEntry`` is displayed, just
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    72
override the view ``primary`` in ``BlogDemo/views.py`` ::
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    73
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    74
  01. from ginco.web.views import baseviews
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    75
  02.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    76
  03. class BlogEntryPrimaryView(baseviews.PrimaryView):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    77
  04.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    78
  05.     accepts = ('BlogEntry',)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    79
  06.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    80
  07.     def cell_call(self, row, col):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    81
  08.         entity = self.entity(row, col)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    82
  09.         self.w(u'<h1>%s</h1>' % entity.title)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    83
  10.         self.w(u'<p>published on %s in category %s</p>' % \
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    84
  11.                (entity.publish_date.strftime('%Y-%m-%d'), entity.category))
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    85
  12.         self.w(u'<p>%s</p>' % entity.text)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    86
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    87
The above source code defines a new primary view (`line 03`) for
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    88
``BlogEntry`` (`line 05`). 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    89
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    90
Since views are applied to resultsets and resulsets can be tables of
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    91
data, it is needed to recover the entity from its (row,col)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    92
coordinates (`line 08`). We will get to this in more detail later.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    94
The view has a ``self.w()`` method that is used to output data. Here `lines
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    95
09-12` output HTML tags and values of the entity's attributes.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    96
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    97
When displaying same blog entry as before, you will notice that the
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    98
page is now looking much nicer.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    99
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   100
.. image:: images/lax-book.09-new-view-blogentry.en.png
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   101
   :alt: blog entries now look much nicer
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   102
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   103
Let us now improve the primary view of a blog ::
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   104
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   105
  01. class BlogPrimaryView(baseviews.PrimaryView):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   106
  02. 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   107
  03.     accepts = ('Blog',)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   108
  04.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   109
  05.     def cell_call(self, row, col):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   110
  06.         entity = self.entity(row, col)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   111
  07.         self.w(u'<h1>%s</h1>' % entity.title)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   112
  08.         self.w(u'<p>%s</p>' % entity.description)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   113
  09.         rset = self.req.execute('Any E WHERE E entry_of B, B eid "%s"' % entity.eid)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   114
  10.         self.wview('primary', rset)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   115
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   116
In the above source code, `lines 01-08` are similar to the previous
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   117
view we defined.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   118
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   119
At `line 09`, a simple request in made to build a resultset with all
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   120
the entities linked to the current ``Blog`` entity by the relationship
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   121
``entry_of``. The part of the framework handling the request knows
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   122
about the schema and infer that such entities have to be of the
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   123
``BlogEntry`` kind and retrieves them.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   124
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   125
The request returns a selection of data called a resultset. At 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   126
`line 10` the view 'primary' is applied to this resultset to output
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   127
HTML. 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   128
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   129
**This is to be compared to interfaces and protocols in object-oriented
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   130
languages. Applying a given view to all the entities of a resultset only
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   131
requires the availability, for each entity of this resultset, of a
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   132
view with that name that can accepts the entity.**
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   133
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   134
Assuming we added entries to the blog titled `MyLife`, displaying it
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   135
now allows to read its description and all its entries.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   136
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   137
.. image:: images/lax-book.10-blog-with-two-entries.en.png
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   138
   :alt: a blog and all its entries
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   139
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   140
**Before we move forward, remember that the selection/view principle is
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   141
at the core of `CubicWeb`. Everywhere in the engine, data is requested
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   142
using the RQL language, then HTML/XML/text/PNG is output by applying a
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   143
view to the resultset returned by the query. That is where most of the
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   144
flexibility comes from.**
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   145
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   146
[WRITE ME]
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   147
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   148
* implementing interfaces, calendar for blog entries
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   149
* show that a calendar view can export data to ical
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   150
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   151
We will implement the cubicwweb.interfaces.ICalendarable interfaces on
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   152
entities.BloEntry and apply the OneMonthCalendar and iCalendar views
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   153
to resultsets like "Any E WHERE E is BlogEntry"
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   154
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   155
* create view "blogentry table" with title, publish_date, category
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   156
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   157
We will show that by default the view that displays 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   158
"Any E,D,C WHERE E publish_date D, E category C" is the table view.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   159
Of course, the same can be obtained by calling
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   160
self.wview('table',rset)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   161
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   162
* in view blog, select blogentries and apply view "blogentry table"
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   163
* demo ajax by filtering blogentry table on category
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   164
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   165
we did the same with 'primary', but with tables we can turn on filters
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   166
and show that ajax comes for free.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   167
[FILLME]
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   168
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   169
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   170
Templates
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   171
---------
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   172
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   173
*Templates* are specific view that does not depend on a result set. The basic
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   174
class `Template` (`cubicweb.common.view`) is derived from the class `View`.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   175
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   176
To build a HTML page, a *main template* is used. In general, the template of
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   177
identifier `main` is the one (it is not used in case an error is raised or for
229
767ff7f5d5a7 [doc] Replace all : s/by example/for example/
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   178
the login form for example). This template uses other templates in addition
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   179
to the views which depends on the content to generate the HTML page to return.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   180
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   181
A *template* is responsible for:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   182
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   183
1. executing RQL query of data to render if necessarry
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   184
2. identifying the view to use to render data if it is not specified
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   185
3. composing the HTML page to return
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   186
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   187
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   188
The default main template (`cubicweb.web.views.basetemplates.TheMainTemplate`)
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   189
------------------------------------------------------------------------------
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   190
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   191
The default main template build the page based on the following pattern:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   192
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   193
.. image:: images/main_template_layout.png
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   194
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   195
The rectangle containing `view.dispathc()` represents the area where the content
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   196
view has to be displayed. The others represents sub-templates called to complete
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   197
the page. A default implementation of those is provided in 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   198
`cubicweb.views.basetemplates`. You can, of course, overload those sub-templates
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   199
to implement your own customization of the HTML page.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   200
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   201
We can also control certain aspects of the main template thanks to the following
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   202
forms parameters:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   203
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   204
* `__notemplate`, if present (whatever the value assigned), only the content view
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   205
  is returned
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   206
* `__force_display`, if present and its value is not null, no navigation 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   207
  whatever the number of entities to display
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   208
* `__method`, if the result set to render contains only one entity and this 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   209
  parameter is set, it refers to a method to call on the entity by passing it
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   210
  the dictionnary of the forms parameters, before going the classic way (through
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   211
  step 1 and 2 described juste above)
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   212
292
2d9e83c34b23 [doc] Renaming of part II sub-sections accordingly.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 288
diff changeset
   213
.. include:: B1021-views-stdlib.en.txt
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   214
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   215
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   216
XML views, binaries...
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   217
----------------------
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   218
For the views generating other formats that HTML (an image generated dynamically
229
767ff7f5d5a7 [doc] Replace all : s/by example/for example/
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   219
for example), and which can not usually be included in the HTML page generated
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   220
by the main template (see above), you have to:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   221
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   222
* set the atribute `templatable` of the class to `False`
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   223
* set, through the attribute `content_type` of the class, the MIME type generated
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   224
  by the view to `application/octet-stream`
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   225
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   226
For the views dedicated to binary content creation (an image dynamically generated
229
767ff7f5d5a7 [doc] Replace all : s/by example/for example/
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   227
for example), we have to set the attribute `binary` of the class to `True` (which
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   228
implies that `templateable == False`, so that the attribute `w` of the view could be
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   229
replaced by a binary flow instead of unicode).
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   230
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   231
(X)HTML tricks to apply
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   232
-----------------------
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   233
229
767ff7f5d5a7 [doc] Replace all : s/by example/for example/
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   234
Some web browser (Firefox for example) are not happy with empty `<div>`
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   235
(by empty we mean that there is no content in the tag, but there
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   236
could be attributes), so we should always use `<div></div>` even if
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   237
it is empty and not use `<div/>`.
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   238