back

Your free e-book!

See when it is not worth using Scrum.
"Why Scrum Doesn't Work" Download

Integrating Mako with Django 1.8 template backend subsystem

Django 1.8 release is coming soon, and one of the new important features is
support for multiple template engines. Allowing to choose between template engines is mostly caused by the need for greater performance in complex templates and a more convenient API for custom tags. It’s also interesting to note that the integrating Mako was funded with an indiegogo campaign. If you want to read more about the development process – head to Aymeric Augustin’s blog.

From the developers perspective 1.8 will change the way templates options are declared in settings (though of course old settings will remain compatible for some period of time). As for built-in backends DTL(Django template language) will still be the default, and Jinja2 support will also be an official part of the new release.

In this article, I’ll show you how to write your own template backend – since
Jinja2 is already there, I’ve chosen another popular engine – Mako.

Writing the custom backend

According to Django docs, writing a custom backend should be very easy, We need one class inheriting BaseEngine that will return Template objects for us – those can be again our custom classes, as long as they have a render method, accepting context and request parameters.

Django source code and docs even contain example code for that, let’s go
through it, as there are some parts that may seem odd:


from django.template import TemplateDoesNotExist, TemplateSyntaxError  
from django.template.backends.base import BaseEngine  
from django.template.backends.utils import csrf_input_lazy, csrf_token_lazy

import foobar


class FooBar(BaseEngine):

    # Name of the subdirectory containing the templates for this engine
    # inside an installed application.
    app_dirname = 'foobar'

    def __init__(self, params):
        params = params.copy()
        options = params.pop('OPTIONS').copy()
        super(FooBar, self).__init__(params)

        self.engine = foobar.Engine(**options)


    def from_string(self, template_code):
        try:
          return Template(self.engine.from_string(template_code))
        except foobar.TemplateCompilationFailed as exc:
            raise TemplateSyntaxError(exc.args)

    def get_template(self, template_name):
        try:
            return Template(self.engine.get_template(template_name))
        except foobar.TemplateNotFound as exc:
            raise TemplateDoesNotExist(exc.args)
        except foobar.TemplateCompilationFailed as exc:
            raise TemplateSyntaxError(exc.args)


class Template(object):

    def __init__(self, template):
        self.template = template

    def render(self, context=None, request=None):
        if context is None:
            context = {}
        if request is not None:
            context['request'] = request
            context['csrf_input'] = csrf_input_lazy(request)
            context['csrf_token'] = csrf_token_lazy(request)
        return self.template.render(context)

In order to use the backend you should also modify your settings file, like this:


TEMPLATES = [  
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.template.context_processors.tz',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
    {
        'BACKEND': 'mako_template_app.mako_template_backend.MakoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.template.context_processors.tz',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        }
    }
]

The idea is very simple:

  • implement a class that inherits from BaseEngine
  • implements from_string
  • implement get_template
  • they should return an object that has a render(self, context=None, request=None) signature

I’ve actually tried doing that, and the first thing I got was an error
screen with “A server error occurred. Please contact the administrator.”
message – not the usual Django detailed error page, only this one sentence. The background runserver process also spit out an enormous stack trace. I started digging, and making my code look more and more like the example one. Finally, the lines that helped were:


params = params.copy()  
options = params.pop('OPTIONS').copy()  

And the lines that were causing the error were in the BaseEngine init implementation:


    def __init__(self, params):
        params = params.copy()
        self.name = params.pop('NAME')
        self.dirs = list(params.pop('DIRS'))
        self.app_dirs = bool(params.pop('APP_DIRS'))
        if params:
            raise ImproperlyConfigured(
                "Unknown parameters: {}".format(", ".join(params)))

So – my settings.py specified some options for the backend, but since the initial version of my __init__ did not clear them, there was the exception, but since the template backends were not set up, I could not see the detailed error message in the browser.

With that fixed, the rest of the code was relatively easy to write – at least errors messages were more comprehensive. One more thing stood out of the example for me – the render method of the template object, which looks like this:


def render(self, context=None, request=None):
if context is None:
context = {}
if request is not None:
context['request'] = request
context['csrf_input'] = csrf_input_lazy(request)
context['csrf_token'] = csrf_token_lazy(request)
return self.template.render(context)

What’s the reason for the contextmanipulation here, shouldn’t this be done somewhere else – like in the contextprocessors I’ve specified?. Well, it turns out, that only the Django template engine supports contextprocessors – even built-in Jinja2 does not have support them. This is kind of unfortunate – especially, since contextprocessors are just functions that take request as input, and return a dictionary of necessary context updates as output (side note: django mailing list has a discussion about whether context processors are needed at all – read about it here). Equipped with that knowledge I’ve started my second take on incorporating Mako. This is the result:


class CustomTemplateBackend(BaseEngine):  
    def __init__(self, params):
        params = params.copy()
        options = params.pop('OPTIONS').copy()
        super(CustomTemplateBackend, self).__init__(params)
        self.context_processors = []
        if 'context_processors' in options:
            self.context_processors = options.pop('context_processors')
        self.init_engine(options)

    @cached_property
    def template_context_processors(self):
        context_processors = _builtin_context_processors
        context_processors += tuple(self.context_processors)
        return tuple(import_string(path) for path in context_processors)


