|
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 :class:`~cubicweb.view.View` |
|
36 `````````````````````````````````` |
|
37 |
|
38 .. autoclass:: cubicweb.view.View |
|
39 |
|
40 The basic interface for views is as follows (remember that the result |
|
41 set has a tabular structure with rows and columns, hence cells): |
|
42 |
|
43 * `render(**context)`, render the view by calling `call` or |
|
44 `cell_call` depending on the context |
|
45 |
|
46 * `call(**kwargs)`, call the view for a complete result set or null |
|
47 (the default implementation calls `cell_call()` on each cell of the |
|
48 result set) |
|
49 |
|
50 * `cell_call(row, col, **kwargs)`, call the view for a given cell of a |
|
51 result set (`row` and `col` being integers used to access the cell) |
|
52 |
|
53 * `url()`, returns the URL enabling us to get the view with the current |
|
54 result set |
|
55 |
|
56 * `wview(__vid, rset, __fallback_vid=None, **kwargs)`, call the view of |
|
57 identifier `__vid` on the given result set. It is possible to give a |
|
58 fallback view identifier that will be used if the requested view is |
|
59 not applicable to the result set. |
|
60 |
|
61 * `html_headers()`, returns a list of HTML headers to be set by the |
|
62 main template |
|
63 |
|
64 * `page_title()`, returns the title to use in the HTML header `title` |
|
65 |
|
66 Other basic view classes |
|
67 ```````````````````````` |
|
68 Here are some of the subclasses of :class:`~cubicweb.view.View` defined in :mod:`cubicweb.view` |
|
69 that are more concrete as they relate to data rendering within the application: |
|
70 |
|
71 .. autoclass:: cubicweb.view.EntityView |
|
72 .. autoclass:: cubicweb.view.StartupView |
|
73 .. autoclass:: cubicweb.view.EntityStartupView |
|
74 .. autoclass:: cubicweb.view.AnyRsetView |
|
75 |
|
76 Examples of views class |
|
77 ``````````````````````` |
|
78 |
|
79 - Using `templatable`, `content_type` and HTTP cache configuration |
|
80 |
|
81 .. sourcecode:: python |
|
82 |
|
83 class RSSView(XMLView): |
|
84 __regid__ = 'rss' |
|
85 title = _('rss') |
|
86 templatable = False |
|
87 content_type = 'text/xml' |
|
88 http_cache_manager = MaxAgeHTTPCacheManager |
|
89 cache_max_age = 60*60*2 # stay in http cache for 2 hours by default |
|
90 |
|
91 |
|
92 - Using a custom selector |
|
93 |
|
94 .. sourcecode:: python |
|
95 |
|
96 class SearchForAssociationView(EntityView): |
|
97 """view called by the edition view when the user asks |
|
98 to search for something to link to the edited eid |
|
99 """ |
|
100 __regid__ = 'search-associate' |
|
101 title = _('search for association') |
|
102 __select__ = one_line_rset() & match_search_state('linksearch') & is_instance('Any') |
|
103 |
|
104 |
|
105 XML views, binaries views... |
|
106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
107 |
|
108 For views generating other formats than HTML (an image generated dynamically |
|
109 for example), and which can not simply be included in the HTML page generated |
|
110 by the main template (see above), you have to: |
|
111 |
|
112 * set the attribute `templatable` of the class to `False` |
|
113 * set, through the attribute `content_type` of the class, the MIME |
|
114 type generated by the view to `application/octet-stream` or any |
|
115 relevant and more specialised mime type |
|
116 |
|
117 For views dedicated to binary content creation (like dynamically generated |
|
118 images), we have to set the attribute `binary` of the class to `True` (which |
|
119 implies that `templatable == False`, so that the attribute `w` of the view could be |
|
120 replaced by a binary flow instead of unicode). |