cmlenz@445: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@445: 
cmlenz@445: ===========================
cmlenz@445: Using the Templating Plugin
cmlenz@445: ===========================
cmlenz@445: 
cmlenz@445: While you can easily use Genshi templating through the APIs provided directly
cmlenz@445: by Genshi, in some situations you may want to use Genshi through the template
cmlenz@445: engine plugin API. Note though that this considerably limits the power and
cmlenz@445: flexibility of Genshi templates (for example, there's no good way to use filters
cmlenz@445: such as Genshi's `HTMLFormFiller`_ when the plugin
cmlenz@445: API is sitting between your code and Genshi).
cmlenz@445: 
cmlenz@445: .. _`HTMLFormFiller`: filters.html>#html-form-filler
cmlenz@445: 
cmlenz@445: 
cmlenz@445: .. contents:: Contents
cmlenz@445:    :depth: 2
cmlenz@445: .. sectnum::
cmlenz@445: 
cmlenz@445: 
cmlenz@445: Introduction
cmlenz@445: ============
cmlenz@445: 
cmlenz@769: Some Python web frameworks support a variety of different templating engines
cmlenz@769: through the `Template Engine Plugin API`_, which was first developed by the
cmlenz@769: Buffet_ and TurboGears_ projects.
cmlenz@445: 
cmlenz@445: .. _`Template Engine Plugin API`: http://docs.turbogears.org/1.0/TemplatePlugins
cmlenz@445: .. _`Buffet`: http://projects.dowski.com/projects/buffet
cmlenz@445: .. _`TurboGears`: http://www.turbogears.org/
cmlenz@445: 
cmlenz@445: Genshi supports this API out of the box, so you can use it in frameworks like
cmlenz@445: TurboGears or `Pylons`_ without installing any additional packages. A small
cmlenz@445: example TurboGears application is included in the ``examples`` directory of
cmlenz@445: source distributions of Genshi.
cmlenz@445: 
cmlenz@445: .. _`Pylons`: http://pylonshq.com/
cmlenz@445: 
cmlenz@445: 
cmlenz@445: Usage
cmlenz@445: =====
cmlenz@445: 
cmlenz@445: The way you use Genshi through the plugin API depends very much on the framework
cmlenz@445: you're using. In general, the approach will look something like the following:
cmlenz@445: 
cmlenz@445: (1) Configure Genshi as the default (or an additional) template engine
cmlenz@445: (2) Optionally specify Genshi-specific `configuration options`_
cmlenz@445: (3) For any given *view* or *controller* (or whatever those are called in your
cmlenz@445:     framework of choice), specify the name of the template to use and which data
cmlenz@445:     should be made available to it.
cmlenz@445: 
cmlenz@445: For point 1, you'll have to specify the *name* of the template engine plugin.
cmlenz@445: For Genshi, this is **"genshi"**. However, because Genshi supports both markup
cmlenz@445: and text templates, it also provides two separate plugins, namely
cmlenz@445: **"genshi-markup"** and **"genshi-text"** (the "genshi" name is just an
cmlenz@445: alias for "genshi-markup").
cmlenz@445: 
cmlenz@445: Usually, you can choose a default template engine, but also use a different
cmlenz@445: engine on a per-request basis. So to use markup templates in general, but a text
cmlenz@445: template in a specific controller, you'd configure "genshi" as the default
cmlenz@445: template engine, and specify "genshi-text" for the controllers that should use
cmlenz@445: text templates. How exactly this works depends on the framework in use.
cmlenz@445: 
cmlenz@445: When rendering a specific template in a controller (point 3 above), you may also
cmlenz@445: be able to pass additional options to the plugin. This includes the ``format``
cmlenz@445: keyword argument, which Genshi will use to override the configured default
cmlenz@445: serialization method. In combination with specifying the "genshi-text" engine
cmlenz@445: name as explained above, you would use this to specify the "text" serialization
cmlenz@445: method when you want to use a text template. Or you'd specify "xml" for the
cmlenz@445: format when you want to produce an Atom feed or other XML content.
cmlenz@445: 
cmlenz@445: 
cmlenz@769: Template Paths
cmlenz@769: --------------
cmlenz@769: 
cmlenz@769: How you specify template paths depends on whether you have a `search path`_ set
cmlenz@769: up or not. The search path is a list of directories that Genshi should load
cmlenz@769: templates from. Now when you request a template using a relative path such as
cmlenz@769: ``mytmpl.html`` or ``foo/mytmpl.html``, Genshi will look for that file in the
cmlenz@769: directories on the search path.
cmlenz@769: 
cmlenz@769: For mostly historical reasons, the Genshi template engine plugin uses a
cmlenz@769: different approach when you **haven't** configured the template search path:
cmlenz@769: you now load templates using *dotted notation*, for example ``mytmpl`` or
cmlenz@769: ``foo.mytmpl``.  Note how you've lost the ability to explicitly specify the
cmlenz@769: file extension: you now have to use ``.html`` for markup templates, and
cmlenz@769: ``.txt`` for text templates.
cmlenz@769: 
cmlenz@769: Using the search path is recommended for a number of reasons: First, it's
cmlenz@769: the native Genshi model and is thus more robust and better supported.
cmlenz@769: Second, a search path gives you much more flexibility for organizing your
cmlenz@769: application templates. And as noted above, you aren't forced to use hardcoded
cmlenz@769: filename extensions for your template files.
cmlenz@769: 
cmlenz@769: 
cmlenz@445: Extra Implicit Objects
cmlenz@769: ----------------------
cmlenz@445: 
cmlenz@445: The "genshi-markup" template engine plugin adds some extra functions that are
cmlenz@445: made available to all templates implicitly, namely:
cmlenz@445: 
cmlenz@445: ``HTML(string)``
cmlenz@445:   Parses the given string as HTML and returns a markup stream.
cmlenz@445: ``XML(string)``
cmlenz@445:   Parses the given string as XML and returns a markup stream.
cmlenz@445: ``ET(tree)``
cmlenz@445:   Adapts the given `ElementTree`_ object to a markup stream.
cmlenz@445: 
cmlenz@445: The framework may make additional objects available by default. Consult the
cmlenz@445: documentation of your framework for more information.
cmlenz@445: 
cmlenz@445: .. _elementtree: http://effbot.org/zone/element-index.htm
cmlenz@445: 
cmlenz@445: 
cmlenz@445: .. _`configuration options`:
cmlenz@445: 
cmlenz@445: Configuration Options
cmlenz@445: =====================
cmlenz@445: 
cmlenz@445: The plugin API allows plugins to be configured using a dictionary of strings.
cmlenz@445: The following is a list of configuration options that Genshi supports. These may
cmlenz@445: or may not be made available by your framework. TurboGears 1.0, for example,
cmlenz@445: only passes a fixed set of options to all plugins.
cmlenz@445: 
cmlenz@545: ``genshi.allow_exec``
cmlenz@545: --------------------------
cmlenz@545: Whether the Python code blocks should be permitted in templates. Specify "yes"
cmlenz@545: to allow code blocks (which is the default), or "no" otherwise. Please note
cmlenz@545: that disallowing code blocks in templates does not turn Genshi into a
cmlenz@545: sandboxable template engine; there are sufficient ways to do harm even using
cmlenz@545: plain expressions.
cmlenz@545: 
cmlenz@445: ``genshi.auto_reload``
cmlenz@445: ----------------------
cmlenz@445: Whether the template loader should check the last modification time of template 
cmlenz@445: files, and automatically reload them if they have been changed. Specify "yes"
cmlenz@445: to enable this reloading (which is the default), or "no" to turn it off.
cmlenz@445: 
cmlenz@548: You probably want to disable reloading in a production environment to improve
cmlenz@548: performance of both templating loading and the processing of includes. But
cmlenz@548: remember that you'll then have to manually restart the server process anytime
cmlenz@548: the templates are updated.
cmlenz@445: 
cmlenz@445: ``genshi.default_doctype``
cmlenz@445: --------------------------
cmlenz@445: The default ``DOCTYPE`` declaration to use in generated markup. Valid values
cmlenz@445: are:
cmlenz@445: 
cmlenz@445: **html-strict** (or just **html**)
cmlenz@445:   HTML 4.01 Strict
cmlenz@445: **html-transitional**
cmlenz@445:   HTML 4.01 Transitional
cmlenz@445: **xhtml-strict** (or just **xhtml**)
cmlenz@445:   XHTML 1.0 Strict
cmlenz@445: **xhtml-transitional**
cmlenz@445:   XHTML 1.0 Transitional
cmlenz@448: **html5**
cmlenz@448:   HTML5 (as `proposed`_ by the WHAT-WG)
cmlenz@448: 
cmlenz@448: .. _proposed: http://www.whatwg.org/specs/web-apps/current-work/
cmlenz@445: 
cmlenz@445: .. note:: While using the Genshi API directly allows you to specify document
cmlenz@445:           types not in that list, the *dictionary-of-strings* based
cmlenz@445:           configuration utilized by the plugin API unfortunately limits your
cmlenz@445:           choices to those listed above.
cmlenz@445: 
cmlenz@445: The default behavior is to not do any prepending/replacing of a ``DOCTYPE``, but
cmlenz@445: rather pass through those defined in the templates (if any). If this option is
cmlenz@445: set, however, any ``DOCTYPE`` declarations in the templates are replaced by the
cmlenz@445: specified document type.
cmlenz@445: 
cmlenz@445: Note that with (X)HTML, the presence and choice of the ``DOCTYPE`` can have a
cmlenz@445: more or less dramatic impact on how modern browsers render pages that use CSS
cmlenz@445: style sheets. In particular, browsers may switch to *quirks rendering mode* for
cmlenz@445: certain document types, or when the ``DOCTYPE`` declaration is missing
cmlenz@445: completely.
cmlenz@445: 
cmlenz@445: For more information on the choice of the appropriate ``DOCTYPE``, see:
cmlenz@445: 
cmlenz@445: * `Recommended DTDs to use in your Web document <http://www.w3.org/QA/2002/04/valid-dtd-list.html>`_
cmlenz@445: * `Choosing a DOCTYPE <http://htmlhelp.com/tools/validator/doctype.html>`_
cmlenz@445: 
cmlenz@445: ``genshi.default_encoding``
cmlenz@445: ---------------------------
cmlenz@445: The default output encoding to use when serializing a template. By default,
cmlenz@445: Genshi uses UTF-8. If you need to, you can choose a different charset by
cmlenz@445: specifying this option, although that rarely makes sense.
cmlenz@445: 
cmlenz@445: As Genshi is not in control over what HTTP headers are being sent together with
cmlenz@445: the template output, make sure that you (or the framework you're using)
cmlenz@445: specify the chosen encoding as part of the outgoing ``Content-Type`` header.
cmlenz@445: For example::
cmlenz@445: 
cmlenz@445:   Content-Type: text/html; charset=utf-8
cmlenz@445: 
cmlenz@445: .. note:: Browsers commonly use ISO-8859-1 by default for ``text/html``, so even
cmlenz@445:           if you use Genshi's default UTF-8 encoding, you'll have to let the
cmlenz@445:           browser know about that explicitly
cmlenz@445: 
cmlenz@445: ``genshi.default_format``
cmlenz@445: -------------------------
cmlenz@445: Determines the default serialization method to use. Valid options are:
cmlenz@445: 
cmlenz@445: **xml**
cmlenz@445:   Serialization to XML
cmlenz@445: **xhtml**
cmlenz@445:   Serialization to XHTML in a way that should be compatible with HTML (i.e. the
cmlenz@445:   result can be sent using the ``text/html`` MIME type, but can also be handled
cmlenz@445:   by XML parsers if you're careful).
cmlenz@445: **html**
cmlenz@445:   Serialization to HTML
cmlenz@445: **text**
cmlenz@445:   Plain text serialization
cmlenz@445: 
cmlenz@445: See `Understanding HTML, XML and XHTML`_ for an excellent description of the
cmlenz@445: subtle differences between the three different markup serialization options. As
cmlenz@445: a general recommendation, if you don't have a special requirement to produce
cmlenz@445: well-formed XML, you should probably use the **html** option for your web sites.
cmlenz@445: 
cmlenz@445: .. _`Understanding HTML, XML and XHTML`: http://webkit.org/blog/?p=68
cmlenz@445: 
cmlenz@538: ``genshi.loader_callback``
cmlenz@538: --------------------------
cmlenz@538: The callback function that should be invoked whenever the template loader loads
cmlenz@538: a new template.
cmlenz@538: 
cmlenz@538: .. note:: Unlike the other options, this option can **not** be passed as
cmlenz@538:           a string value, but rather must be a reference to the actual function.
cmlenz@538:           That effectively means it can not be set from (non-Python)
cmlenz@538:           configuration files.
cmlenz@538: 
cmlenz@445: ``genshi.lookup_errors``
cmlenz@445: ------------------------
cmlenz@445: The error handling style to use in template expressions. Can be either
cmlenz@445: **lenient** (the default) or **strict**. See the `Error Handling`_ section for
cmlenz@445: detailled information on the differences between these two modes.
cmlenz@445: 
cmlenz@445: .. _`Error Handling`: templates.html#template-expressions-and-code-blocks
cmlenz@445: 
cmlenz@445: ``genshi.max_cache_size``
cmlenz@445: -------------------------
cmlenz@445: The maximum number of templates that the template loader will cache in memory.
cmlenz@445: The default value is **25**. You may want to choose a higher value if your web
cmlenz@445: site uses a larger number of templates, and you have enough memory to spare.
cmlenz@445: 
cmlenz@592: ``genshi.new_text_syntax``
cmlenz@592: --------------------------
cmlenz@592: Whether the new syntax for text templates should be used. Specify "yes" to
cmlenz@592: enable the new syntax, or "no" to use the old syntax.
cmlenz@592: 
cmlenz@592: In the version of Genshi, the default is to use the old syntax for
cmlenz@592: backwards-compatibility, but that will change in a future release.
cmlenz@592: 
cmlenz@769: .. _`search path`:
cmlenz@769: 
cmlenz@445: ``genshi.search_path``
cmlenz@445: ----------------------
cmlenz@445: A colon-separated list of file-system path names that the template loader should
cmlenz@445: use to search for templates.