doc/book/en/B1020-define-views.en.txt
author Sandrine Ribeau <sandrine.ribeau@logilab.fr>
Tue, 14 Apr 2009 17:18:32 -0700
changeset 1355 8a3102fb4760
parent 1280 ebf1d748ed5a
child 1411 cb4b9d48977e
child 1588 79755c89b4f3
permissions -rw-r--r--
[doc] Adds description and example of TreeMixIn.
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
1249
905d76e38433 [doc] improve view explanation
Emile Anclin <emile.anclin@logilab.fr>
parents: 1191
diff changeset
     3
.. _ViewDefinition:
93
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
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
     8
This chapter aims to describe the concept of a `view` used all along
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
     9
the development of a web application and how it has been implemented
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    10
in `CubicWeb`.
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    11
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    12
We'll start with a description of the interface providing you with a basic
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    13
understanding of the classes and methods available, then detail the view
316
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
    14
selection principle which makes `CubicWeb` web interface very flexible.
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    15
1355
8a3102fb4760 [doc] Adds description and example of TreeMixIn.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 1280
diff changeset
    16
A `View` is an object applied to another object such as an entity.
8a3102fb4760 [doc] Adds description and example of TreeMixIn.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 1280
diff changeset
    17
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    18
Basic class for views
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    19
---------------------
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    20
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    21
Class `View` (`cubicweb.common.view`)
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    22
`````````````````````````````````````
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    23
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    24
This class is an abstraction of a view class, used as a base class for every
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    25
renderable object such as views, templates, graphic components, etc.
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    26
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    27
A `View` is instantiated to render a result set or part of a result set. `View`
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    28
subclasses may be parametrized using the following class attributes:
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    29
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    30
    * `templatable` indicates if the view may be embeded in a main
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    31
      template or if it has to be rendered standalone (i.e. XML views
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    32
      must not be embeded in the main template for HTML pages)
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    33
    * if the view is not templatable, it should set the `content_type` class
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    34
      attribute to the correct MIME type (text/xhtml by default)
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    35
    * the `category` attribute may be used in the interface to regroup related
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    36
      objects together
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    37
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    38
At instantiation time, the standard `req`, `rset`, and `cursor`
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    39
attributes are added and the `w` attribute will be set at rendering
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    40
time.
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    41
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    42
A view writes to its output stream thanks to its attribute `w` (`UStreamIO`).
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    43
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    44
The basic interface for views is as follows (remember that the result set has a
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    45
tabular structure with rows and columns, hence cells):
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    46
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    47
* `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
    48
  `cell_call` depending on the given parameters
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    49
* `call(**kwargs)`, call the view for a complete result set or null (default 
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
    50
  implementation calls `cell_call()` on each cell of the result set)
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    51
* `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
    52
* `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
    53
  result set 
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    54
* `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
    55
  `__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
    56
  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
    57
  result set
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    58
  
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    59
* `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
    60
  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
    61
  
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    62
* `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
    63
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    64
* `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
    65
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    66
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
    67
Other basic view classes
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
    68
````````````````````````
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    69
Here are some of the subclasses of `View` defined in `cubicweb.common.view`
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
    70
that are more concrete as they relate to data rendering within the application:
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    71
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    72
* `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
    73
