django.js 0.1.3

Django JS Tools

Django.js provides tools for JavaScript development with Django.

This is currently a work in progress so don’t expect it to be perfect.

Django.js is inspired from:

• Miguel Araujo’s verbatim snippet.

• Dimitri Gnidash’s django-js-utils.

Installation

You can install Django.JS with pip:

$ pip install django.js

or with easy_install:

$ easy_install django.js

Add djangojs to your settings.INSTALLED_APPS.

Add djangojs.urls to your root URL_CONF:

urlpatterns = patterns('',
    ...
    url(r'^djangojs/', include('djangojs.urls')),
    ...
)

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 setting.py:

from django.template import add_to_builtins

add_to_builtins('djangojs.templatetags.js')

Usage

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>

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>
    $(Django).on('ready', function() {
        console.log(
            Django.url('my-view'),
            Django.url('my-view', 'arg1'),
            Django.url('my-view', ['arg1']),
            Django.url('my-view', {key: 'test'}),
            Django.trans('my string')
        );
    });
    Django.init({% django_urls_json %});
</script>

If you don’t want to manually trigger initialization, you can use the {% django_js_init %} tag:

{% django_js_init %}
<script>
    $(Django).on('ready', function() {
        console.log(Django.url('my-view'));
    });
</script>

django_js tag also configure jQuery.ajax to handle CSRF tokens.

jquery_js

The {% jquery_js %} tag only load the jQuery (1.8.2) library.

The django_js and django_js_init tags automatically load jQuery so no need to manually load it.

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>

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'});

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

Constants

Django.js wraps some Django constants:

• Django.STATIC_URL

• Django.LANGUAGES

• Django.LANGUAGE_CODE

• Django.LANGUAGE_NAME

• Django.LANGUAGE_NAME_LOCAL

• Django.LANGUAGE_BIDI

Other features

When the django_js template tag is included in a page, it automatically:

• 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:

  • gettext()

  • ngettext()

  • interpolate()