Configuration¶

Typical configuration example (YAML):

tool.ext.templating.JinjaPlugin: null

This configuration preserves the default values. See section “Overriding templates” below for more information on configuration options.

Of course you can replace JinjaPlugin with MakoPlugin.

Usage¶

Simple example (assuming that the code is in my_extension/__init__.py):

from tool import app
from tool.plugins import BasePlugin

class Foo(BasePlugin):
    def make_env(self):
        t = app.get_feature('templating')
        t.register_templates(__name__)

In this case the absolute path to templates will be constructed from module location and the default name for template directory, i.e. something like /path/to/my_extension/templates/.

The templates will be available as my_extension/template_name.html.

Advanced usage:

t.register_templates('proj.extension_foo', 'data/tmpl/', prefix='proj')

In this case the absolute path to templates will be something like /path/to/proj/extension_foo/data/tmpl/.

The templates will be available as proj/template_name.html.

Bundle templates¶

Jinja2 provides excellent means to configure the way templates are located and loaded. Tool looks up the template in this order:

• the project-level search paths (first full match wins);
• the registered prefixes (i.e. the path starts with a known extension name).

The prefixes can be registered with register_templates(). For example, we have created an extension with this layout:

my_extension/
    templates/
        foo.html
    __init__.py

To register the extension’s templates, add this to its __init__.py:

from tool.ext.templating import register_templates

register_templates(__name__)

This will make our foo.html globally available as my_extension/foo.html.

There are other ways to register the templates. Please consult the code to find them out. Anyway, templates must be registered explicitly. Tool lets you organize the extensions the way you want and therefore expects that you tell what is where.

Overriding templates¶

Web-oriented Tool extensions usually provide templates. Sometimes you’ll want to replace certain templates. Let’s say we are not comfortable with a default Admin template and want to override it. Let’s create a project-level directory for templates and put our customized templates there:

some_site/
    templates/
        admin/
            object_list.html
    conf.yaml
    manage.py

As you see, the template path within templates/ will be admin/object_list.html (admin is the natural template prefix for tool.ext.admin, see register_templates() for details).

Now let’s edit out conf.yaml and let the application know about the templates/ directory:

extensions:
    tool.ext.templating.JinjaPlugin:
        searchpaths: ['templates']

Well, actually this is the default setting. If searchpaths is not defined at all, it is assumed to be ['templates'].

Now the template admin/object_list.html will be picked from the templates/ directory. All other admin templates remain defaults.

This way you can override any bundle’s template.

API reference¶

Both JinjaPlugin and MakoPlugin provide two important methods: register_templates to declare the template directories, and render_template to actually use them.

class tool.ext.templating.JinjaPlugin(app, conf)¶

Offers integration with Jinja2.

register_templates(module_path, dir_name='templates', prefix=None)¶

Registers given extension’s templates in the template loader.

Parameters:	module_path – The dotted path to the bundle module. The absolute path to the templates will depend on the module location. dir_name – Templates directory name within given module. Default is templates. Relative to module’s __file__. prefix – The prefix for templates. By default the rightmost part of the module name is used e.g. tool.ext.admin will have the prefix admin.

class tool.ext.templating.MakoPlugin(app, conf)¶

Offers integration with Mako.

register_templates(module_path, dir_name='templates', prefix=None)¶

Registers given extension’s templates in the template loader.

Parameters:	module_path – The dotted path to the bundle module. The absolute path to the templates will depend on the module location. dir_name – Templates directory name within given module. Default is templates. Relative to module’s __file__. prefix – The prefix for templates. By default the rightmost part of the module name is used e.g. tool.ext.admin will have the prefix admin.

render_template(path, context)¶

Renders given template file with given context and returns the result.

Parameters:	path – Path to the template file. Should be previously registered with register_templates() and/or belong to the directories listed is searchpaths (see configuration). context – A dictionary.

tool.ext.templating.as_html(template_path)¶

Decorator for views. If the view returns a dictionary, given template is rendered with that dictionary as the context. If the returned value is not a dictionary, it is passed further as is.

Internally calls render_response().

tool.ext.templating.register_templates(module_path, dir_name='templates', prefix=None)¶

See JinjaPlugin.register_templates() and MakoPlugin.register_templates().

tool.ext.templating.render_template(template_path, **extra_context)¶

Renders given template file with given context.

Template_path:	path to the template; must belong to one of directories listed in searchpaths (see configuration).

tool.ext.templating.render_response(template_path, mimetype='text/html', **extra_context)¶

TODO

Internally calls render_template().