* `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
    74
* `AnyRsetView`, view applied to any result set 
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    75
* `EmptyRsetView`, view applied to an empty result set
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    76
1280
ebf1d748ed5a [doc] Registerers are deprecated; little improvement
Emile Anclin <emile.anclin@logilab.fr>
parents: 1253
diff changeset
    77
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    78
The selection view principle
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    79
----------------------------
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    80
316
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
    81
A view is essentially defined by:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    82
306
1ed1da008e50 [doc] Removes references to LAX.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 301
diff changeset
    83
- an identifier (all objects in `CubicWeb` are entered in a registry
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    84
  and this identifier will be used as a key). This is defined in the class
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
    85
  attribute ``id``.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    86
  
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
    87
- a filter to select the result sets it can be applied to. This is defined in
316
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
    88
  the class attribute ``__selectors__``, which expects a tuple of selectors
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
    89
  as its value.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    90
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    91
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    92
For a given identifier, multiple views can be defined. `CubicWeb` uses
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
    93
a selector which computes scores to identify and select the
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
    94
best view to apply in the given context. The selectors library is in 
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    95
``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
    96
compute scores is in ``cubicweb.vregistry.vreq``.
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
    97
316
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
    98
.. include:: B1021-views-selectors.en.txt
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
    99
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   100
Registerer
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   101
``````````
1280
ebf1d748ed5a [doc] Registerers are deprecated; little improvement
Emile Anclin <emile.anclin@logilab.fr>
parents: 1253
diff changeset
   102
[Registerers are deprecated: they will soon disappear for explicite 
ebf1d748ed5a [doc] Registerers are deprecated; little improvement
Emile Anclin <emile.anclin@logilab.fr>
parents: 1253
diff changeset
   103
registration...] 
ebf1d748ed5a [doc] Registerers are deprecated; little improvement
Emile Anclin <emile.anclin@logilab.fr>
parents: 1253
diff changeset
   104
316
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   105
A view is also customizable through its attribute ``__registerer__``.
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   106
This is used at the time the application is launched to manage how
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   107
objects (views, graphic components, actions, etc.) 
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   108
are registered in the `cubicWeb` registry.
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   109
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   110
A `registerer` can, for example, identify when we register an 
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   111
object that is equivalent to an already registered object, which
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   112
could happen when we define two `primary` views for an entity type.
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   113
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   114
The purpose of a `registerer` is to control object registry
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   115
at the application startup whereas `selectors` control objects
316
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   116
when they are selected for display.
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   117
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   118
316
99943acb44af [doc] Add sub-section about selectors and a little about registerer in views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 309
diff changeset
   119
.. include:: B1022-views-stdlib.en.txt
306
1ed1da008e50 [doc] Removes references to LAX.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 301
diff changeset
   120
318
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   121
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   122
Examples of views class 
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   123
-----------------------
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   124
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   125
- Using the attribute `templatable`
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   126
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   127
  ::
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   128
    
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   129
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   130
    class RssView(XmlView):
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   131
        id = 'rss'
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   132
        title = _('rss')
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   133
        templatable = False
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   134
        content_type = 'text/xml'
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   135
        http_cache_manager = MaxAgeHTTPCacheManager
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   136
        cache_max_age = 60*60*2 # stay in http cache for 2 hours by default
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   137
    
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   138
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   139
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   140
- Using the attribute `__selectors__`
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   141
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   142
  ::
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   143
    
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   144
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   145
    class SearchForAssociationView(EntityView):
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   146
        """view called by the edition view when the user asks
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   147
        to search for something to link to the edited eid
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   148
        """
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   149
        id = 'search-associate'
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   150
        title = _('search for association')
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   151
        __selectors__ = (one_line_rset, match_search_state, accept_selector)
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   152
        accepts = ('Any',)
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   153
        search_states = ('linksearch',)
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   154
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   155
    
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   156
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   157
6cb74102d611 [doc] Add a little to views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 316
diff changeset
   158
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
   159
Example of a view customization
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
   160
-------------------------------
306
1ed1da008e50 [doc] Removes references to LAX.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 301
diff changeset
   161
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
   162
We'll show you now an example of a ``primary`` view and how to customize it.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   163
309
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
   164
If you want to change the way a ``BlogEntry`` is displayed, just override 
7067c97cb182 [doc] minor text improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 308
diff changeset
   165
the method ``cell_call()`` of the view ``primary`` in ``BlogDemo/views.py`` ::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   166
1191
216141cf47a3 remove all erudi and ginco occurences in the doc
Emile Anclin <emile.anclin@logilab.fr>
parents: 318
diff changeset
   167
  01. from cubicweb.web.views import baseviews
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   168
  02.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   169
  03. class BlogEntryPrimaryView(baseviews.PrimaryView):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   170
  04.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   171
  05.     accepts = ('BlogEntry',)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   172
  06.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   173
  07.     def cell_call(self, row, col):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   174
  08.         entity = self.entity(row, col)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   175
  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
   176
  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
   177
  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
   178
  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
   179
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   180
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
   181
``BlogEntry`` (`line 05`). 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   182
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   183
Since views are applied to result sets which can be tables of
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   184
data, we have to recover the entity from its (row,col)-coordinates (`line 08`).
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   185
We will get to this in more detail later.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   186
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   187
The view method ``self.w()`` is used to output data. Here `lines
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   188
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
   189
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   190
When displaying the same blog entry as before, you will notice that the
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   191
page is now looking much nicer. [FIXME: it is not clear to what this refers.]
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/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
   194
   :alt: blog entries now look much nicer
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   195
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   196
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
   197
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   198
  01. class BlogPrimaryView(baseviews.PrimaryView):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   199
  02. 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   200
  03.     accepts = ('Blog',)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   201
  04.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   202
  05.     def cell_call(self, row, col):
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   203
  06.         entity = self.entity(row, col)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   204
  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
   205
  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
   206
  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
   207
  10.         self.wview('primary', rset)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   208
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   209
In the above source code, `lines 01-08` are similar to the previous
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   210
view we defined. [FIXME: defined where ?]
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   211
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   212
At `line 09`, a simple request is made to build a result set with all
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   213
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
   214
