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