1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 .. |cubicweb| replace:: *CubicWeb* |
|
4 |
|
5 .. _templates: |
|
6 |
|
7 Templates |
|
8 ========= |
|
9 |
|
10 Templates are the entry point for the |cubicweb| view system. As seen |
|
11 in :ref:`views_base_class`, there are two kinds of views: the |
|
12 templatable and non-templatable. |
|
13 |
|
14 Non-templatable views are standalone. They are responsible for all the |
|
15 details such as setting a proper content type (or mime type), the |
|
16 proper document headers, namespaces, etc. Examples are pure xml views |
|
17 such as RSS or Semantic Web views (`SIOC`_, `DOAP`_, `FOAF`_, `Linked |
|
18 Data`_, etc.). |
|
19 |
|
20 .. _`SIOC`: http://sioc-project.org/ |
|
21 .. _`DOAP`: http://trac.usefulinc.com/doap |
|
22 .. _`FOAF`: http://www.foaf-project.org/ |
|
23 .. _`Linked Data`: http://linkeddata.org/ |
|
24 |
|
25 Templatable views are not concerned with such pesky details. They |
|
26 leave it to the template. Conversely, the template's main job is to: |
|
27 |
|
28 * set up the proper document header and content type |
|
29 * define the general layout of a document |
|
30 * invoke adequate views in the various sections of the document |
|
31 |
|
32 |
|
33 Look at :mod:`cubicweb.web.views.basetemplates` and you will find the |
|
34 base templates used to generate (X)HTML for your application. The most |
|
35 important template there is `TheMainTemplate`. |
|
36 |
|
37 .. _the_main_template_layout: |
|
38 |
|
39 TheMainTemplate |
|
40 --------------- |
|
41 |
|
42 .. _the_main_template_sections: |
|
43 |
|
44 Layout and sections |
|
45 ``````````````````` |
|
46 |
|
47 A page is composed as indicated on the schema below : |
|
48 |
|
49 .. image:: ../../../images/main_template.png |
|
50 |
|
51 The sections dispatches specific views: |
|
52 |
|
53 * `header`: the rendering of the header is delegated to the |
|
54 `htmlheader` view, whose default implementation can be found in |
|
55 ``basetemplates.py`` and which does the following things: |
|
56 |
|
57 * inject the favicon if there is one |
|
58 * inject the global style sheets and javascript resources |
|
59 * call and display a link to an rss component if there is one available |
|
60 |
|
61 it also sets up the page title, and fills the actual |
|
62 `header` section with top-level components, using the `header` view, which: |
|
63 |
|
64 * tries to display a logo, the name of the application and the `breadcrumbs` |
|
65 * provides a login status area |
|
66 * provides a login box (hiden by default) |
|
67 |
|
68 * `left column`: this is filled with all selectable boxes matching the |
|
69 `left` context (there is also a right column but nowadays it is |
|
70 seldom used due to bad usability) |
|
71 |
|
72 * `contentcol`: this is the central column; it is filled with: |
|
73 |
|
74 * the `rqlinput` view (hidden by default) |
|
75 * the `applmessages` component |
|
76 * the `contentheader` view which in turns dispatches all available |
|
77 content navigation components having the `navtop` context (this |
|
78 is used to navigate through entities implementing the IPrevNext |
|
79 interface) |
|
80 * the view that was given as input to the template's `call` |
|
81 method, also dealing with pagination concerns |
|
82 * the `contentfooter` |
|
83 |
|
84 * `footer`: adds all footer actions |
|
85 |
|
86 .. note:: |
|
87 |
|
88 How and why a view object is given to the main template is explained |
|
89 in the :ref:`publisher` chapter. |
|
90 |
|
91 Class attributes |
|
92 ```````````````` |
|
93 |
|
94 We can also control certain aspects of the main template thanks to the following |
|
95 forms parameters: |
|
96 |
|
97 * `__notemplate`, if present (whatever the value assigned), only the content view |
|
98 is returned |
|
99 * `__force_display`, if present and its value is not null, no navigation |
|
100 whatever the number of entities to display |
|
101 * `__method`, if the result set to render contains only one entity and this |
|
102 parameter is set, it refers to a method to call on the entity by passing it |
|
103 the dictionary of the forms parameters, before going the classic way (through |
|
104 step 1 and 2 described juste above) |
|
105 |
|
106 Other templates |
|
107 --------------- |
|
108 |
|
109 Other standard templates include: |
|
110 |
|
111 * `login` and `logout` |
|
112 |
|
113 * `error-template` specializes TheMainTemplate to do proper end-user |
|
114 output if an error occurs during the computation of TheMainTemplate |
|
115 (it is a fallback view). |
|