``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
   215
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
   216
``BlogEntry`` kind and retrieves them.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   217
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   218
The request returns a selection of data called a result set. At 
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   219
`line 10` the view 'primary' is applied to this result set to output
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   220
HTML. 
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   221
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   222
**This is to be compared to interfaces and protocols in object-oriented
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   223
languages. Applying a given view called 'a_view' to all the entities
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   224
of a result set only requires to have for each entity of this result set,
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   225
an available view called 'a_view' which accepts the entity.**
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   226
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   227
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
   228
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
   229
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   230
.. 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
   231
   :alt: a blog and all its entries
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   232
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   233
**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
   234
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
   235
using the RQL language, then HTML/XML/text/PNG is output by applying a
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   236
view to the result set returned by the query. That is where most of the
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   237
flexibility comes from.**
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   238
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   239
[WRITE ME]
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   240
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   241
* implementing interfaces, calendar for blog entries
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   242
* 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
   243
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
   244
We will implement the `cubicweb.interfaces.ICalendarable` interfaces on
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
   245
entities.BlogEntry and apply the OneMonthCalendar and iCalendar views
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   246
to result sets like "Any E WHERE E is BlogEntry"
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   247
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   248
* 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
   249
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   250
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
   251
"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
   252
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
   253
self.wview('table',rset)
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   254
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   255
* 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
   256
* 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
   257
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   258
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
   259
and show that ajax comes for free.
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   260
[FILLME]
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   261
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   262
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   263
Templates
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   264
---------
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   265
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   266
*Templates* are specific views that do not depend on a result set. The basic
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   267
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
   268
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   269
To build a HTML page, a *main template* is used. In general, the template of
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
   270
identifier `main` is the one to use (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
   271
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
   272
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
   273
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   274
A *template* is responsible for:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   275
301
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 292
diff changeset
   276
1. executing RQL query of data to render if necessary
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   277
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
   278
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
   279
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
   280
You will find out more about templates in :ref:`templates`. 
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   281
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   282
XML views, binaries...
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   283
----------------------
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   284
For views generating other formats than HTML (an image generated dynamically
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   285
for example), and which can not simply 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
   286
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
   287
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   288
* set the attribute `templatable` of the class to `False`
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   289
* 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
   290
  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
   291
1253
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   292
For views dedicated to binary content creation (like dynamically generated 
9716a9f77980 [doc] some improvements on Views
Emile Anclin <emile.anclin@logilab.fr>
parents: 1249
diff changeset
   293
images), we have to set the attribute `binary` of the class to `True` (which
308
73a352526577 [doc] Improvement to the Views chapter. Moved content about the main template in the Templates chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 306
diff changeset
   294
implies that `templatable == False`, so that the attribute `w` of the view could be
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   295
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
   296
102
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   297
(X)HTML tricks to apply
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   298
-----------------------
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   299
229
767ff7f5d5a7 [doc] Replace all : s/by example/for example/
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   300
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
   301
(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
   302
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
   303
it is empty and not use `<div/>`.
ef84f6b2e4cf [doc] Initial translation of views chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
   304