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