Mercurial > genshi > mirror

annotate doc/plugin.txt @ 713:5420fe9d99a9 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
The `Markup` class now supports mappings for right hand of the `%` (modulo) operator in the same way the Python string classes do, except that the substituted values are escape. Also, the special constructor which took positional arguments that would be substituted was removed. Thus the `Markup` class now supports the same arguments as that of its `unicode` base class. Closes #211. Many thanks to Christian Boos for the patch!
author cmlenz
date Tue, 08 Apr 2008 18:18:18 +0000
parents 1da8de3e5e51
children 3a59144a35b1
rev   line source
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
2
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
3 ===========================
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
4 Using the Templating Plugin
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
5 ===========================
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
6
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
7 While you can easily use Genshi templating through the APIs provided directly
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
9 engine plugin API. Note though that this considerably limits the power and
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
11 such as Genshi's `HTMLFormFiller`_ when the plugin
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
12 API is sitting between your code and Genshi).
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
13
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
14 .. _`HTMLFormFiller`: filters.html>#html-form-filler
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
15
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
16
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
17 .. contents:: Contents
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
18 :depth: 2
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
19 .. sectnum::
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
20
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
21
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
22 Introduction
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
23 ============
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
24
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
25 Most Python web frameworks (with the notable exception of Django_) support
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
26 a variety of different templating engines through the `Template Engine Plugin
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
27 API`_, which was first developed by the Buffet_ and TurboGears_ projects.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
28
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
29 .. _`Template Engine Plugin API`: http://docs.turbogears.org/1.0/TemplatePlugins
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
30 .. _`Django`: http://www.djangoproject.com/
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
31 .. _`Buffet`: http://projects.dowski.com/projects/buffet
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
32 .. _`TurboGears`: http://www.turbogears.org/
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
33
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
35 TurboGears or `Pylons`_ without installing any additional packages. A small
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
36 example TurboGears application is included in the ``examples`` directory of
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
37 source distributions of Genshi.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
38
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
39 .. _`Pylons`: http://pylonshq.com/
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
40
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
41
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
42 Usage
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
43 =====
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
44
ec7890aa7c0b 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
ec7890aa7c0b 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:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
47
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
48 (1) Configure Genshi as the default (or an additional) template engine
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
49 (2) Optionally specify Genshi-specific `configuration options`_
ec7890aa7c0b 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
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
52 should be made available to it.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
53
ec7890aa7c0b 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.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
55 For Genshi, this is **"genshi"**. However, because Genshi supports both markup
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
56 and text templates, it also provides two separate plugins, namely
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
57 **"genshi-markup"** and **"genshi-text"** (the "genshi" name is just an
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
58 alias for "genshi-markup").
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
59
ec7890aa7c0b 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
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
62 template in a specific controller, you'd configure "genshi" as the default
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
63 template engine, and specify "genshi-text" for the controllers that should use
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
64 text templates. How exactly this works depends on the framework in use.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
65
ec7890aa7c0b 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
ec7890aa7c0b 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``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
68 keyword argument, which Genshi will use to override the configured default
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
69 serialization method. In combination with specifying the "genshi-text" engine
ec7890aa7c0b 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
ec7890aa7c0b 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
ec7890aa7c0b 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.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
73
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
74
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
75 Extra Implicit Objects
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
76 ======================
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
77
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
78 The "genshi-markup" template engine plugin adds some extra functions that are
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
79 made available to all templates implicitly, namely:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
80
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
81 ``HTML(string)``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
82 Parses the given string as HTML and returns a markup stream.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
83 ``XML(string)``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
84 Parses the given string as XML and returns a markup stream.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
85 ``ET(tree)``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
86 Adapts the given `ElementTree`_ object to a markup stream.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
87
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
88 The framework may make additional objects available by default. Consult the
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
89 documentation of your framework for more information.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
90
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
91 .. _elementtree: http://effbot.org/zone/element-index.htm
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
92
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
93
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
94 .. _`configuration options`:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
95
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
96 Configuration Options
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
97 =====================
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
98
ec7890aa7c0b 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.
ec7890aa7c0b 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
ec7890aa7c0b 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,
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
102 only passes a fixed set of options to all plugins.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
103
545
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 538
diff changeset
104 ``genshi.allow_exec``
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 538
diff changeset
105 --------------------------
619340e2d805 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"
619340e2d805 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
619340e2d805 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
619340e2d805 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
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 538
diff changeset
110 plain expressions.
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 538
diff changeset
111
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
112 ``genshi.auto_reload``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
113 ----------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
114 Whether the template loader should check the last modification time of template
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
115 files, and automatically reload them if they have been changed. Specify "yes"
ec7890aa7c0b 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.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
117
548
1cc1afc39176 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
1cc1afc39176 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
1cc1afc39176 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
1cc1afc39176 Implement static includes, which improves performance a bit when auto reloading is disabled.
cmlenz
parents: 545
diff changeset
121 the templates are updated.
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
122
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
123 ``genshi.default_doctype``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
124 --------------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
125 The default ``DOCTYPE`` declaration to use in generated markup. Valid values
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
126 are:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
127
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
128 **html-strict** (or just **html**)
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
129 HTML 4.01 Strict
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
130 **html-transitional**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
131 HTML 4.01 Transitional
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
132 **xhtml-strict** (or just **xhtml**)
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
133 XHTML 1.0 Strict
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
134 **xhtml-transitional**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
135 XHTML 1.0 Transitional
448
1154f2aadb6c Add support for HTML5 doctype.
cmlenz
parents: 445
diff changeset
136 **html5**
1154f2aadb6c Add support for HTML5 doctype.
cmlenz
parents: 445
diff changeset
137 HTML5 (as `proposed`_ by the WHAT-WG)
1154f2aadb6c Add support for HTML5 doctype.
cmlenz
parents: 445
diff changeset
138
1154f2aadb6c Add support for HTML5 doctype.
cmlenz
parents: 445
diff changeset
139 .. _proposed: http://www.whatwg.org/specs/web-apps/current-work/
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
140
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
141 .. note:: While using the Genshi API directly allows you to specify document
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
142 types not in that list, the *dictionary-of-strings* based
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
143 configuration utilized by the plugin API unfortunately limits your
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
144 choices to those listed above.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
145
ec7890aa7c0b 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
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
148 set, however, any ``DOCTYPE`` declarations in the templates are replaced by the
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
149 specified document type.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
150
ec7890aa7c0b 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
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
153 style sheets. In particular, browsers may switch to *quirks rendering mode* for
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
154 certain document types, or when the ``DOCTYPE`` declaration is missing
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
155 completely.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
156
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
157 For more information on the choice of the appropriate ``DOCTYPE``, see:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
158
ec7890aa7c0b 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>`_
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
160 * `Choosing a DOCTYPE <http://htmlhelp.com/tools/validator/doctype.html>`_
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
161
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
162 ``genshi.default_encoding``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
163 ---------------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
164 The default output encoding to use when serializing a template. By default,
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
166 specifying this option, although that rarely makes sense.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
167
ec7890aa7c0b 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
ec7890aa7c0b 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)
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
170 specify the chosen encoding as part of the outgoing ``Content-Type`` header.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
171 For example::
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
172
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
173 Content-Type: text/html; charset=utf-8
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
174
ec7890aa7c0b 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
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
177 browser know about that explicitly
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
178
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
179 ``genshi.default_format``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
180 -------------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
181 Determines the default serialization method to use. Valid options are:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
182
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
183 **xml**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
184 Serialization to XML
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
185 **xhtml**
ec7890aa7c0b 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
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
188 by XML parsers if you're careful).
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
189 **html**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
190 Serialization to HTML
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
191 **text**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
192 Plain text serialization
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
193
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
194 See `Understanding HTML, XML and XHTML`_ for an excellent description of the
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
195 subtle differences between the three different markup serialization options. As
ec7890aa7c0b 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
ec7890aa7c0b 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.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
198
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
199 .. _`Understanding HTML, XML and XHTML`: http://webkit.org/blog/?p=68
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
200
538
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
201 ``genshi.loader_callback``
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
202 --------------------------
e9db4aca70f0 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
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
204 a new template.
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
205
e9db4aca70f0 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
e9db4aca70f0 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.
e9db4aca70f0 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)
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
209 configuration files.
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
210
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
211 ``genshi.lookup_errors``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
212 ------------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
213 The error handling style to use in template expressions. Can be either
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
214 **lenient** (the default) or **strict**. See the `Error Handling`_ section for
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
215 detailled information on the differences between these two modes.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
216
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
217 .. _`Error Handling`: templates.html#template-expressions-and-code-blocks
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
218
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
219 ``genshi.max_cache_size``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
220 -------------------------
ec7890aa7c0b 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.
ec7890aa7c0b 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
ec7890aa7c0b 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.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
224
592
1da8de3e5e51 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``
1da8de3e5e51 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 --------------------------
1da8de3e5e51 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
1da8de3e5e51 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.
1da8de3e5e51 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
1da8de3e5e51 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
1da8de3e5e51 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.
1da8de3e5e51 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
233 ``genshi.search_path``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
234 ----------------------
ec7890aa7c0b 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
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
236 use to search for templates.
Copyright (C) 2012-2017 Edgewall Software