Buffet 0.6 introduced support for an open template plugin system. Version 1.0 is the current recommended version.

Introduction

Buffet provides a common API for using multiple templating languages with CherryPy. By changing as little as one argument in your code you can switch between the following templating systems:

• Cheetah
• CherryTemplate (up to 0.4)
• Kid
• Myghty
• Python 2.4 String Templates
• XSLT
• Nevow STAN (retired)
• Formencode.htmlgen
• Breve
• Genshi
• Mako

You can also use different template engines for different sections of your site, playing to the strengths of each templating system.

Download and Install

Cross-Platform: Download the compressed source below, decompress it and run python setup.py install. You can now also use easy_install Buffet if you have the setuptools package installed.

Windows: Download the exe file below, double-click it and follow the prompts.

Usage

CherryPy is intentionally and wonderfully templating language care-free. You can use whatever templating language you like (or none at all!). However, you have to deal with each language and its engine at a low level in your page handlers.

When using Buffet, you instantiate the filter for a section of your site using one of the supported templating languages. Then, all your page handlers have to do is return a tuple containing the path to your template file and a dictionary of key:value pairs to pass to the template. For simplicty, a decorator, using_template(tmpl_path), is included so that you only need to return the dictionary in your page handler and the decorator wraps it in a tuple with the template path.

Here is a quick example:

import cherrypy
from buffet import TemplateFilter, using_template

class CheetahSection(object):
    # the filter takes two arguments: 
    # the name of the template engine to use
    # and the base path to look for templates
    # this example requires the TurboCheetah plugin
    # TurboCheetah requires that the templates be contained
    # in a Python package hierarchy (folders with an 
    # __init__.py in them
    _cp_filters = [TemplateFilter('cheetah', 'media/my_templates')]

    # here we expose the page handler and tell it what template to use
    @cherrypy.expose
    @using_template('index_template')
    def index(self):
        # all we have to do is return a dict
        # with the variables expected by the template as keys
        return dict(title="Cheetah Test", message="Hello, Cheetah")

Page Composition with Templates

Versions 0.9 and later support composing single pages of multiple templates from within Buffet. For example:

class Root(object):
    @cherrypy.expose
    def multi_test(self):
        return (
                ('head', # template name
                    dict(title="Composition Test") # data for template
                    ),
                ('body', # and so on ...
                    dict(message="Thanks to Bill Mill")
                    ),
                ('foot', {}
                    )
                )

Plugins

Starting with version 0.6, Buffet no longer includes built-in template support. Instead, it relies on plugins that publish entry points in the 'python.templating.engines' entry point group. Here is a list of some of the currently compatible plugins:

• TurboCheetah - Cheetah template support
• TurboKid - Kid template support
• TurboStan - Nevow Stan support
• BuffetString - simple Python 'string.Template' support
• BuffetMyghty - Myghty template support
• BuffetXSLT - XSLT support using Amara
• Genshi - includes its own plugin
• Mako - includes its own plugin
• Breve - includes its own plugin

Generally, plugins can be installed through easy_install (easy_install [PluginName]). You can create plugins for other templating engines by following the instructions at the plugin specification page.

TemplateFilter

Supported first arguments for the TemplateFilter are the plugin entry point names - typically the name of the templating package in lowercase ('cheetah', 'myghty', etc).

Support/Questions/Suggestions

For questions regarding Buffet, please feel free to email me (christian [shift] + 2 dowski.com) or catch me on IRC at #cherrypy on oftc.net. I'll do my best to answer questions regarding third-party plugins as well, but it is probably best to contact the plugin maintainer.

Forks

The Pylons project uses a fork of Buffet for universal templating.

Thanks ...

... to Sylvain Hellegouarch for CherryTemplate and XSLT support in 0.4. ... to Kevin Dangoor for proposing the idea to share code between Buffet and TurboGears and for introducing me to entry points. ... to Ulrich Schreiner for alerting me to the bug fixed in 0.8 (and tweaked in 0.9). ... to Bill Mill for the template composition support introduced in 0.9.

Changelog

• 1.0 - unit tests and flexible options for using Buffet when hosting multiple apps
• 0.9 - integrated template page composition patch from Bill Mill.
• 0.8 - fixed bug that removed newlines from template output.
• 0.7 - moved plugin initialization to filter initialization.
• 0.6 - support for pluggable template engine architecture.
• 0.4 - support for CherryTemplate and XSLT.
• 0.2 - initial release.

Subversion

Subversion hosting courtesy of Bill Mill.