Mercurial > genshi > mirror
comparison doc/plugin.txt @ 445:ec7890aa7c0b trunk
Add documentation page on the plugin API.
author | cmlenz |
---|---|
date | Fri, 13 Apr 2007 10:38:12 +0000 |
parents | |
children | 1154f2aadb6c |
comparison
equal
deleted
inserted
replaced
444:589c4b076cfe | 445:ec7890aa7c0b |
---|---|
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. |