Mercurial > genshi > genshi-test

annotate doc/plugin.txt @ 676:d406547a5d90 experimental-optimizer

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