Unobtrusive jinja2 integration in Django
pip install djinga==2.1.2
© 2014-2017 Thomas Khyn
Unobtrusive jinja2 integration in Django
Tested with Django 1.8, 1.11 and 2.0 and the latest minor versions of Python 2 and 3 (Django 2.0 only supports Python 3).
If you like djinga
and are looking for a way to thank me and/or encourage
future development, here is my BTC or BCH donation address:
1EwENyR8RV6tMc1hsLTkPURtn5wJgaBfG9
.
Simply because no other jinja2 integration app for django met the requirements of a perfectionist django developer.
Djinga enables you to:
makemessages
management commandInstall djinga using the method of your choice
Add 'djinga' to your INSTALLED_APPS
Set the TEMPLATE
setting as:
TEMPLATES = [ { 'BACKEND': 'djinga.backends.djinga.DjingaTemplates', 'DIRS': ['your/first/template/directory', 'your/second/template/directory'], 'OPTIONS': { ... }, }, ]
Add the relevant options for jinja2 and djinga
By default, a template will be rendered using Django's built-in template engine if it has a .html, .htm, .djhtml or .djhtm file extension. If it has a .jjhtml or .jjhtm file extension, it will be rendered by Jinja2, using the setting values provided in django's setting module.
Simply add the following options to the 'OPTIONS'
section of the
TEMPLATES
item matching the djinga backend:
TEMPLATES = [ { 'BACKEND': 'djinga.backends.djinga.DjingaTemplates', 'OPTIONS': { 'option1': 'value1', 'option2': {'key1': 'val1', 'key2': 'val2'}, ... }, }, ]
A list or tuple of file extensions (with or without the leading dot) for templates that should be rendered with Django's internal template engine.
Defaults to ('html', 'htm', 'jjhtml', 'jjhtm')
A list or tuple of the file extensions (with or without the leading dot) for templates that should be rendered with Jinja2.
Defaults to ('jjhtml', 'jjhtm')
djinga.ext.*
.globals
and
filters
options. See Adding globals and filters for details.Djinga comes with several Jinja2 extensions:
{% static 'path' %}
tag to refer to Django's staticfiles
directory{% css 'rel/path/to/file.css' %}
tag that generates a
HTML link element refering to the css file located at a relative path in
a css directory. The css directory's path can be defined relatively to
Django's staticfiles directory through the setting JINJA2_STATIC_CSS{% django %}{% enddjango %}
tag to include django template
language in a jinja2 template. For this tag to work, the
django.core.context_processors.request
context processor must be
enabled.{% csrf_token %}
tag.The following tags are automatically made available in any django template:
{% extends %}
tag and enables it to refer to
jinja2 files as well as normal django template files. While the template
engine for the current file remains Django's one, the template engine for
the extended file can be either Jinja2 or Django, depending on the file
extension (in dj_exts
or jj_exts
)A straightforward way to add globals and filters and make them available from
your Jinja2 templates is to add them to the globals
or the filters
options in the settings module.
However, this is not always convenient nor possible (import loops), and djinga
therefore provides a way to ease this process, through the jj_global
and
jj_filter
decorators in combination with the load_from
option.
Basically, the decorators mark the functions as Jinja2 globals or filters, while the setting (a list of module paths) indicates djinga where to look for them.
A short example is better than long explanations, so here we go.
This:
[my_app/my_module.py] from djinga.register import jj_filter, jj_global @jj_global def my_tag(*args, **kw): pass @jj_filter def my_filter(*args, **kw) pass [settings.py] # django 1.8+ TEMPLATES = [ { 'BACKEND': 'djinga.backends.djinga.DjingaTemplates', 'OPTIONS': { 'load_from': ('my_app.my_module',), }, }, ] [settings.py] # django < 1.8 JINJA2_LOAD_FROM = ( 'my_app.my_module', )
is equivalent to this:
[my_app/my_module.py] def my_tag(*args): pass def my_filter(*args, **kw) pass [settings.py] # django 1.8+ from my_app.my_module import my_tag, my_filter TEMPLATES = [ { 'BACKEND': 'djinga.backends.djinga.DjingaTemplates', 'OPTIONS': { 'globals': {'my_tag': my_tag}, 'filters': {'my_filter': my_filter}, }, }, ] [settings.py] # django < 1.8 from my_app.my_module import my_tag, my_filter JINJA2_GLOBALS = {'my_tag': my_tag} JINJA2_FILTERS = {'my_filter': my_filter}
...with the significant advantage of not requiring a possibly issue-prone
import
statement in the settings
module.
The jj_global
and jj_filter
decorators are compatible with any of the
Jinja2 built-in decorators. They do not affect the behavior nor the
signature of the decorated function, so you can use it normally (as a normal
Django template tag or filter, for example).
The collected globals and filters are appended to the ones already specified
in globals
and filters
.
makemesssages
management commandAdapted from coffin.
Djinga overrides the Django makemessages
core management command to include
the specific Jinja2 translation tags and ensure the strings marked for
translation in Jinja2 templates appear in the translations dictionary.