Skip to main content

An adapter for using Jinja2 templates with Django.

Project description

.. _jingo:
.. module:: jingo

=====
Jingo
=====

.. note:: This document may be out of date. The up-to-date documentation can
be found on `Read the Docs <https://jingo.readthedocs.org/en/latest/>`_.


Jingo is an adapter for using Jinja2_ templates within Django.


NB: Django 1.8 and django-jinja
-------------------------------

In version 1.8, Django added support for multiple template engines, and
the django-jinja_ project leverages that to support Jinja2_, while Jingo
does not.

**django-jinja is recommended for new projects.** Jingo supports Django
1.8, but it is not clear that its method will continue work beyond that.
If you're already using Jingo, and not ready to make `the switch`_,
Jingo will continue to work for now, but is undecided about continuing
to support new Django versions.

.. _django-jinja: https://github.com/niwinz/django-jinja
.. _the switch: http://bluesock.org/~willkg/blog/mozilla/input_django_1_8_upgrade.html#switching-from-jingo-to-django-jinja
.. _Jinja2: http://jinja.pocoo.org/2/


.. _usage:

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.shorcuts.render`` work, but so does any method that
Django provides to render templates.

.. _settings:

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',
)

.. versionchanged:: 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:

.. function:: jingo.register.filter

Adds the decorated function to Jinja's filter library.

.. function:: jingo.register.function

Adds the decorated function to Jinja's global namespace.


.. highlight:: jinja

Default Helpers
~~~~~~~~~~~~~~~

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

.. automodule:: jingo.helpers
:members:


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.

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()


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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jingo-0.8.1.tar.gz (9.9 kB view details)

Uploaded Source

Built Distribution

jingo-0.8.1-py2.py3-none-any.whl (12.7 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file jingo-0.8.1.tar.gz.

File metadata

  • Download URL: jingo-0.8.1.tar.gz
  • Upload date:
  • Size: 9.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for jingo-0.8.1.tar.gz
Algorithm Hash digest
SHA256 9757e570834d65ae9f3363d96439b6bf9845e0100ea3c4a01f52fddf3dcaf3bd
MD5 259b410d102c4b5935a0e578e04bd005
BLAKE2b-256 69e8e2115c5ea652a97d3b52af7c8e3bec5290f3a9136d4f5219766dcd7dc427

See more details on using hashes here.

Provenance

File details

Details for the file jingo-0.8.1-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for jingo-0.8.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 719ca165ce8becaf8d16b1596e863a380474c30ce5d239c6f0c1243f73f0fa20
MD5 ceaa180583edda805a9acaaf3a6b675a
BLAKE2b-256 3a903385242a04477424fc087411e1f74ac11c7d7904f5a3db6e817b52fe8347

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page