class MakoTemplates(CustomTemplateBackend):  
    app_dirname = 'mako'

    def init_engine(self, options):
        self.lookup = TemplateLookup(directories=self.template_dirs, **options)

    def from_string(self, template_code):
        try:
            return MakoTemplateWrapper(self, Template(template_code))
        except SyntaxException as exc:
            six.raise_from(TemplateSyntaxError, exc)

    def get_template(self, template_name):
        try:
            return MakoTemplateWrapper(self, self.lookup.get_template(template_name))
        except TemplateLookupException as exc:
            six.raise_from(TemplateDoesNotExist, exc)
        except SyntaxException as exc:
            six.raise_from(TemplateSyntaxError, exc)


class ContextProcessorTemplate(object):  
    def __init__(self, engine, template):
        self.engine = engine
        self.template = template

    def render(self, context=None, request=None):
        if context is None:
            context = {}
        for processor in self.engine.template_context_processors:
            context.update(processor(request))
        return self.render_internal(context)


class MakoTemplateWrapper(ContextProcessorTemplate):  
    def render_internal(self, context):
        return self.template.render(**context)

Let’s go through important modifications:

  • First of all, I’ve extracted the quirks of BaseEngine inheritance into CustomTemplateBackend. This class can be reused if I ever decide to write backends for other templating engines, and I won’t have to worry about popping OPTIONS again.
  • The second change involves using templatecontextprocessors – This code is mostly taken from Django source code – the Engine class (used internally by DjangoEngine which extends BaseEngine) and RequestContext. With that, I can support existing context processors and don’t have to remember about quirks in my template wrapper objects. This class can also be reused by other backends.
  • MakoTemplates initializes TemplateLookup (which is roughly equivalent of Jinja2 environment, with any options provided in the settings) – so user have control over mako initialization – for example, they can set the filter_exception flag to true, to get a better insight into why template rendering failed. An alternative would be to let users specify a custom callable that would return Lookup (in a similar way Jinja2 backend environment setting work)
  • from_string and get_template translate mako specific exceptions into django specific ones – to keep code compatible with both python 3, and python 2 we use six.raise_from
  • app_dirname specifies the default directory to look for templates, for DTL this is the familiar ‘templates’, for other backends, it’s best to use an unique name. Additional directories can be also set in settings.

Referencing the templates from your view functions:

This is actually quite easy – the render call does not change


def hello(request):  
    return render(request, 'mako_template_app/hello.mako.html', {})

This has one caveat though – If you have several template backend defined (and chances are, you have – for example you want to use Jinja2 for your templates and Django for admin pages) – each of them is being scanned for the template, which can slightly reduce your performance. As for now, the render method does not provide a way to select the template backend, but django.template.loader exposes methods with using a parameter with which you can explicitly specify the desired backend and skip the exhaustive search.

Software Engineers - development team

Wrap-up

Although currently there are some quirks in the API (at the moment of writing this article Django 1.8 was at the alpha stage), the support for multiple template engines in Django looks promising and is not difficult to use – and once the release date approaches packages for integrating most popular engines will most likely be already available.

Hope you enjoyed the read, if we didn’t dispel your doubts please let us know. We’d love to help you – click here!


cto - Chris Gibas

Free 30-minute consultation with our CTO

Chris Gibas - our CTO will be happy to discuss your project! Let's talk!

More blog posts
How we joined our client to speed up product development

Julianna Sykutera

How we joined our client to speed up product development

The process of insurance claim reporting requires a lot of effort and patience. Not to mention, it’s very often unclear on what condition a claim has been rejected or accepted by agents. On the other hand, insurance companies and brokers spend a lot of time verifying received applications and preparing suitable documents. Where in fact, all of these could be […]

5 reasons to build your digital product with Idego

Okay, so we’re at the point where we all already know that you need some software help (either that or our marketing department did a sloppy job bringing you here ;)). You did some research, found some interesting providers and now you’re facing a tough business decision of choosing a vendor. You’re not buying cookies from scout girls, of course, […]

5 reasons to build your digital product with Idego

Adam Grabowski

Building apps with Python – What does the process look like?

Idego

Substantive support - Julianna Sykutera

Building apps with Python – What does the process look like?

The process of developing an application can take place in many different ways. It all depends on the complexity of the project and the experts entrusted with the task. This is because the project can be carried out with the help of programmers working within the organisation, or it can be entrusted to a dedicated external team. Such a solution […]

The Best Web Applications We All Use on a Regular Basis

Web applications began to grow in importance as developers gained the expertise and technology needed to turn static web pages into highly functional and interactive browser-based programs. We all use such applications almost every day.  Which companies use web applications? What does the process of creating them look like? What is a web application? A web application, due to the […]

The Best Web Applications We All Use on a Regular Basis

Idego

Substantive support - Julianna Sykutera

Get a free estimation

Need a successful project?