Template tags¶
Initialization¶
You can either:
- load the template tag lib into each template manually:
{% load js %}
- load the template tag lib by adding to your
views.py
:
from django.template import add_to_builtins
add_to_builtins('djangojs.templatetags.js')
If you want to use boolean parameters, Django.js provide the djangojs.context_processors.booleans
to help. Simply add it to your settings.CONTEXT_PROCESSORS
.
If not, you should use the string versions: param="True"
.
If settings.DEBUG=True
, unminified versions are loaded (only for provided libraries,
aka. Django.js, jQuery and jQuery Migrate).
Usage¶
django_js¶
A {% django_js %}
tag is available to provide the Django JS module.
After loading, you can use the Django module to resolve URLs and Translations:
{% django_js %}
<script>
console.log(
Django.url('my-view', {key: 'test'}),
Django.file('test.json'),
Django.context.STATIC_URL
);
</script>
It supports the following keyword parameters (in this order if you want to omit the keyword):
Parameter | Default | Description |
---|---|---|
jquery |
true |
Load the jQuery library |
i18n |
true |
Load the javascript i18n catalog |
csrf |
true |
Patch jQuery.ajax() for Django CSRF |
init |
true |
Initialize Django.js on load |
You can disable all this features by simply providing arguments to the template tag:
{% django_js jquery=false i18n=false csrf=false %}
django_js_init¶
The {% django_js_init %}
provide the necessary bootstrap for the Django.js without loading it.
It allows you to use Django.js with an AMD loader or a javascript compressor.
It supports the following keyword parameters (in this order if you want to omit the keyword):
Parameter | Default | Description |
---|---|---|
jquery |
false |
Load the jQuery library |
i18n |
true |
Load the javascript i18n catalog |
csrf |
true |
Patch jQuery.ajax() fot Django CSRF |
init |
true |
Initialize Django.js on load |
You can disable all this features by simply providing arguments to the template tag:
{% django_js_init jquery=true i18n=false csrf=false %}
If you want to use it with require.js or Django Pipeline, see RequireJS integration or Django Pipeline.
Internationalization¶
When the {% django_js %}
template tag is included in a page, it automatically:
loads the django javascript catalog for all supported apps
- loads the django javascript i18n/l10n tools in the page:
gettext()
ngettext()
interpolate()
You can disable this feature by setting the i18n
keyword parameter to false
.
Note
You can filter included apps by using either the settings whitelist settings.JS_I18N
or the settings blacklist settings.JS_I18N_EXCLUDE
or both.
For more informations, see Settings.
jQuery Ajax CSRF¶
When the django_js
template tag is ininitialized it automatically patch jQuery.ajax()
to handle CSRF tokens on ajax request.
You can disable this feature by setting the csrf
keyword parameter to false
.
You can manually enable it later with:
Django.jquery_csrf();
verbatim¶
A {% verbatim %}
tag is available to ease the JS templating.
It escape a specific part. For example, you may want a subpart of your template to be rendered by Django :
<script type="text/x-handlebars" id="tpl-django-form">
<form>
{% verbatim %}
{{#if id}}<h1>{{ id }}</h1>{{/if}}
{% endverbatim %}
{{ yourform.as_p }}
</form>
</script>
Note
Starting from Django 1.5, use the included verbatim tag .
jquery_js¶
The {% jquery_js %}
tag only load the jQuery library.
You can override the version either by passing the version as a parameter or setting the version with the settings.JQUERY_VERSION
property.
For more informations, see Settings.
You can optionnaly load the jQuery Migrate plugins for legacy support with jQuery 1.9.0+.
{% jquery_js %}
{% jquery_js "1.8.3" %}
{% jquery_js migrate=true %}
The django_js
tag automatically load jQuery so no need to manually load it unless you set jquery=false
.
javascript/js¶
The javascript
and js
tags are the same quick helper to include javascript files from {{STATIC_URL}}
:
{% javascript "js/my.js" %}
{% js "js/my.js" %}
is equivalent to:
<script type="text/javascript" src="{% static "js/my.js" %}"></script>
Both tags take an options type
parameter that specifies the content type of the <script>
tag:
{% javascript "js/my.custom" type="text/custom" %}
yields:
<script type="text/custom" src="{% static "js/my.custom" %}"></script>
coffescript/coffee¶
The coffeescript
and coffee
tags are the same quick helper to include coffeescript files from {{STATIC_URL}}
:
{% coffeescript "js/my.coffee" %}
{% coffee "js/my.coffee" %}
is equivalent to:
<script type="text/coffeescript" src="{% static "js/my.coffee" %}"></script>
css¶
The css
tag is a quick helper to include css files from {{STATIC_URL}}
:
{% css "css/my.css" %}
is equivalent to:
<link rel="stylesheet" type="text/css" href="{% static "css/my.css" %}" />
js_lib¶
The js_lib
tag is a quick helper to include javascript files from {{STATIC_URL}}js/libs
:
{% js_lib "my-lib.js" %}
is equivalent to:
<script type="text/javascript" src="{{STATIC_URL}}js/libs/my-lib.js"></script>