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