PK M2žB•'{ý5D 5D djangojs-0.7.2/settings.html
You can tune a little Django.js behaviour using settings. Django.js provide the following optionnal settings:
Specify the jQuery version to use. If not specififed, default to last version.
Django.js provide the following versions:
Serialized URLs names whitelist. If this setting is specified, only named URLs listed in will be serialized.
Serialized URLs names blacklist. It this setting is specified, named URLs listed in will not be serialized.
Serialized namespaces whitelist. If this setting is specified, only URLs from namespaces listed in will be serialized.
Serialized namespaces blacklist. It this setting is specified, URLs from namespaces listed in will not be serialized.
Serialize unnamed URLs. If this setting is set to True, unnamed URLs will be serialized (only for function based views).
Serialized translations whitelist. If specified, only apps listed in will appear in the javascript translation catalog.
Serialized translations blacklist. If specified, apps listed in will not appear in the javascript translation catalog.
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')
Django.js works with RequireJS but it requires some extras step to do it.
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.
You should add an extra shim configuration for Django.js:
require.config({
paths: {
django: 'djangojs/django'
},
shim: {
"django": {
"deps": ["jquery"],
"exports": "Django"
}
}
});
Django.js provides tools for JavaScript development with Django.
Django.js is inspired from:
Note
This is currently a work in progress (API wil not be stable before 1.0) so don’t expect it to be perfect but please submit an issue for any bug you find or any feature you want.
Django.js requires Python 2.7+ and Django 1.4.2+.
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')),
...
)
Django Absolute contribute with the following context variables:
They will be available into Django.context javascript object (nothing new, this the default behavior). But, two more methods will be available:
If you try to call these methods without django-bsolute installed, a DjangoJsError will be thrown.
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.min.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" %}
You can either:
{% load js %}
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".
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() fot Django CSRF |
You can disable all this features by simply providing arguments to the template tag:
{% django_js jquery=false i18n=false csrf=false %}
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 |
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.
When the {% django_js %} template tag is included in a page, it automatically:
loads the django javascript catalog for all supported apps
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.
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();
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 .
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.
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>
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>
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" %}" />
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>
Django.js provide tools for easy javascript testing.
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:
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):
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)
Note
Whatever TestCase you choose, it should output TAP. If you don’t have complex and specific needs, you just have to use the provided template and extends them if needed.
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.
Warning
Phantom.js is required to use this feature and should be on your $PATH.
Added namespaced URLs support
Upgraded to Jasmine 1.3.1
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
Expose PhantomJS timeout with PhantomJsRunner.timeout attribute
Upgraded to jQuery 1.8.3
Upgraded to Jasmine 1.3.0
Synchronous URLs and context fetch.
Use django.utils.termcolors
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