Mercurial > genshi > genshi-test

annotate doc/plugin.txt @ 704:4d2afb73d51b experimental-match-fastpaths

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
further performance improvements to MatchSet functionality - factor out MatchSet's State so that we dont' have to keep copying over the state every time we create a new child MatchSet. Also fixes a bug where we could get duplicate match indexes when a new match is created while evaluating an existing match Also, try to be lazy about creating the first MatchSet so that we don't hurt bigtable performance (i.e. when there are no py:matches in play at all)
author aflett
date Fri, 04 Apr 2008 16:57:27 +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