Mako for Django

Mako powered template backend for
Django.

Overview
Motivation
Installation
Usage
Tutorial
References
Name
License

Overview

This backend integrates Mako directly into Django's template engine API. It
supports Django's configuration, template discovery within app directories, and
context processors, while extending them with Mako's syntax, performance, and
detailed error handling.

Preview: Contextual line information

Preview: Runtime errors

Preview: Template postmortem

Motivation

Mako's multi-zoned inheritance feature can be used with the <%def> tag to
encapsulate structure and behavior, enabling modular and maintainable
templates. This approach provides a component-like system similar to
React
(JSX) or other modern
frameworks that support props and named/default slots. For technical details,
see the Defs and Blocks
section in the Mako documentation.

Demonstration

Component definition: button.html.mako

<%def
  name="base_button(
    class_name=None,
    icon=None,
    label=None,
    round=False,
    rounded=False,
  )"
>
  <button
    class="${ clsx([
      'button',
      ('button--round', round),
      ('button--rounded', rounded),
      class_name,
    ]) }"
  >
    % if icon:
      <span class="button__icon">
        ${ icon() }
      </span>
    % endif
    % if label:
      <span class="button__label">
        ${ label() }
      </span>
    % endif
  </button>
</%def>

<%def name="basic_button(class_name=None, rounded=False)">
  <%self:base_button
    class_name="${ ['button--basic', class_name] }"
    icon="${ getattr(caller, 'icon', None) }"
    label="${ getattr(caller, 'label', None) }"
    rounded="${ rounded }"
  />
</%def>

<%def name="icon_button(class_name=None, round=False)">
  <%self:base_button
    class_name="${ ['button--icon', class_name] }"
    icon="${ getattr(caller, 'body', None) }"
    round="${ round }"
  />
</%def>

The clsx function is a utility for managing class-names dynamically. It's
imported from the
clsx-py
project.

Component usage: page.html.mako

<%namespace name="button" file="button.html.mako" />

<%button:icon_button class_name="sample-button">
  ➖
</%button:icon_button>

<%button:icon_button class_name="sample-button" round="${ True }">
  ➕
</%button:icon_button>

<%button:basic_button class_name="sample-button">
  <%def name="icon()">✖️</%def>
  <%def name="label()">Cancel</%def>
</%button:basic_button>

<%button:basic_button class_name="sample-button" rounded="${ True }">
  <%def name="icon()">⚡</%def>
  <%def name="label()">Trigger</%def>
</%button:basic_button>

Output

<button class="button button--icon sample-button">
  <span class="button__icon">➖</span>
</button>

<button class="button button--round button--icon sample-button">
  <span class="button__icon">➕</span>
</button>

<button class="button button--basic sample-button">
  <span class="button__icon">✖️</span>
  <span class="button__label">Cancel</span>
</button>

<button class="button button--rounded button--basic sample-button">
  <span class="button__icon">⚡</span>
  <span class="button__label">Trigger</span>
</button>

Installation

Available on PyPI:

pip install mako-for-django

Usage

Minimal configuration in settings.py:

TEMPLATES = [
    {
        "BACKEND": "django_mako.MakoEngine",
        "DIRS": [
            BASE_DIR / "mako",
        ],
        "APP_DIRS": True,
        "OPTIONS": {},
    },
]

Example: Extending OPTIONS

MAKO_LOOKUP_OPTIONS = {
  "cache_enabled": True,
  # https://beaker.readthedocs.io/en/latest/
  "cache_impl": "beaker",
}

MAKO_TEMPLATE_OPTIONS = {
  "encoding_errors": "strict" if DEBUG else "htmlentityreplace",
}

TEMPLATES = [
    {
        "BACKEND": "django_mako.MakoEngine",
        "DIRS": [
            BASE_DIR / "mako",
        ],
        "APP_DIRS": True,
        "OPTIONS": {
            "lookup": {
                **MAKO_LOOKUP_OPTIONS,
            },
            "template": {
                **MAKO_TEMPLATE_OPTIONS,
            },
        },
    },
]

Example: Using Mako alongside DjangoTemplates

SHARED_TEMPLATE_CONTEXT_PROCESSORS = [
    "django.template.context_processors.debug",
    "django.template.context_processors.request",
    "django.contrib.auth.context_processors.auth",
    "django.template.context_processors.tz",
    "django.template.context_processors.i18n",
    "django.contrib.messages.context_processors.messages",
    "django.template.context_processors.static",
    "django.template.context_processors.media",
]

# Context processors to use with Mako backend only.
MAKO_TEMPLATE_CONTEXT_PROCESSORS = [
    "django_mako.template.context_processors.url",
]

TEMPLATES = [
    {
        "BACKEND": "django_mako.MakoEngine",
        "DIRS": [
            BASE_DIR / "mako",
        ],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                *SHARED_TEMPLATE_CONTEXT_PROCESSORS,
                *MAKO_TEMPLATE_CONTEXT_PROCESSORS,
            ],
        },
    },
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            BASE_DIR / "templates",
        ],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                *SHARED_TEMPLATE_CONTEXT_PROCESSORS,
            ],
        },
    },
]

Note

By default, templates within apps should be placed under a mako directory.

Tutorial

This tutorial guides you through creating a minimal Django project using Mako
templates. Follow the steps to set up the project, add an application, create
layout and page templates, and finally render a simple page in the browser.

By the end of this tutorial, the project structure should look like this:

demo/
├── demo/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── index/
│   ├── mako/
│   │   └── index/
│   │       └── views/
│   │           └── index.html.mako
│   ├── migrations/
│   │   └── __init__.py
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── models.py
│   ├── tests.py
│   └── views.py
├── mako/
│   └── layout.html.mako
└── manage.py

Create a new Django project:

django-admin startproject demo
cd demo

Create a new app inside the project:

python manage.py startapp index

Enable the app in settings.py:

INSTALLED_APPS = [
    "index",
]

Configure MakoEngine in settings.py:

TEMPLATES = [
    {
        "BACKEND": "django_mako.MakoEngine",
        "DIRS": [
            BASE_DIR / "mako",
        ],
        "APP_DIRS": True,
        "OPTIONS": {},
    },
]

Add layout template mako/layout.html.mako:

<!DOCTYPE html>
<html>
  <head>
    <title><%block name="title">Demo</%block></title>
  </head>
  <body>
    ${ next.body() }
  </body>
</html>

Create page template index/mako/index/views/index.html.mako:

<%inherit file="/layout.html.mako" />

<%block name="title">${ title } | ${ parent.title() }</%block>

<h1>${ title }</h1>

Add view in index/views.py:

from django.shortcuts import render


def index(request):
    return render(
        request,
        # The template path, relative to `index/mako` directory.
        "/index/views/index.html.mako",
        {
            "title": "Mako for Django",
        },
    )

Wire up urls.py:

from django.urls import path
from index.views import index


urlpatterns = [
    path("", index),
]

Run the server:

python manage.py runserver

After running the server, you can visit
http://127.0.0.1:8000/.

Checkout the e2e directory for more examples.

git clone https://github.com/ertgl/mako-for-django.git
cd mako-for-django/e2e
make
python manage.py runserver

References

Name

Published on PyPI as mako-for-django. The import name django_mako is chosen
for brevity.

License

This project is licensed under the
MIT License.
See the LICENSE file for details.

ertgl/mako-for-django

Mako for Django

Table of Contents

Overview

Motivation

Demonstration

Installation

Usage

Tutorial

References

Name

License

On this page

Languages

Contributors

Latest Release