|
1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 .. _templates: |
|
4 |
|
5 Templates |
|
6 ========= |
|
7 |
|
8 Templates are the entry point for the |cubicweb| view system. As seen |
|
9 in :ref:`views_base_class`, there are two kinds of views: the |
|
10 templatable and non-templatable. |
|
11 |
|
12 |
|
13 Non-templatable views |
|
14 --------------------- |
|
15 |
|
16 Non-templatable views are standalone. They are responsible for all the details |
|
17 such as setting a proper content type (or mime type), the proper document |
|
18 headers, namespaces, etc. Examples are pure xml views such as RSS or Semantic Web |
|
19 views (`SIOC`_, `DOAP`_, `FOAF`_, `Linked Data`_, etc.), and views which generate |
|
20 binary files (pdf, excel files, etc.) |
|
21 |
|
22 .. _`SIOC`: http://sioc-project.org/ |
|
23 .. _`DOAP`: http://trac.usefulinc.com/doap |
|
24 .. _`FOAF`: http://www.foaf-project.org/ |
|
25 .. _`Linked Data`: http://linkeddata.org/ |
|
26 |
|
27 |
|
28 To notice that a view is not templatable, you just have to set the |
|
29 view's class attribute `templatable` to `False`. In this case, it |
|
30 should set the `content_type` class attribute to the correct MIME |
|
31 type. By default, it is text/xhtml. Additionally, if your view |
|
32 generate a binary file, you have to set the view's class attribute |
|
33 `binary` to `True` too. |
|
34 |
|
35 |
|
36 Templatable views |
|
37 ----------------- |
|
38 |
|
39 Templatable views are not concerned with such pesky details. They |
|
40 leave it to the template. Conversely, the template's main job is to: |
|
41 |
|
42 * set up the proper document header and content type |
|
43 * define the general layout of a document |
|
44 * invoke adequate views in the various sections of the document |
|
45 |
|
46 |
|
47 Look at :mod:`cubicweb.web.views.basetemplates` and you will find the base |
|
48 templates used to generate (X)HTML for your application. The most important |
|
49 template there is :class:`~cubicweb.web.views.basetemplates.TheMainTemplate`. |
|
50 |
|
51 .. _the_main_template_layout: |
|
52 |
|
53 TheMainTemplate |
|
54 ~~~~~~~~~~~~~~~ |
|
55 |
|
56 .. _the_main_template_sections: |
|
57 |
|
58 Layout and sections |
|
59 ``````````````````` |
|
60 |
|
61 A page is composed as indicated on the schema below : |
|
62 |
|
63 .. image:: ../../images/main_template.png |
|
64 |
|
65 The sections dispatches specific views: |
|
66 |
|
67 * `header`: the rendering of the header is delegated to the |
|
68 `htmlheader` view, whose default implementation can be found in |
|
69 ``basetemplates.py`` and which does the following things: |
|
70 |
|
71 * inject the favicon if there is one |
|
72 * inject the global style sheets and javascript resources |
|
73 * call and display a link to an rss component if there is one available |
|
74 |
|
75 it also sets up the page title, and fills the actual |
|
76 `header` section with top-level components, using the `header` view, which: |
|
77 |
|
78 * tries to display a logo, the name of the application and the `breadcrumbs` |
|
79 * provides a login status area |
|
80 * provides a login box (hiden by default) |
|
81 |
|
82 * `left column`: this is filled with all selectable boxes matching the |
|
83 `left` context (there is also a right column but nowadays it is |
|
84 seldom used due to bad usability) |
|
85 |
|
86 * `contentcol`: this is the central column; it is filled with: |
|
87 |
|
88 * the `rqlinput` view (hidden by default) |
|
89 * the `applmessages` component |
|
90 * the `contentheader` view which in turns dispatches all available |
|
91 content navigation components having the `navtop` context (this |
|
92 is used to navigate through entities implementing the IPrevNext |
|
93 interface) |
|
94 * the view that was given as input to the template's `call` |
|
95 method, also dealing with pagination concerns |
|
96 * the `contentfooter` |
|
97 |
|
98 * `footer`: adds all footer actions |
|
99 |
|
100 .. note:: |
|
101 |
|
102 How and why a view object is given to the main template is explained |
|
103 in the :ref:`publisher` chapter. |
|
104 |
|
105 Configure the main template |
|
106 ``````````````````````````` |
|
107 |
|
108 You can overload some methods of the |
|
109 :class:`~cubicweb.web.views.basetemplates.TheMainTemplate`, in order to fulfil |
|
110 your needs. There are also some attributes and methods which can be defined on a |
|
111 view to modify the base template behaviour: |
|
112 |
|
113 * `paginable`: if the result set is bigger than a configurable size, your result |
|
114 page will be paginated by default. You can set this attribute to `False` to |
|
115 avoid this. |
|
116 |
|
117 * `binary`: boolean flag telling if the view generates some text or a binary |
|
118 stream. Default to False. When view generates text argument given to `self.w` |
|
119 **must be a unicode string**, encoded string otherwise. |
|
120 |
|
121 * `content_type`, view's content type, default to 'text/xhtml' |
|
122 |
|
123 * `templatable`, boolean flag telling if the view's content should be returned |
|
124 directly (when `False`) or included in the main template layout (including |
|
125 header, boxes and so on). |
|
126 |
|
127 * `page_title()`, method that should return a title that will be set as page |
|
128 title in the html headers. |
|
129 |
|
130 * `html_headers()`, method that should return a list of HTML headers to be |
|
131 included the html headers. |
|
132 |
|
133 |
|
134 You can also modify certain aspects of the main template of a page |
|
135 when building a url or setting these parameters in the req.form: |
|
136 |
|
137 * `__notemplate`, if present (whatever the value assigned), only the content view |
|
138 is returned |
|
139 |
|
140 * `__force_display`, if present and its value is not null, no pagination whatever |
|
141 the number of entities to display (e.g. similar effect as view's `paginable` |
|
142 attribute described above. |
|
143 |
|
144 * `__method`, if the result set to render contains only one entity and this |
|
145 parameter is set, it refers to a method to call on the entity by passing it the |
|
146 dictionary of the forms parameters, before going the classic way (through step |
|
147 1 and 2 described juste above) |
|
148 |
|
149 * `vtitle`, a title to be set as <h1> of the content |
|
150 |
|
151 Other templates |
|
152 ~~~~~~~~~~~~~~~ |
|
153 |
|
154 There are also the following other standard templates: |
|
155 |
|
156 * :class:`cubicweb.web.views.basetemplates.LogInTemplate` |
|
157 * :class:`cubicweb.web.views.basetemplates.LogOutTemplate` |
|
158 * :class:`cubicweb.web.views.basetemplates.ErrorTemplate` specializes |
|
159 :class:`~cubicweb.web.views.basetemplates.TheMainTemplate` to do |
|
160 proper end-user output if an error occurs during the computation of |
|
161 TheMainTemplate (it is a fallback view). |