Mercurial > genshi > genshi-test

comparison doc/plugin.txt @ 445:906b346513b6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation page on the plugin API.
author cmlenz
date Fri, 13 Apr 2007 10:38:12 +0000
parents
children 0407937b2853
comparison
equal deleted inserted replaced
444:1a75995cb00c 445:906b346513b6
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
128
129 .. note:: While using the Genshi API directly allows you to specify document
130 types not in that list, the *dictionary-of-strings* based
131 configuration utilized by the plugin API unfortunately limits your
132 choices to those listed above.
133
134 The default behavior is to not do any prepending/replacing of a ``DOCTYPE``, but
135 rather pass through those defined in the templates (if any). If this option is
136 set, however, any ``DOCTYPE`` declarations in the templates are replaced by the
137 specified document type.
138
139 Note that with (X)HTML, the presence and choice of the ``DOCTYPE`` can have a
140 more or less dramatic impact on how modern browsers render pages that use CSS
141 style sheets. In particular, browsers may switch to *quirks rendering mode* for
142 certain document types, or when the ``DOCTYPE`` declaration is missing
143 completely.
144
145 For more information on the choice of the appropriate ``DOCTYPE``, see:
146
147 * `Recommended DTDs to use in your Web document <http://www.w3.org/QA/2002/04/valid-dtd-list.html>`_
148 * `Choosing a DOCTYPE <http://htmlhelp.com/tools/validator/doctype.html>`_
149
150 ``genshi.default_encoding``
151 ---------------------------
152 The default output encoding to use when serializing a template. By default,
153 Genshi uses UTF-8. If you need to, you can choose a different charset by
154 specifying this option, although that rarely makes sense.
155
156 As Genshi is not in control over what HTTP headers are being sent together with
157 the template output, make sure that you (or the framework you're using)
158 specify the chosen encoding as part of the outgoing ``Content-Type`` header.
159 For example::
160
161 Content-Type: text/html; charset=utf-8
162
163 .. note:: Browsers commonly use ISO-8859-1 by default for ``text/html``, so even
164 if you use Genshi's default UTF-8 encoding, you'll have to let the
165 browser know about that explicitly
166
167 ``genshi.default_format``
168 -------------------------
169 Determines the default serialization method to use. Valid options are:
170
171 **xml**
172 Serialization to XML
173 **xhtml**
174 Serialization to XHTML in a way that should be compatible with HTML (i.e. the
175 result can be sent using the ``text/html`` MIME type, but can also be handled
176 by XML parsers if you're careful).
177 **html**
178 Serialization to HTML
179 **text**
180 Plain text serialization
181
182 See `Understanding HTML, XML and XHTML`_ for an excellent description of the
183 subtle differences between the three different markup serialization options. As
184 a general recommendation, if you don't have a special requirement to produce
185 well-formed XML, you should probably use the **html** option for your web sites.
186
187 .. _`Understanding HTML, XML and XHTML`: http://webkit.org/blog/?p=68
188
189 ``genshi.lookup_errors``
190 ------------------------
191 The error handling style to use in template expressions. Can be either
192 **lenient** (the default) or **strict**. See the `Error Handling`_ section for
193 detailled information on the differences between these two modes.
194
195 .. _`Error Handling`: templates.html#template-expressions-and-code-blocks
196
197 ``genshi.max_cache_size``
198 -------------------------
199 The maximum number of templates that the template loader will cache in memory.
200 The default value is **25**. You may want to choose a higher value if your web
201 site uses a larger number of templates, and you have enough memory to spare.
202
203 ``genshi.search_path``
204 ----------------------
205 A colon-separated list of file-system path names that the template loader should
206 use to search for templates.
Copyright (C) 2012-2017 Edgewall Software