Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

96 lines (62 sloc) 4.498 kb
Template Language Plugins
+++++++++++++++++++++++++
Pylons supports a variety of template languages in addition to Myghty 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 <http://projects.dowski.com/projects/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 <install.html>`_) you will need to install the appropriate Buffet plugin. In the case
of Kid, this is called TurboKid and can be installed as follows::
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::
~/yourproject% mkdir yourproject/kidtemplates
~/yourproject% 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/middleware.py``, and add to 'config.init_app....':
.. code-block:: Python
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:
.. code-block:: Python
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 (Myghty, 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:
.. code-block:: XML
<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 Myghty 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 Myghty to your choice. Let's make Kid the default template engine.
Edit ``yourproject/config/middleware.py``, right after the 'config.init_app....':
.. code-block:: Python
config.init_app(global_conf, app_conf, package='yourproject',
template_engine='kid')
This swaps Myghty 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 <class-pylons.config.Config.html>`_ from the Pylons Module API.
Jump to Line
Something went wrong with that request. Please try again.