Mercurial > genshi > mirror
annotate doc/plugin.txt @ 1026:2e169deb0adc stable-0.7.x
Merge r1229 to r1238 and r1243 to r1251 from trunk (documentation fixes and Python 3.4 support).
| author | hodgestar |
|---|---|
| date | Sun, 09 Mar 2014 08:41:45 +0000 |
| parents | 3a59144a35b1 |
| children |
| rev | line source |
|---|---|
| 445 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
| 2 | |
| 3 =========================== | |
| 4 Using the Templating Plugin | |
| 5 =========================== | |
| 6 | |
| 7 While you can easily use Genshi templating through the APIs provided directly | |
| 8 by Genshi, in some situations you may want to use Genshi through the template | |
| 9 engine plugin API. Note though that this considerably limits the power and | |
| 10 flexibility of Genshi templates (for example, there's no good way to use filters | |
| 11 such as Genshi's `HTMLFormFiller`_ when the plugin | |
| 12 API is sitting between your code and Genshi). | |
| 13 | |
| 14 .. _`HTMLFormFiller`: filters.html>#html-form-filler | |
| 15 | |
| 16 | |
| 17 .. contents:: Contents | |
| 18 :depth: 2 | |
| 19 .. sectnum:: | |
| 20 | |
| 21 | |
| 22 Introduction | |
| 23 ============ | |
| 24 | |
|
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 | 28 |
| 29 .. _`Template Engine Plugin API`: http://docs.turbogears.org/1.0/TemplatePlugins | |
| 30 .. _`Buffet`: http://projects.dowski.com/projects/buffet | |
| 31 .. _`TurboGears`: http://www.turbogears.org/ | |
| 32 | |
| 33 Genshi supports this API out of the box, so you can use it in frameworks like | |
| 34 TurboGears or `Pylons`_ without installing any additional packages. A small | |
| 35 example TurboGears application is included in the ``examples`` directory of | |
| 36 source distributions of Genshi. | |
| 37 | |
| 38 .. _`Pylons`: http://pylonshq.com/ | |
| 39 | |
| 40 | |
| 41 Usage | |
| 42 ===== | |
| 43 | |
| 44 The way you use Genshi through the plugin API depends very much on the framework | |
| 45 you're using. In general, the approach will look something like the following: | |
| 46 | |
| 47 (1) Configure Genshi as the default (or an additional) template engine | |
| 48 (2) Optionally specify Genshi-specific `configuration options`_ | |
| 49 (3) For any given *view* or *controller* (or whatever those are called in your | |
| 50 framework of choice), specify the name of the template to use and which data | |
| 51 should be made available to it. | |
| 52 | |
| 53 For point 1, you'll have to specify the *name* of the template engine plugin. | |
| 54 For Genshi, this is **"genshi"**. However, because Genshi supports both markup | |
| 55 and text templates, it also provides two separate plugins, namely | |
| 56 **"genshi-markup"** and **"genshi-text"** (the "genshi" name is just an | |
| 57 alias for "genshi-markup"). | |
| 58 | |
| 59 Usually, you can choose a default template engine, but also use a different | |
| 60 engine on a per-request basis. So to use markup templates in general, but a text | |
| 61 template in a specific controller, you'd configure "genshi" as the default | |
| 62 template engine, and specify "genshi-text" for the controllers that should use | |
| 63 text templates. How exactly this works depends on the framework in use. | |
| 64 | |
| 65 When rendering a specific template in a controller (point 3 above), you may also | |
| 66 be able to pass additional options to the plugin. This includes the ``format`` | |
| 67 keyword argument, which Genshi will use to override the configured default | |
| 68 serialization method. In combination with specifying the "genshi-text" engine | |
| 69 name as explained above, you would use this to specify the "text" serialization | |
| 70 method when you want to use a text template. Or you'd specify "xml" for the | |
| 71 format when you want to produce an Atom feed or other XML content. | |
| 72 | |
| 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 | 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 | 99 |
| 100 The "genshi-markup" template engine plugin adds some extra functions that are | |
| 101 made available to all templates implicitly, namely: | |
| 102 | |
| 103 ``HTML(string)`` | |
| 104 Parses the given string as HTML and returns a markup stream. | |
| 105 ``XML(string)`` | |
| 106 Parses the given string as XML and returns a markup stream. | |
| 107 ``ET(tree)`` | |
| 108 Adapts the given `ElementTree`_ object to a markup stream. | |
| 109 | |
| 110 The framework may make additional objects available by default. Consult the | |
| 111 documentation of your framework for more information. | |
| 112 | |
| 113 .. _elementtree: http://effbot.org/zone/element-index.htm | |
| 114 | |
| 115 | |
| 116 .. _`configuration options`: | |
| 117 | |
| 118 Configuration Options | |
| 119 ===================== | |
| 120 | |
| 121 The plugin API allows plugins to be configured using a dictionary of strings. | |
| 122 The following is a list of configuration options that Genshi supports. These may | |
| 123 or may not be made available by your framework. TurboGears 1.0, for example, | |
| 124 only passes a fixed set of options to all plugins. | |
| 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 | 134 ``genshi.auto_reload`` |
| 135 ---------------------- | |
| 136 Whether the template loader should check the last modification time of template | |
| 137 files, and automatically reload them if they have been changed. Specify "yes" | |
| 138 to enable this reloading (which is the default), or "no" to turn it off. | |
| 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 | 144 |
| 145 ``genshi.default_doctype`` | |
| 146 -------------------------- | |
| 147 The default ``DOCTYPE`` declaration to use in generated markup. Valid values | |
| 148 are: | |
| 149 | |
| 150 **html-strict** (or just **html**) | |
| 151 HTML 4.01 Strict | |
| 152 **html-transitional** | |
| 153 HTML 4.01 Transitional | |
| 154 **xhtml-strict** (or just **xhtml**) | |
| 155 XHTML 1.0 Strict | |
| 156 **xhtml-transitional** | |
| 157 XHTML 1.0 Transitional | |
| 448 | 158 **html5** |
| 159 HTML5 (as `proposed`_ by the WHAT-WG) | |
| 160 | |
| 161 .. _proposed: http://www.whatwg.org/specs/web-apps/current-work/ | |
| 445 | 162 |
| 163 .. note:: While using the Genshi API directly allows you to specify document | |
| 164 types not in that list, the *dictionary-of-strings* based | |
| 165 configuration utilized by the plugin API unfortunately limits your | |
| 166 choices to those listed above. | |
| 167 | |
| 168 The default behavior is to not do any prepending/replacing of a ``DOCTYPE``, but | |
| 169 rather pass through those defined in the templates (if any). If this option is | |
| 170 set, however, any ``DOCTYPE`` declarations in the templates are replaced by the | |
| 171 specified document type. | |
| 172 | |
| 173 Note that with (X)HTML, the presence and choice of the ``DOCTYPE`` can have a | |
| 174 more or less dramatic impact on how modern browsers render pages that use CSS | |
| 175 style sheets. In particular, browsers may switch to *quirks rendering mode* for | |
| 176 certain document types, or when the ``DOCTYPE`` declaration is missing | |
| 177 completely. | |
| 178 | |
| 179 For more information on the choice of the appropriate ``DOCTYPE``, see: | |
| 180 | |
| 181 * `Recommended DTDs to use in your Web document <http://www.w3.org/QA/2002/04/valid-dtd-list.html>`_ | |
| 182 * `Choosing a DOCTYPE <http://htmlhelp.com/tools/validator/doctype.html>`_ | |
| 183 | |
| 184 ``genshi.default_encoding`` | |
| 185 --------------------------- | |
| 186 The default output encoding to use when serializing a template. By default, | |
| 187 Genshi uses UTF-8. If you need to, you can choose a different charset by | |
| 188 specifying this option, although that rarely makes sense. | |
| 189 | |
| 190 As Genshi is not in control over what HTTP headers are being sent together with | |
| 191 the template output, make sure that you (or the framework you're using) | |
| 192 specify the chosen encoding as part of the outgoing ``Content-Type`` header. | |
| 193 For example:: | |
| 194 | |
| 195 Content-Type: text/html; charset=utf-8 | |
| 196 | |
| 197 .. note:: Browsers commonly use ISO-8859-1 by default for ``text/html``, so even | |
| 198 if you use Genshi's default UTF-8 encoding, you'll have to let the | |
| 199 browser know about that explicitly | |
| 200 | |
| 201 ``genshi.default_format`` | |
| 202 ------------------------- | |
| 203 Determines the default serialization method to use. Valid options are: | |
| 204 | |
| 205 **xml** | |
| 206 Serialization to XML | |
| 207 **xhtml** | |
| 208 Serialization to XHTML in a way that should be compatible with HTML (i.e. the | |
| 209 result can be sent using the ``text/html`` MIME type, but can also be handled | |
| 210 by XML parsers if you're careful). | |
| 211 **html** | |
| 212 Serialization to HTML | |
| 213 **text** | |
| 214 Plain text serialization | |
| 215 | |
| 216 See `Understanding HTML, XML and XHTML`_ for an excellent description of the | |
| 217 subtle differences between the three different markup serialization options. As | |
| 218 a general recommendation, if you don't have a special requirement to produce | |
| 219 well-formed XML, you should probably use the **html** option for your web sites. | |
| 220 | |
| 221 .. _`Understanding HTML, XML and XHTML`: http://webkit.org/blog/?p=68 | |
| 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 | 233 ``genshi.lookup_errors`` |
| 234 ------------------------ | |
| 235 The error handling style to use in template expressions. Can be either | |
| 236 **lenient** (the default) or **strict**. See the `Error Handling`_ section for | |
| 237 detailled information on the differences between these two modes. | |
| 238 | |
| 239 .. _`Error Handling`: templates.html#template-expressions-and-code-blocks | |
| 240 | |
| 241 ``genshi.max_cache_size`` | |
| 242 ------------------------- | |
| 243 The maximum number of templates that the template loader will cache in memory. | |
| 244 The default value is **25**. You may want to choose a higher value if your web | |
| 245 site uses a larger number of templates, and you have enough memory to spare. | |
| 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 | 257 ``genshi.search_path`` |
| 258 ---------------------- | |
| 259 A colon-separated list of file-system path names that the template loader should | |
| 260 use to search for templates. |