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 %}
<script>
    console.log(
        Django.url('my-view', {key: 'test'}),
        Django.file('test.json'),
        Django.context.STATIC_URL
    );
</script>

{% django_js jquery=false i18n=false csrf=false %}

{% django_js_init jquery=true i18n=false csrf=false %}

Django.jquery_csrf();

<script type="text/x-handlebars" id="tpl-django-form">
    <form>
        {% verbatim %}
            {{#if id}}<h1>{{ id }}</h1>{{/if}}
        {% endverbatim %}
        {{ yourform.as_p }}
    </form>
</script>

{% jquery_js %}
{% jquery_js "1.8.3" %}
{% jquery_js migrate=true %}

{% javascript "js/my.js" %}
{% js "js/my.js" %}

<script type="text/javascript" src="{% static "js/my.js" %}"></script>

{% javascript "js/my.custom" type="text/custom" %}

<script type="text/custom" src="{% static "js/my.custom" %}"></script>

{% coffeescript "js/my.coffee" %}
{% coffee "js/my.coffee" %}

<script type="text/coffeescript" src="{% static "js/my.coffee" %}"></script>

{% css "css/my.css" %}

<link rel="stylesheet" type="text/css" href="{% static "css/my.css" %}" />

{% js_lib "my-lib.js" %}

<script type="text/javascript" src="{{STATIC_URL}}js/libs/my-lib.js"></script>

Reverse URLs¶

The Django.js library expose reverse urls to javascript. You can call the Django.url() method with:

• an url name without arguments

Django.url('my-view');

• an url name and a variable number of arguments

Django.url('my-view', arg1, arg2);

• an url name and an array of arguments

Django.url('my-view' [arg1, arg2]);

• an url name and an object with named arguments

Django.url('my-view', {arg1: 'value1', arg2: 'value2'});

• an url name with one or more namespaces

Django.url('ns:my-view');
Django.url('ns:nested:my-view');

You can use anonymous forms (variable arguments and array) with named arguments in urls but you can’t use object form with anonymous arguments.

You can also force unnamed URLs serialization with settings.JS_URLS_UNNAMED:

Django.url('path.to.my.view');

Static URLs¶

You can obtain a static file url with the static or file methods:

Django.static('my-data.json');
Django.file('my-data.json');
Django.static('another/data.pdf');
Django.file('another/data.pdf');

Context¶

Django.js wraps some Django values normally accessible in the template context:

• Django.context.STATIC_URL
• Django.context.MEDIA_URL
• Django.context.LANGUAGES
• Django.context.LANGUAGE_CODE
• Django.context.LANGUAGE_NAME
• Django.context.LANGUAGE_NAME_LOCAL
• Django.context.LANGUAGE_BIDI

In fact, any value contributed by a context processor and serializable will be accessible from Django.context.

User and permissions¶

Django.js allows you to check basic user attributes and permissions from client side. You can simply access the Django.user object or call the Django.user.has_perm() method:

console.log(Django.user.username);

if (Django.user.is_authenticated) {
    do_something();
}

if (Django.user.is_staff) {
    go_to_admin();
}

if (Django.user.is_superuser) {
    do_a_superuser_thing();
}

if (Django.user.has_perm('myapp.do_something')) {
    do_something();
}

CSRF Tokens¶

Django.js provides some helpers for CSRF protection.

• return the value of the CSRF token

Django.csrf_token();

• return the hidden input element containing the CSRF token, like the {% csrf_token %} template tag

Django.csrf_element();

Preloading prerequisites¶

You should use the django_js_init template tag before loading your application with RequireJS.

{% load js %}
{% django_js_init %}
<script data-main="scripts/main" src="scripts/require.js"></script>

It works with django-require too:

{% load js require %}
{% django_js_init %}
{% require_module 'main' %}

See django_js_init.

shim configuration¶

You should add an extra shim configuration for Django.js:

require.config({
    paths: {
        django: 'djangojs/django'
    },

    shim: {
        "django": {
            "deps": ["jquery"],
            "exports": "Django"
        }
    }
});

Views¶

Django.js provides base views for javascript testing. Instead of writing a full view each time you need a Jasmine or a QUnit test view, simply use the provided JasmineView and QUnitView and add them to your test_urls.py:

from django.conf.urls import patterns, url, include

from djangojs.views import JasmineView, QUnitView

urlpatterns = patterns('',
    url(r'^jasmine$', JasmineView.as_view(js_files='js/specs/*.specs.js'), name='my_jasmine_view'),
    url(r'^qunit$', QUnitView.as_view(js_files='js/tests/*.tests.js'), name='my_qunit_view'),
)

Both view have a js_files attribute which can be a string or and array of strings. Each string can be a static js file path to include or a glob pattern:

from djangojs.views import JasmineView

class MyJasmineView(JasmineView):
    js_files = (
        'js/lib/my-lib.js',
        'js/test/*.specs.js',
        'js/other/specs.*.js',
    )

jQuery can automatically be included into the view by setting the jquery attribute to True:

from djangojs.views import JasmineView

class MyJasmineView(JasmineView):
    jquery = True
    js_files = 'js/test/*.specs.js'

Django.js can automatically be included into the view by setting the django_js attribute to True:

from djangojs.views import JasmineView

class MyJasmineView(JasmineView):
    django_js = True
    js_files = 'js/test/*.specs.js'

These views extends the Django TemplateView so you can add extra context entries and you can customize the template by extending them.

from djangojs.views import QUnitView

class MyQUnitView(QUnitView):
    js_files = 'js/test/*.test.js'
    template_name = 'my-qunit-runner.html'

    def get_context_data(self, **kwargs):
        context = super(MyQUnitView, self).get_context_data(**kwargs)
        context['form'] = TestForm()
        return context

Two extensible test runner templates are provided:

• djangojs/jasmine-runner.html for jasmine tests
• djangojs/qunit-runner.html for QUnit tests

Both provides a js_init block, a js_content block and a body_content block.

{% extends "djangojs/qunit-runner.html" %}

{% block js_init %}
    {{ block.super }}
    {% js "js/init.js" %}
{% endblock %}

{% block js_content %}
    {% load js %}
    {% js "js/tests/my.tests.js" %}
{% endblock %}

{% block body_content %}
  <form id="test-form" action="{% url test_form %}" method="POST" style="display: none;">
    {{csrf_token}}
    {{form}}
  </form>
{% endblock %}

You can inspect django.js own test suites on github.

If you just need the Django.js comptible runners, you can include the following templates (depending on your framework):

• QUnit:

  • djangojs/qunit-runner-head.html
  • djangojs/qunit-runner-body.html

• Jasmine:

  • djangojs/jasmine-runner-head.html
  • djangojs/jasmine-runner-body.html

Test cases¶

A Phantom.js test runner parsing TAP is provided in 3 flavours:

• JsTestCase that runs javascript tests against Django liveserver TestCase.
• JsFileTestCase that runs javascript tests against a static html file
• JsTemplateTestCase that runs javascript tests against a rendered html file (but without liveserver running)

Jasmine/QUnit support are provided with JasmineSuite and QUnitSuite mixins.

To use it with the previously defined views, just define either url_name or filename attribute:

from djangojs.runners import JsTestCase, JsFileTestCase, JsTemplateTestCase
from djangojs.runners import JasmineSuite, QUnitSuite


class JasminTests(JasmineSuite, JsTestCase):
    urls = 'myapp.test_urls'
    title = 'My Jasmine suite'
    url_name = 'my_url_name'


class QUnitTests(QunitSuite, JsFileTestCase):
    filename = '/tmp/my-runner.html'


class JasminTests(JasmineSuite, JsTemplateTestCase):
    template_name = 'my/template.html'
    js_files = 'js/test/other/*.js'

The verbosity is automatically adjusted with the -v/--verbosity parameter from the manage.py test command line.

Django Absolute¶

Django Absolute contribute with the following context variables:

• ABSOLUTE_ROOT
• ABSOLUTE_ROOT_URL
• SITE_ROOT
• SITE_ROOT_URL

They will be available into Django.context javascript object (nothing new, this the default behavior). But, two more methods will be available:

• Django.absolute() to reverse an absolute URL based on request
• Django.site() to reverse an absolute URL based on Django site

If you try to call these methods without django-bsolute installed, a DjangoJsError will be thrown.

Django Pipeline¶

If you want to compress Django.js with Django Pipeline, you should change the way you load django.js.

First add jQuery and Django.js to your pipelines in you settings.py:

PIPELINE_JS = {
    'base': {
        'source_filenames': (
            '...',
            'js/libs/jquery-1.9.1.js',
            'js/djangojs/django.js',
            '...',
        ),
        'output_filename': 'js/base.min.js',
    },
}

Instead of using the django_js template tag:

{% load js %}
{% django_js %}

you should use the django_js_init and include your compressed bundle:

{% load js compressed %}
{% django_js_init %}
{% compressed_js "base" %}

JQUERY_VERSION¶

Specify the jQuery version to use. If not specififed, default to last version.

Django.js provide the following versions:

• 1.8.3
• 1.9.0
• 1.9.1
• 1.10.1
• 2.0.0
• 2.0.1
• 2.0.2

JS_URLS¶

Serialized URLs names whitelist. If this setting is specified, only named URLs listed in will be serialized.

• Default value: None
• Expected: a list of URLs names to include only

JS_URLS_EXCLUDE¶

Serialized URLs names blacklist. It this setting is specified, named URLs listed in will not be serialized.

• Default value: None
• Expected: a list of URLs names to exclude

JS_URLS_NAMESPACES¶

Serialized namespaces whitelist. If this setting is specified, only URLs from namespaces listed in will be serialized.

• Default value: None
• Expected: a list of URL namespaces to include only

JS_URLS_NAMESPACES_EXCLUDE¶

Serialized namespaces blacklist. It this setting is specified, URLs from namespaces listed in will not be serialized.

• Default value: None
• Expected: a list of URL namespaces to exclude

JS_URLS_UNNAMED¶

Serialize unnamed URLs. If this setting is set to True, unnamed URLs will be serialized (only for function based views).

• Default value: False

JS_I18N_APPS¶

Serialized translations whitelist. If specified, only apps listed in will appear in the javascript translation catalog.

• Default value: None
• Expected: a restricted application list to include in the javascript translation catalog

JS_I18N_APPS_EXCLUDE¶

Serialized translations blacklist. If specified, apps listed in will not appear in the javascript translation catalog.

• Default value: None
• Expected: an application list to exclude from the javascript translation catalog

Usage exemple¶

You could have, in your settings.py:

# Exclude my secrets pages from serialized URLs
JS_URLS_EXCLUDE = (
    'my_secret_page',
    'another_secret_page',
)
# Only include admin namespace
JS_URLS_NAMESPACES = (
    'admin',
)
# Only include my apps' translations
JS_I18N_APPS = ('myapp', 'myapp.other')

djangojs – Main package¶

Django.js provide better integration of javascript into Django.

djangojs.JQUERY_DEFAULT_VERSION = '2.0.2'¶

Packaged jQuery version

djangojs.views – Javascript views helpers¶

This module provide helper views for javascript.

class djangojs.views.JsInitView(**kwargs)[source]¶

Bases: django.views.generic.base.TemplateView

Render a javascript file containing the URLs mapping and the context as JSON.

class djangojs.views.JsonView(**kwargs)[source]¶

Bases: django.views.generic.base.View

A views that render JSON.

class djangojs.views.UrlsJsonView(**kwargs)[source]¶

Bases: djangojs.views.JsonView

Render the URLs as a JSON object.

class djangojs.views.ContextJsonView(**kwargs)[source]¶

Bases: djangojs.views.JsonView

Render the context as a JSON object.

class djangojs.views.JsTestView(**kwargs)[source]¶

Bases: django.views.generic.base.TemplateView

Base class for JS tests views

django_js = False¶

Includes or not Django.js in the test view

jquery = False¶

Includes or not jQuery in the test view.

js_files = None¶

A path or a list of path to javascript files to include into the view.

• Supports glob patterns.
• Order is kept for rendering.

class djangojs.views.JasmineView(**kwargs)[source]¶

Bases: djangojs.views.JsTestView

Render a Jasmine test runner.

class djangojs.views.QUnitView(**kwargs)[source]¶

Bases: djangojs.views.JsTestView

Render a QUnit test runner

theme = u'qunit'¶

QUnit runner theme.

Should be one of: qunit, gabe, ninja, nv

djangojs.runners – Javascript unittest runners¶

This module provide Javascript test runners for Django unittest.

class djangojs.runners.JsTestCase(methodName='runTest')[source]¶

Bases: djangojs.runners.PhantomJsRunner, django.test.testcases.LiveServerTestCase

A PhantomJS suite that run against the Django LiveServerTestCase

url_args = None¶

an optionnal arguments array to pass to the reverse() function

url_kwargs = None¶

an optionnal keyword arguments dictionnary to pass to the reverse() function

url_name = None¶

a mandatory named URL that point to the test runner page

class djangojs.runners.JsFileTestCase(methodName='runTest')[source]¶

Bases: djangojs.runners.PhantomJsRunner, unittest.case.TestCase

A PhantomJS suite that run against a local html file

filename = None¶

absolute path to the test runner page

class djangojs.runners.JsTemplateTestCase(methodName='runTest')[source]¶

Bases: djangojs.runners.JsFileTestCase

A PhantomJS suite that run against a rendered html file but without server.

Note

Template is rendered using a modified static storage that give file:// scheme URLs. To benefits from it, you have to use either the static template tag or one the djangojs template tags.

Warning

Template is not rendered within a request/response dialog. You can’t access the request object and everything that depends on the server.

jquery = False¶

Includes or not jQuery in the test view. Template has to handle the use_jquery property.

js_files = None¶

A path or a list of path to javascript files to include into the view.

• Supports glob patterns.
• Order is kept for rendering.

template_name = None¶

absolute path to the test runner page

exception djangojs.runners.JsTestException(message, failures=None)[source]¶

Bases: exceptions.Exception

An exception raised by Javascript tests.

It display javascript errors into the exception message.

class djangojs.runners.JasmineSuite[source]¶

Bases: object

A mixin that runs a jasmine test suite with PhantomJs.

class djangojs.runners.QUnitSuite[source]¶

Bases: object

A mixin that runs a QUnit test suite with PhantomJs.

class djangojs.runners.AbsoluteFileStorage(location=None, base_url=None)[source]¶

Bases: django.core.files.storage.FileSystemStorage

A storage that give the absolute file scheme URL as URL.

djangojs.utils – Miscellaneous helpers¶

This modules holds every helpers that does not fit in any standard django modules.

It might be splitted in futur releases.

djangojs.utils.urls_as_dict()[source]¶

Get the URLs mapping as a dictionnary

djangojs.utils.urls_as_json()[source]¶

Get the URLs mapping as JSON

class djangojs.utils.ContextSerializer[source]¶

Bases: object

Serialize the context from requests.

classmethod as_dict(request)[source]¶

Serialize the context as a dictionnary from a given request.

classmethod as_json(request)[source]¶

Serialize the context as JSON from a given request.

classmethod handle_user(data, request)[source]¶

Insert user informations in data

class djangojs.utils.StorageGlobber[source]¶

Bases: object

Retrieve file list from static file storages.

classmethod glob(files=None)[source]¶

Glob a pattern or a list of pattern static storage relative(s).

djangojs.tap – Tap format parser¶

This module provide test runners for JS in Django.

class djangojs.tap.TapParser(yield_class=<class 'djangojs.tap.TapTest'>, debug=False)[source]¶

Bases: object

A TAP parser class reading from iterable TAP lines.

djangojs.templatetags.js – Javascript template tags¶

Provide template tags to help with Javascript/Django integration.

class djangojs.templatetags.js.VerbatimNode(text_and_nodes)[source]¶

Bases: django.template.base.Node

Wrap {% verbatim %} and {% endverbatim %} around a block of javascript template and this will try its best to output the contents with no changes.

{% verbatim %}
    {% trans "Your name is" %} {{first}} {{last}}
{% endverbatim %}

djangojs.templatetags.js.coffee(filename)[source]¶

A simple shortcut to render a script tag to a static coffeescript file

djangojs.templatetags.js.coffeescript(filename)[source]¶

A simple shortcut to render a script tag to a static coffeescript file

djangojs.templatetags.js.css(filename)[source]¶

A simple shortcut to render a link tag to a static CSS file

djangojs.templatetags.js.django_js(context, jquery=True, i18n=True, csrf=True)[source]¶

Include Django.js javascript library in the page

djangojs.templatetags.js.django_js_init(context, jquery=False, i18n=True, csrf=True)[source]¶

Include Django.js javascript library initialization in the page

djangojs.templatetags.js.javascript(filename, type=u'text/javascript')[source]¶

A simple shortcut to render a script tag to a static javascript file

djangojs.templatetags.js.jquery_js(version=None, migrate=False)[source]¶

A shortcut to render a script tag for the packaged jQuery

djangojs.templatetags.js.js(filename, type=u'text/javascript')[source]¶

A simple shortcut to render a script tag to a static javascript file

djangojs.templatetags.js.verbatim(parser, token)[source]¶

Renders verbatim tags

djangojs.templatetags.js.verbatim_tags(parser, token, endtagname)[source]¶

Javascript templates (jquery, handlebars.js, mustache.js) use constructs like:

{{if condition}} print something{{/if}}

This, of course, completely screws up Django templates, because Django thinks {{ and }} means something.

The following code preserves {{ }} tokens.

This version of verbatim template tag allows you to use tags like url {% url name %}. {% trans “foo” %} or {% csrf_token %} within.

Inspired by:

• Miguel Araujo: https://gist.github.com/893408

djangojs.context_processors – Context processors¶

djangojs.context_processors.booleans(request)[source]¶

Allow to use booleans in templates.

See: http://stackoverflow.com/questions/4557114/django-custom-template-tag-which-accepts-a-boolean-parameter

0.7.5 (2013-06-01)¶

• Handle Django 1.5+ custom user model
• Upgraded to jQuery 2.0.2 and jQuery Migrate 1.2.1

0.7.4 (2013-05-11)¶

• Preserve declaration order in StorageGlobber.glob() (Fix issue #17)
• Fixes on localization on handling

0.7.3 (2013-04-30)¶

• Upgraded to jQuery 2.0.0
• Package both minified and unminified versions.
• Load minified versions (Django.js, jQuery and jQuery Migrate) when DEBUG=False

0.7.2 (2013-04-30)¶

• Fix issue #16
• Declare package as Python 3 compatible on PyPI

0.7.1 (2013-04-25)¶

• Optionnaly include jQuery with {% django_js_init %}.

0.7.0 (2013-04-25)¶

• Added RequireJS/AMD helpers and documentation
• Added Django Pipeline integration helpers and documentation
• Support unnamed URLs resolution.
• Support custom content types to be passed into the js/javascript script tag (thanks to Travis Jensen)
• Added coffee and coffescript template tags
• Python 3 compatibility

0.6.5 (2013-03-13)¶

• Make JsonView reusable
• Unescape regex characters in URLs
• Fix handling of 0 as parameter for Javasript reverse URLs

0.6.4 (2013-03-10)¶

• Support namespaces without app_name set.

0.6.3 (2013-03-08)¶

• Fix CSRF misspelling (thanks to Andy Freeland)
• Added some client side CSRF helpers (thanks to Andy Freeland)
• Upgrade to jQuery 1.9.1 and jQuery Migrate 1.1.1
• Do not clutter url parameters in js, javascript and js_lib template tags.

0.6.2 (2013-02-18)¶

• Compatible with Django 1.5

0.6.1 (2013-02-11)¶

• Added static method (even if it’s a unused reserved keyword)

0.6 (2013-02-09)¶

• Added basic user attributes access
• Added permissions support
• Added booleans context processor
• Added jQuery 1.9.0 and jQuery Migrate 1.0.0
• Upgraded QUnit to 1.11.0
• Added QUnit theme support
• Allow to specify jQuery version (1.8.3 and 1.9.0 are bundled)

0.5 (2012-12-17)¶

• Added namespaced URLs support

• Upgraded to Jasmine 1.3.1

• Refactor testing tools:

  • Rename test/js into js/test and reorganize test resources
  • Renamed runner_url* into url* on JsTestCase
  • Handle url_args and url_kwargs on JsTestCase
  • Renamed JasmineMixin into JasmineSuite
  • Renamed QUnitMixin into QUnitSuite
  • Extracted runners initialization into includable templates

• Added JsFileTestCase to run tests from a static html file without live server

• Added JsTemplateTestCase to run tests from a rendered template file without live server

• Added some settings to filter scope:

  • Serialized named URLs whitelist: settings.JS_URLS
  • Serialized named URLs blacklist: settings.JS_URLS_EXCLUDE
  • Serialized namespaces whitelist: settings.JS_URLS_NAMESPACES
  • Serialized namespaces blacklist: settings.JS_URLS_NAMESPACES_EXCLUDE
  • Serialized translations whitelist: settings.JS_I18N_APPS
  • Serialized translations blacklist: settings.JS_I18N_APPS_EXCLUDE

• Expose PhantomJS timeout with PhantomJsRunner.timeout attribute

0.4 (2012-12-04)¶

• Upgraded to jQuery 1.8.3

• Upgraded to Jasmine 1.3.0

• Synchronous URLs and context fetch.

• Use django.utils.termcolors

• Class based javascript testing tools:

  • Factorize JsTestCase common behaviour
  • Removed JsTestCase.run_jasmine() and added JasmineMixin
  • Removed JsTestCase.run_qunit() and added QUnitMixin
  • Extract TapParser into djangojs.tap

• Only one Django.js test suite

• Each framework is tested against its own test suite

• Make jQuery support optionnal into JsTestCase

• Improved JsTestCase output

• Drop Python 2.6 support

• Added API documentation

0.3.2 (2012-11-10)¶

• Optionnal support for Django Absolute

0.3.1 (2012-11-03)¶

• Added JsTestView.django_js to optionnaly include django.js
• Added js_init block to runners to templates.

0.3 (2012-11-02)¶

• Improved ready event handling
• Removed runners from urls.py
• Added documentation
• Added ContextJsonView and Django.context fetched from json.
• Improved error handling
• Added DjangoJsError custom error type

0.2 (2012-10-23)¶

• Refactor template tag initialization
• Provides Jasmine and QUnit test views with test discovery (globbing)
• Provides Jasmine and QUnit test cases
• Added Django.file()
• Added {% javascript %}, {% js %} and {% css %} template tags

0.1.3 (2012-10-02)¶

• First public release
• Provides django.js with url() method and constants
• Provides {% verbatim %} template tag
• Patch jQuery.ajax() to handle CSRF tokens
• Loads the django javascript catalog for all apps supporting it
• Loads the django javascript i18n/l10n tools in the page