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.
