|
445
|
1 .. -*- mode: rst; encoding: utf-8 -*-
|
|
|
2
|
|
|
3 ===========================
|
|
|
4 Using the Templating Plugin
|
|
|
5 ===========================
|
|
|
6
|
|
|
7 While you can easily use Genshi templating through the APIs provided directly
|
|
|
8 by Genshi, in some situations you may want to use Genshi through the template
|
|
|
9 engine plugin API. Note though that this considerably limits the power and
|
|
|
10 flexibility of Genshi templates (for example, there's no good way to use filters
|
|
|
11 such as Genshi's `HTMLFormFiller`_ when the plugin
|
|
|
12 API is sitting between your code and Genshi).
|
|
|
13
|
|
|
14 .. _`HTMLFormFiller`: filters.html>#html-form-filler
|
|
|
15
|
|
|
16
|
|
|
17 .. contents:: Contents
|
|
|
18 :depth: 2
|
|
|
19 .. sectnum::
|
|
|
20
|
|
|
21
|
|
|
22 Introduction
|
|
|
23 ============
|
|
|
24
|
|
|
25 Most Python web frameworks (with the notable exception of Django_) support
|
|
|
26 a variety of different templating engines through the `Template Engine Plugin
|
|
|
27 API`_, which was first developed by the Buffet_ and TurboGears_ projects.
|
|
|
28
|
|
|
29 .. _`Template Engine Plugin API`: http://docs.turbogears.org/1.0/TemplatePlugins
|
|
|
30 .. _`Django`: http://www.djangoproject.com/
|
|
|
31 .. _`Buffet`: http://projects.dowski.com/projects/buffet
|
|
|
32 .. _`TurboGears`: http://www.turbogears.org/
|
|
|
33
|
|
|
34 Genshi supports this API out of the box, so you can use it in frameworks like
|
|
|
35 TurboGears or `Pylons`_ without installing any additional packages. A small
|
|
|
36 example TurboGears application is included in the ``examples`` directory of
|
|
|
37 source distributions of Genshi.
|
|
|
38
|
|
|
39 .. _`Pylons`: http://pylonshq.com/
|
|
|
40
|
|
|
41
|
|
|
42 Usage
|
|
|
43 =====
|
|
|
44
|
|
|
45 The way you use Genshi through the plugin API depends very much on the framework
|
|
|
46 you're using. In general, the approach will look something like the following:
|
|
|
47
|
|
|
48 (1) Configure Genshi as the default (or an additional) template engine
|
|
|
49 (2) Optionally specify Genshi-specific `configuration options`_
|
|
|
50 (3) For any given *view* or *controller* (or whatever those are called in your
|
|
|
51 framework of choice), specify the name of the template to use and which data
|
|
|
52 should be made available to it.
|
|
|
53
|
|
|
54 For point 1, you'll have to specify the *name* of the template engine plugin.
|
|
|
55 For Genshi, this is **"genshi"**. However, because Genshi supports both markup
|
|
|
56 and text templates, it also provides two separate plugins, namely
|
|
|
57 **"genshi-markup"** and **"genshi-text"** (the "genshi" name is just an
|
|
|
58 alias for "genshi-markup").
|
|
|
59
|
|
|
60 Usually, you can choose a default template engine, but also use a different
|
|
|
61 engine on a per-request basis. So to use markup templates in general, but a text
|
|
|
62 template in a specific controller, you'd configure "genshi" as the default
|
|
|
63 template engine, and specify "genshi-text" for the controllers that should use
|
|
|
64 text templates. How exactly this works depends on the framework in use.
|
|
|
65
|
|
|
66 When rendering a specific template in a controller (point 3 above), you may also
|
|
|
67 be able to pass additional options to the plugin. This includes the ``format``
|
|
|
68 keyword argument, which Genshi will use to override the configured default
|
|
|
69 serialization method. In combination with specifying the "genshi-text" engine
|
|
|
70 name as explained above, you would use this to specify the "text" serialization
|
|
|
71 method when you want to use a text template. Or you'd specify "xml" for the
|
|
|
72 format when you want to produce an Atom feed or other XML content.
|
|
|
73
|
|
|
74
|
|
|
75 Extra Implicit Objects
|
|
|
76 ======================
|
|
|
77
|
|
|
78 The "genshi-markup" template engine plugin adds some extra functions that are
|
|
|
79 made available to all templates implicitly, namely:
|
|
|
80
|
|
|
81 ``HTML(string)``
|
|
|
82 Parses the given string as HTML and returns a markup stream.
|
|
|
83 ``XML(string)``
|
|
|
84 Parses the given string as XML and returns a markup stream.
|
|
|
85 ``ET(tree)``
|
|
|
86 Adapts the given `ElementTree`_ object to a markup stream.
|
|
|
87
|
|
|
88 The framework may make additional objects available by default. Consult the
|
|
|
89 documentation of your framework for more information.
|
|
|
90
|
|
|
91 .. _elementtree: http://effbot.org/zone/element-index.htm
|
|
|
92
|
|
|
93
|
|
|
94 .. _`configuration options`:
|
|
|
95
|
|
|
96 Configuration Options
|
|
|
97 =====================
|
|
|
98
|
|
|
99 The plugin API allows plugins to be configured using a dictionary of strings.
|
|
|
100 The following is a list of configuration options that Genshi supports. These may
|
|
|
101 or may not be made available by your framework. TurboGears 1.0, for example,
|
|
|
102 only passes a fixed set of options to all plugins.
|
|
|
103
|
|
|
104 ``genshi.auto_reload``
|
|
|
105 ----------------------
|
|
|
106 Whether the template loader should check the last modification time of template
|
|
|
107 files, and automatically reload them if they have been changed. Specify "yes"
|
|
|
108 to enable this reloading (which is the default), or "no" to turn it off.
|
|
|
109
|
|
|
110 .. note:: You may want to disable reloading in a production environment to gain
|
|
|
111 a slight (and possible even negligible) improvement in loading
|
|
|
112 performance, but then you'll have to manually restart the server
|
|
|
113 process anytime the templates are updated.
|
|
|
114
|
|
|
115 ``genshi.default_doctype``
|
|
|
116 --------------------------
|
|
|
117 The default ``DOCTYPE`` declaration to use in generated markup. Valid values
|
|
|
118 are:
|
|
|
119
|
|
|
120 **html-strict** (or just **html**)
|
|
|
121 HTML 4.01 Strict
|
|
|
122 **html-transitional**
|
|
|
123 HTML 4.01 Transitional
|
|
|
124 **xhtml-strict** (or just **xhtml**)
|
|
|
125 XHTML 1.0 Strict
|
|
|
126 **xhtml-transitional**
|
|
|
127 XHTML 1.0 Transitional
|
|
448
|
128 **html5**
|
|
|
129 HTML5 (as `proposed`_ by the WHAT-WG)
|
|
|
130
|
|
|
131 .. _proposed: http://www.whatwg.org/specs/web-apps/current-work/
|
|
445
|
132
|
|
|
133 .. note:: While using the Genshi API directly allows you to specify document
|
|
|
134 types not in that list, the *dictionary-of-strings* based
|
|
|
135 configuration utilized by the plugin API unfortunately limits your
|
|
|
136 choices to those listed above.
|
|
|
137
|
|
|
138 The default behavior is to not do any prepending/replacing of a ``DOCTYPE``, but
|
|
|
139 rather pass through those defined in the templates (if any). If this option is
|
|
|
140 set, however, any ``DOCTYPE`` declarations in the templates are replaced by the
|
|
|
141 specified document type.
|
|
|
142
|
|
|
143 Note that with (X)HTML, the presence and choice of the ``DOCTYPE`` can have a
|
|
|
144 more or less dramatic impact on how modern browsers render pages that use CSS
|
|
|
145 style sheets. In particular, browsers may switch to *quirks rendering mode* for
|
|
|
146 certain document types, or when the ``DOCTYPE`` declaration is missing
|
|
|
147 completely.
|
|
|
148
|
|
|
149 For more information on the choice of the appropriate ``DOCTYPE``, see:
|
|
|
150
|
|
|
151 * `Recommended DTDs to use in your Web document <http://www.w3.org/QA/2002/04/valid-dtd-list.html>`_
|
|
|
152 * `Choosing a DOCTYPE <http://htmlhelp.com/tools/validator/doctype.html>`_
|
|
|
153
|
|
|
154 ``genshi.default_encoding``
|
|
|
155 ---------------------------
|
|
|
156 The default output encoding to use when serializing a template. By default,
|
|
|
157 Genshi uses UTF-8. If you need to, you can choose a different charset by
|
|
|
158 specifying this option, although that rarely makes sense.
|
|
|
159
|
|
|
160 As Genshi is not in control over what HTTP headers are being sent together with
|
|
|
161 the template output, make sure that you (or the framework you're using)
|
|
|
162 specify the chosen encoding as part of the outgoing ``Content-Type`` header.
|
|
|
163 For example::
|
|
|
164
|
|
|
165 Content-Type: text/html; charset=utf-8
|
|
|
166
|
|
|
167 .. note:: Browsers commonly use ISO-8859-1 by default for ``text/html``, so even
|
|
|
168 if you use Genshi's default UTF-8 encoding, you'll have to let the
|
|
|
169 browser know about that explicitly
|
|
|
170
|
|
|
171 ``genshi.default_format``
|
|
|
172 -------------------------
|
|
|
173 Determines the default serialization method to use. Valid options are:
|
|
|
174
|
|
|
175 **xml**
|
|
|
176 Serialization to XML
|
|
|
177 **xhtml**
|
|
|
178 Serialization to XHTML in a way that should be compatible with HTML (i.e. the
|
|
|
179 result can be sent using the ``text/html`` MIME type, but can also be handled
|
|
|
180 by XML parsers if you're careful).
|
|
|
181 **html**
|
|
|
182 Serialization to HTML
|
|
|
183 **text**
|
|
|
184 Plain text serialization
|
|
|
185
|
|
|
186 See `Understanding HTML, XML and XHTML`_ for an excellent description of the
|
|
|
187 subtle differences between the three different markup serialization options. As
|
|
|
188 a general recommendation, if you don't have a special requirement to produce
|
|
|
189 well-formed XML, you should probably use the **html** option for your web sites.
|
|
|
190
|
|
|
191 .. _`Understanding HTML, XML and XHTML`: http://webkit.org/blog/?p=68
|
|
|
192
|
|
|
193 ``genshi.lookup_errors``
|
|
|
194 ------------------------
|
|
|
195 The error handling style to use in template expressions. Can be either
|
|
|
196 **lenient** (the default) or **strict**. See the `Error Handling`_ section for
|
|
|
197 detailled information on the differences between these two modes.
|
|
|
198
|
|
|
199 .. _`Error Handling`: templates.html#template-expressions-and-code-blocks
|
|
|
200
|
|
|
201 ``genshi.max_cache_size``
|
|
|
202 -------------------------
|
|
|
203 The maximum number of templates that the template loader will cache in memory.
|
|
|
204 The default value is **25**. You may want to choose a higher value if your web
|
|
|
205 site uses a larger number of templates, and you have enough memory to spare.
|
|
|
206
|
|
|
207 ``genshi.search_path``
|
|
|
208 ----------------------
|
|
|
209 A colon-separated list of file-system path names that the template loader should
|
|
|
210 use to search for templates.
|
