Template Language Plugins

Pylons supports a variety of template languages in addition to Mako through the use of template engine plug-ins. This can be useful both for migrating web applications to Pylons, or in cases where you just would rather prefer some other templating solution.

Template language plug-ins can be installed rather easily using setuptools. A current list of template engine plug-ins is at the Buffet website.

Once you have installed one of these, using the new template language within Pylons is quite easy. As Pylons does not come pre-configured with this in mind, you will need to do a little more work yourself depending on which template language you're using.

Example: Using Kid with Pylons

If you didn't select the kid optional extra package when you installed Pylons (described on the install page) you will need to install the appropriate Buffet plugin. In the case of Kid, this is called TurboKid and can be installed as follows:

1	$ easy_install TurboKid

To use Kid with Pylons, first we must setup a new template directory for the Kid templates.

First, create a directory in yourproject called kidtemplates and add a controller:

1
2
3

$ cd yourproject
$ mkdir yourproject/kidtemplates
$ paster controller kid

You will now have a kid.py controller in your controllers directory. First, we will need to add Kid to the available template engines.

Edit yourproject/config/environment.py add to the bottom of the load_environment function:

1 2	kidopts = {'kid.assume_encoding':'utf-8', 'kid.encoding':'utf-8'} config.add_template_engine('kid', 'yourproject.kidtemplates', kidopts)

Edit the KidController class so it looks like this:

class KidController(BaseController):
    def index(self):
        c.title = "Your Page"
        c.message = 'hi'
        return render_response('kid', 'test')

Make sure to change yourproject.kidtemplates to reflect what your project is actually called. The first argument to render or render_response can be the template engine to use, while the second non-keyword argument is the template. If you don't specify a template engine, it will drop back to the default (Mako, unless you change the default).

Now let's add the Kid template to render, create the file yourproject/kidtemplates/test.kid with the following content:

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://purl.org/kid/ns#">
    <head>
        <title py:content="c.title">title</title>
    </head>
    <body>
        <p py:content="c.message">message</p>
        <p>You made it to the following url: ${h.url_for()}</p>
    </body>
</html>

Since the template plug-ins currently expect paths to act as module imports, you will also need to create a __init__.py file inside yourproject/kidtemplates.

Loading /kid will now return the Kid template that you have created.

Notice that all the same Pylons variables are made accessible to template engine plug-ins. You will have c, h, g, session, and request available in any template language you choose to use. This also makes it easier to switch later to Mako or a different template language without having to update your controller action.

Switching the Default Template Engine

In Pylons, customization is not just allowed but actively encouraged. It's quite easy to change the default engine from Mako to your choice. Let's make Kid the default template engine.

Edit yourproject/config/environment.py and change the template_engine argument passed to config.init_app:

1 2	config.init_app(global_conf, app_conf, package='yourproject', template_engine='kid', paths=paths)

This swaps Mako out and uses Kid, making Kid the new default template engine. The above index method no longer needs to specify 'kid' now when rendering a template. The existing templates directory will be used, and you'll need to create the __init__.py file before adding Kid templates. Current template engine's that can be swapped in this manner are kid, mako, and genshi.

Note

For more details on the config object, check out the extensive Config docs from the Pylons Module API.