Mercurial > genshi > mirror

annotate doc/plugin.txt @ 934:31bbb6f9e87b trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge r1142 from py3k: add support for python 3 to genshi.template expression evaluator: * add support for python 3 AST: * AST for raise has changed in Python 3. * Python 3 adds AST nodes for individual arguments and Bytes. * use genshi.compat functions for dealing with code objects. * do not coerce byte strings to unicode in Python 3 ASTTransformer. * replace doctests that reply on exception names with uglier but more compatible try:.. except:.. doctest * handle filename preferences of Python 2 and 3 (2 prefers bytes, 3 prefers unicode). * ifilter is gone from itertools in Python 3 so use repeat for tests instead.
author hodgestar
date Fri, 18 Mar 2011 09:15:29 +0000
parents 3a59144a35b1
children
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
769
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
25 Some Python web frameworks support a variety of different templating engines
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
26 through the `Template Engine Plugin API`_, which was first developed by the
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
27 Buffet_ and TurboGears_ projects.
445
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 .. _`Buffet`: http://projects.dowski.com/projects/buffet
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
31 .. _`TurboGears`: http://www.turbogears.org/
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
32
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
33 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
34 TurboGears or `Pylons`_ without installing any additional packages. A small
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
35 example TurboGears application is included in the ``examples`` directory of
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
36 source distributions of Genshi.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
37
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
38 .. _`Pylons`: http://pylonshq.com/
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
39
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 Usage
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
42 =====
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 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
45 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
46
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
47 (1) Configure Genshi as the default (or an additional) template engine
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
48 (2) Optionally specify Genshi-specific `configuration options`_
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
49 (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
50 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
51 should be made available to it.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
52
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
53 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
54 For Genshi, this is **"genshi"**. However, because Genshi supports both markup
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
55 and text templates, it also provides two separate plugins, namely
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
56 **"genshi-markup"** and **"genshi-text"** (the "genshi" name is just an
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
57 alias for "genshi-markup").
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
58
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
59 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
60 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
61 template in a specific controller, you'd configure "genshi" as the default
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
62 template engine, and specify "genshi-text" for the controllers that should use
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
63 text templates. How exactly this works depends on the framework in use.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
64
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
65 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
66 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
67 keyword argument, which Genshi will use to override the configured default
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
68 serialization method. In combination with specifying the "genshi-text" engine
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
69 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
70 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
71 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
72
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
73
769
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
74 Template Paths
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
75 --------------
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
76
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
77 How you specify template paths depends on whether you have a `search path`_ set
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
78 up or not. The search path is a list of directories that Genshi should load
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
79 templates from. Now when you request a template using a relative path such as
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
80 ``mytmpl.html`` or ``foo/mytmpl.html``, Genshi will look for that file in the
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
81 directories on the search path.
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
82
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
83 For mostly historical reasons, the Genshi template engine plugin uses a
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
84 different approach when you **haven't** configured the template search path:
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
85 you now load templates using *dotted notation*, for example ``mytmpl`` or
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
86 ``foo.mytmpl``. Note how you've lost the ability to explicitly specify the
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
87 file extension: you now have to use ``.html`` for markup templates, and
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
88 ``.txt`` for text templates.
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
89
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
90 Using the search path is recommended for a number of reasons: First, it's
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
91 the native Genshi model and is thus more robust and better supported.
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
92 Second, a search path gives you much more flexibility for organizing your
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
93 application templates. And as noted above, you aren't forced to use hardcoded
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
94 filename extensions for your template files.
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
95
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
96
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
97 Extra Implicit Objects
769
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
98 ----------------------
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
99
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
100 The "genshi-markup" template engine plugin adds some extra functions that are
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
101 made available to all templates implicitly, namely:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
102
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
103 ``HTML(string)``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
104 Parses the given string as HTML and returns a markup stream.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
105 ``XML(string)``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
106 Parses the given string as XML and returns a markup stream.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
107 ``ET(tree)``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
108 Adapts the given `ElementTree`_ object to a markup stream.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
109
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
110 The framework may make additional objects available by default. Consult the
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
111 documentation of your framework for more information.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
112
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
113 .. _elementtree: http://effbot.org/zone/element-index.htm
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
114
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
115
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
116 .. _`configuration options`:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
117
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
118 Configuration Options
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
119 =====================
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
120
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
121 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
122 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
123 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
124 only passes a fixed set of options to all plugins.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
125
545
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 538
diff changeset
126 ``genshi.allow_exec``
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 538
diff changeset
127 --------------------------
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 538
diff changeset
128 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
129 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
130 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
131 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
132 plain expressions.
619340e2d805 Support for Python code blocks in templates can now be disabled. Closes #123.
cmlenz
parents: 538
diff changeset
133
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
134 ``genshi.auto_reload``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
135 ----------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
136 Whether the template loader should check the last modification time of template
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
137 files, and automatically reload them if they have been changed. Specify "yes"
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
138 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
139
548
1cc1afc39176 Implement static includes, which improves performance a bit when auto reloading is disabled.
cmlenz
parents: 545
diff changeset
140 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
141 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
142 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
143 the templates are updated.
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
144
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
145 ``genshi.default_doctype``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
146 --------------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
147 The default ``DOCTYPE`` declaration to use in generated markup. Valid values
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
148 are:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
149
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
150 **html-strict** (or just **html**)
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
151 HTML 4.01 Strict
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
152 **html-transitional**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
153 HTML 4.01 Transitional
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
154 **xhtml-strict** (or just **xhtml**)
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
155 XHTML 1.0 Strict
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
156 **xhtml-transitional**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
157 XHTML 1.0 Transitional
448
1154f2aadb6c Add support for HTML5 doctype.
cmlenz
parents: 445
diff changeset
158 **html5**
1154f2aadb6c Add support for HTML5 doctype.
cmlenz
parents: 445
diff changeset
159 HTML5 (as `proposed`_ by the WHAT-WG)
1154f2aadb6c Add support for HTML5 doctype.
cmlenz
parents: 445
diff changeset
160
1154f2aadb6c Add support for HTML5 doctype.
cmlenz
parents: 445
diff changeset
161 .. _proposed: http://www.whatwg.org/specs/web-apps/current-work/
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
162
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
163 .. note:: While using the Genshi API directly allows you to specify document
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
164 types not in that list, the *dictionary-of-strings* based
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
165 configuration utilized by the plugin API unfortunately limits your
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
166 choices to those listed above.
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 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
169 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
170 set, however, any ``DOCTYPE`` declarations in the templates are replaced by the
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
171 specified document type.
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 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
174 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
175 style sheets. In particular, browsers may switch to *quirks rendering mode* for
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
176 certain document types, or when the ``DOCTYPE`` declaration is missing
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
177 completely.
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 For more information on the choice of the appropriate ``DOCTYPE``, see:
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 * `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
182 * `Choosing a DOCTYPE <http://htmlhelp.com/tools/validator/doctype.html>`_
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
183
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
184 ``genshi.default_encoding``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
185 ---------------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
186 The default output encoding to use when serializing a template. By default,
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
187 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
188 specifying this option, although that rarely makes sense.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
189
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
190 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
191 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
192 specify the chosen encoding as part of the outgoing ``Content-Type`` header.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
193 For example::
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
194
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
195 Content-Type: text/html; charset=utf-8
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
196
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
197 .. 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
198 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
199 browser know about that explicitly
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
200
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
201 ``genshi.default_format``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
202 -------------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
203 Determines the default serialization method to use. Valid options are:
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
204
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
205 **xml**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
206 Serialization to XML
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
207 **xhtml**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
208 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
209 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
210 by XML parsers if you're careful).
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
211 **html**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
212 Serialization to HTML
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
213 **text**
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
214 Plain text serialization
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
215
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
216 See `Understanding HTML, XML and XHTML`_ for an excellent description of the
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
217 subtle differences between the three different markup serialization options. As
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
218 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
219 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
220
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
221 .. _`Understanding HTML, XML and XHTML`: http://webkit.org/blog/?p=68
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
222
538
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
223 ``genshi.loader_callback``
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
224 --------------------------
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
225 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
226 a new template.
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
227
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
228 .. 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
229 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
230 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
231 configuration files.
e9db4aca70f0 Add `loader_callback` option to plugin interface as requested in #130.
cmlenz
parents: 448
diff changeset
232
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
233 ``genshi.lookup_errors``
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 The error handling style to use in template expressions. Can be either
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
236 **lenient** (the default) or **strict**. See the `Error Handling`_ section for
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
237 detailled information on the differences between these two modes.
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
238
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
239 .. _`Error Handling`: templates.html#template-expressions-and-code-blocks
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
240
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
241 ``genshi.max_cache_size``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
242 -------------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
243 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
244 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
245 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
246
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
247 ``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
248 --------------------------
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
249 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
250 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
251
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
252 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
253 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
254
769
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
255 .. _`search path`:
3a59144a35b1 Includes from templates loaded via an absolute path now include the correct file in nested directories as long if no search path has been configured. Closes #240.
cmlenz
parents: 592
diff changeset
256
445
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
257 ``genshi.search_path``
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
258 ----------------------
ec7890aa7c0b Add documentation page on the plugin API.
cmlenz
parents:
diff changeset
259 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
260 use to search for templates.
Copyright (C) 2012-2017 Edgewall Software