Introduction

django-jq provide a set of utilities to ease jQuery integration in a Django project.

Installation

For the installation I suggest a separated folder containing a SVN external of this project. Personally I like to use a folder named "contrib" to put in all my externals.

$: cd myDjangoProject/
$: mkdir contrib/
$: svn add contrib/
$: svn propedit svn:externals contrib/

An editor will open a (most likely) blank file, just add the following line:

django_jq http://django-jq.googlecode.com/svn/trunk/

Save the file, exit the editor and perform a svn up. At this point django-jq should have been checked out in contrib/.

Now edit settings.py and add the following lines;

import sys
sys.path.append('contrib/')

Also add 'django_jq' to your INSTALLED_APPS. Now it should work but only with Google Ajax API. In order to serve the file locally we must add the urls.

To do that open your main urls.py file and add those line below your media url;

urlpatterns += patterns('',
    (r'^media/(.*)$', 'django.views.static.serve', {'document_root': 'media'}),
    (r'^jq-media/', include('django_jq.urls')),
)

One last step is necessary to serve jQuery locally. The jQuery files must be cached locally. To do this without pain, I've made a Django management script:

$: python manage.py jqsetup

This command will fetch all jQuery versions specified in JQUERY_VERSIONS. To only cache or update one version you can do the following:

$: python manage.py jqsetup --onlyversion 1.3

URLs routing

Django-jq brings the power of the Django URL dispatcher to the client side and allow you to work with named URLs. This is great because it allow to change your URLs in Django without ever breaking your JavaScript code (as long as the URL name does not change of course).

Installation

This feature is implemented with a simple_tag, however it needs to import your application URLs. So in templatetags/jquery.py I must try to import it dynamically, which looks like an ugly hack;

module = settings.ROOT_URLCONF.split('.')
# A little kitten die each time you do this.
exec "from %s import %s" % (module[0], module[1])

This is not the most reliable nor the most optimal way to do it, but it's the only way I've found to get it working without further configurations. If it bother you I would advise to specify the module import manually or tell me a better way to do it.

Usage

Now the fun part starts. To enable this functionality simply call the template tag like this in you base template;

{% jquery_urls %}

When it's done you'll have access to all the named URLs. Take the following url example;

urlpatterns = patterns('myProject.main.views',
    url(r'^$', 'home', name='home'),
    url(r'^/view/contact/(\d+)/$', 'view_contact', name='view-contact'),
    url(r'^/calendar/(?P<year>\d{4})/$', 'view_calendar', name='view-calendar'),
)

To get the "home" URL you can simply do the following:

$.url('home');
// returns "/"

There is two ways to pass parameters to the URLs, first with an annotated object for named arguments and with standard arguments for anonymous parameter.

For example;

$.url('view-contact', 1);
// returns "/view/contact/1/"

$.url('view-calendar', {year: 2009});
// returns "/calendar/2009/"

If the URL expects an argument and you don't provide it, it will returns the URLs with the parameter slugs, making it easy to spot and fix missing arguments;

$.url('view-contact');
// returns "/view/%_0/"

$.url('view-calendar', {year: 2009});
// returns "/calendar/%year/"

Note: If you pass to much arguments: if they are named arguments they will be converted as GET variables, but if they are anonymous arguments they will be dropped.

$.url('view-contact', 1, 2, 3, 4);
// returns "/view/1/"

$.url('view-calendar', {year: 2009, sort: 'asc', 'limit': 10});
// returns "/calendar/2009/?sort=asc&limit=10"

Templatetags

{% jquery_script %}

Used to load jQuery locally or with Google Ajax API.

Examples

{% jquery_script %}
<script type="text/javascript" src="/jq-media/jquery/1.3/jquery.js"></script>

{% jquery_script "1.2.6" %}
<script type="text/javascript" src="/jq-media/jquery/1.2.6/jquery.js"></script>

{% jquery_script "1.3" 1 %}
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.js"></script>

Note: Minified version can be loaded by setting DEBUG to False in settings.py.

Settings

All these settings have defaults and you can override them in your settings.py file.

JQUERY_VERSIONS   = ['1.2.3', '1.2.6', '1.3.0', '1.3.1', '1.3.2']
JQUERY_REMOTE_URL = 'http://ajax.googleapis.com/ajax/libs/jquery/%s/jquery%s.js'
JQUERY_LOCAL_URL  = '/jq-media/jquery/%s/jquery%s.js'

To come

Check the possibility of making custom Django form widgets for jQuery UI widgets
jQuery UI integration

► Sign in to add a comment