|
1 |
|
2 .. _Views: |
|
3 |
|
4 Views |
|
5 ----- |
|
6 |
|
7 This chapter aims to describe the concept of a `view` used all along |
|
8 the development of a web application and how it has been implemented |
|
9 in *CubicWeb*. |
|
10 |
|
11 We'll start with a description of the interface providing you with a |
|
12 basic understanding of the available classes and methods, then detail |
|
13 the view selection principle. |
|
14 |
|
15 A `View` is an object responsible for the rendering of data from the |
|
16 model into an end-user consummable form. They typically churn out an |
|
17 XHTML stream, but there are views concerned with email other non-html |
|
18 outputs. |
|
19 |
|
20 Basic class for views |
|
21 ~~~~~~~~~~~~~~~~~~~~~ |
|
22 |
|
23 Class `View` (`cubicweb.view`) |
|
24 ``````````````````````````````` |
|
25 |
|
26 This class is an abstraction of a view class, used as a base class for every |
|
27 renderable object such as views, templates, graphic components, etc. |
|
28 |
|
29 A `View` is instantiated to render a result set or part of a result |
|
30 set. `View` subclasses may be parametrized using the following class |
|
31 attributes: |
|
32 |
|
33 * `templatable` indicates if the view may be embedded in a main |
|
34 template or if it has to be rendered standalone (i.e. pure XML views |
|
35 must not be embedded in the main template of HTML pages) |
|
36 |
|
37 * if the view is not templatable, it should set the `content_type` |
|
38 class attribute to the correct MIME type (text/xhtml being the |
|
39 default) |
|
40 |
|
41 * the `category` attribute may be used in the interface to regroup |
|
42 related view kinds together |
|
43 |
|
44 A view writes to its output stream thanks to its attribute `w` (the |
|
45 append method of an `UStreamIO`, except for binary views). |
|
46 |
|
47 At instantiation time, the standard `_cw` and `cw_rset` attributes are |
|
48 added and the `w` attribute will be set at rendering time. |
|
49 |
|
50 The basic interface for views is as follows (remember that the result |
|
51 set has a tabular structure with rows and columns, hence cells): |
|
52 |
|
53 * `render(**context)`, render the view by calling `call` or |
|
54 `cell_call` depending on the context |
|
55 |
|
56 * `call(**kwargs)`, call the view for a complete result set or null |
|
57 (the default implementation calls `cell_call()` on each cell of the |
|
58 result set) |
|
59 |
|
60 * `cell_call(row, col, **kwargs)`, call the view for a given cell of a |
|
61 result set (`row` and `col` being integers used to access the cell) |
|
62 |
|
63 * `url()`, returns the URL enabling us to get the view with the current |
|
64 result set |
|
65 |
|
66 * `wview(__vid, rset, __fallback_vid=None, **kwargs)`, call the view of |
|
67 identifier `__vid` on the given result set. It is possible to give a |
|
68 fallback view identifier that will be used if the requested view is |
|
69 not applicable to the result set. |
|
70 |
|
71 * `html_headers()`, returns a list of HTML headers to be set by the |
|
72 main template |
|
73 |
|
74 * `page_title()`, returns the title to use in the HTML header `title` |
|
75 |
|
76 Other basic view classes |
|
77 ```````````````````````` |
|
78 Here are some of the subclasses of `View` defined in `cubicweb.common.view` |
|
79 that are more concrete as they relate to data rendering within the application: |
|
80 |
|
81 * `EntityView`, view applying to lines or cell containing an entity (e.g. an eid) |
|
82 * `StartupView`, start view that does not require a result set to apply to |
|
83 * `AnyRsetView`, view applicable to any result set |
|
84 |
|
85 Examples of views class |
|
86 ----------------------- |
|
87 |
|
88 - Using `templatable`, `content_type` and HTTP cache configuration |
|
89 |
|
90 .. sourcecode:: python |
|
91 |
|
92 class RSSView(XMLView): |
|
93 __regid__ = 'rss' |
|
94 title = _('rss') |
|
95 templatable = False |
|
96 content_type = 'text/xml' |
|
97 http_cache_manager = MaxAgeHTTPCacheManager |
|
98 cache_max_age = 60*60*2 # stay in http cache for 2 hours by default |
|
99 |
|
100 |
|
101 - Using a custom selector |
|
102 |
|
103 .. sourcecode:: python |
|
104 |
|
105 class SearchForAssociationView(EntityView): |
|
106 """view called by the edition view when the user asks |
|
107 to search for something to link to the edited eid |
|
108 """ |
|
109 __regid__ = 'search-associate' |
|
110 title = _('search for association') |
|
111 __select__ = one_line_rset() & match_search_state('linksearch') & implements('Any') |
|
112 |
|
113 |
|
114 |
|
115 |
|
116 XML views, binaries views... |
|
117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
118 |
|
119 For views generating other formats than HTML (an image generated dynamically |
|
120 for example), and which can not simply be included in the HTML page generated |
|
121 by the main template (see above), you have to: |
|
122 |
|
123 * set the attribute `templatable` of the class to `False` |
|
124 * set, through the attribute `content_type` of the class, the MIME |
|
125 type generated by the view to `application/octet-stream` or any |
|
126 relevant and more specialised mime type |
|
127 |
|
128 For views dedicated to binary content creation (like dynamically generated |
|
129 images), we have to set the attribute `binary` of the class to `True` (which |
|
130 implies that `templatable == False`, so that the attribute `w` of the view could be |
|
131 replaced by a binary flow instead of unicode). |