# Jingo

Jingo is an adapter for using Jinja2 templates within Django.

Note

Coffin or Jingo?

Jingo differs from Coffin in two major ways:

- Jingo serves purely as a minimalistic bridge between Django and Jinja2. Coffin attempts to reduce the differences between Jinja2 templates and Django’s native templates.
- Jingo has a far superior name, as it is a portmanteau of ‘Jinja’ and Django.

## Usage

When configured properly (see Settings below) you can render Jinja2 templates in your view the same way you’d render Django templates:

    from django.shortcuts import render

    def my_view(request):
        context = dict(user_ids=(1, 2, 3, 4))
        return render(request, 'users/search.html', context)

Note

Not only does `django.shortcuts.render` work, but so does any method that Django provides to render templates from files.

If you’re using Django’s low-level `Template` class with a literal string, e.g.:

    from django.templates import Template

    t = Template('template string')

then you’ll need to change that code slightly, to:

    from jingo import get_env

    t = get_env().from_string('template_string')

and then the template will be rendered with all the same features that Jingo provides when rendering template files.

## Settings

You’ll want to use Django to use jingo’s template loader. In `settings.py`:

    TEMPLATE_LOADERS = (
        'jingo.Loader',
        'django.template.loaders.filesystem.Loader',
        'django.template.loaders.app_directories.Loader',
    )

This will let you use `django.shortcuts.render` or `django.shortcuts.render_to_response`.

You can optionally specify which filename patterns to consider Jinja2 templates:

    JINGO_INCLUDE_PATTERN = r'\.jinja2'  # use any regular expression here

This will consider every template file that contains the substring .jinja2 to be a Jinja2 file (unless it’s in a module explicitly excluded, see below).

And finally you may have apps that do not use Jinja2, these must be excluded from the loader:

    JINGO_EXCLUDE_APPS = ('debug_toolbar',)

If a template path begins with `debug_toolbar`, the Jinja loader will raise a `TemplateDoesNotExist` exception. This causes Django to move onto the next loader in `TEMPLATE_LOADERS` to find a template - in this case, `django.template.loaders.filesystem.Loader`.

Note

Technically, we’re looking at the template path, not the app. Often these are the same, but in some cases, like ‘registration’ in the default setting–which is an admin template–they are not.

The default is in `jingo.EXCLUDE_APPS`:

    EXCLUDE_APPS = (
        'admin',
        'admindocs',
        'registration',
        'context_processors',
    )

Changed in version 0.6.2: Added `context_processors` application.

If you want to configure the Jinja environment, use `JINJA_CONFIG` in `settings.py`. It can be a dict or a function that returns a dict.

    JINJA_CONFIG = {'autoescape': False}

or

    def JINJA_CONFIG():
        return {'the_answer': 41 + 1}

## Template Helpers

Instead of template tags, Jinja encourages you to add functions and filters to the templating environment. In `jingo`, we call these helpers. When the Jinja environment is initialized, `jingo` will try to open a `helpers.py` file from every app in `INSTALLED_APPS`. Two decorators are provided to ease the environment extension:

`jingo.register.``filter`()

  Adds the decorated function to Jinja’s filter library.

`jingo.register.``function`()

  Adds the decorated function to Jinja’s global namespace.

### Default Helpers

Helpers are available in all templates automatically, without any extra loading.

## Template Environment

A single Jinja `Environment` is created for use in all templates. This is available as `jingo.env` if you need to work with the `Environment`.

## Localization

Since we all love L10n, let’s see what it looks like in Jinja templates:

    <h2>{{ _('Reviews for {0}')|f(addon.name) }}</h2>

The simple way is to use the familiar underscore and string within a `{{ }}` moustache block. `f` is an interpolation filter documented below. Sphinx could create a link if I knew how to do that.

The other method uses Jinja’s `trans` tag:

    {% trans user=review.user|user_link, date=review.created|datetime %}
      by {{ user }} on {{ date }}
    {% endtrans %}

`trans` is nice when you have a lot of text or want to inject some variables directly. Both methods are useful, pick the one that makes you happy.

## Forms

Django marks its form HTML “safe” according to its own rules, which Jinja2 does not recognize.

Django marks its form HTML “safe” according to its own rules, which Jinja2 does not recognize.

This monkeypatches Django to support the `__html__` protocol used in Jinja2 templates. `Form`, `BoundField`, `ErrorList`, and other form objects that render HTML through their `__unicode__` method are extended with `__html__` so they can be rendered in Jinja2 templates without adding `|safe`.

Call the `patch()` function to execute the patch. It must be called before `django.forms` is imported for the conditional_escape patch to work properly. The root URLconf is the recommended location for calling `patch()`.

Usage:

    import jingo.monkey
    jingo.monkey.patch()

This patch was originally developed by Jeff Balogh and this version is taken from the nuggets project at https://github.com/mozilla/nuggets/blob/master/safe_django_forms.py

## Testing

To run the test suite, you need to define `DJANGO_SETTINGS_MODULE` first:

    $ export DJANGO_SETTINGS_MODULE="fake_settings"
    $ nosetests

or simply run:

    $ python run_tests.py

To test on all supported versions of Python and Django:

    $ pip install tox
    $ tox