django-jsdir 0.2.1

Directory concatenation

A short real-life example is better than long boring explanations. Suppose you have the following JS files layout:

static/js/
    big_script/
        00_init.js
        10_helpers.js
        50_core.js
        99_onload.js

All the files in big_script are nicely formatted and commented javascript files, perfect for debugging. But you have to include each js file from big_script in your template. And even worse, when deploying your application, you need to concatenate/compress the big_script directory and update your template accordingly. All that entirely manually.

Until now.

With django-jsdir and a few minimal changes, you will not have to worry about that anymore. The only thing to do is to get rid of all the <script> tags refering to big_script/*.js files in your template, and replace them by:

{% jsdir 'big_script' %}

django-jsdir will then take care of:

1. linking all the scripts nested under big_script directory tree when in development mode with files served from the application’s static directory. This will change nothing from the developer’s point of view, except he won’t need to update the script list anymore

2. concatenating (and possibly compressing, with the help of django-compressor) all the nested subscripts in one file named big_script.dir.js either on the first request or when you’ll run manage.py collectstatic, depending if the file already exists or not

3. linking the generated big_script.dir.js when in production mode

In other words, you do not have to change your production template (or scratch your head to find a way to do it programmatically with conditional extends or includes) AND you do not have to manually concatenate and/or compress your JS files anymore.

Inclusion of all files in a directory

Sometimes, you will prefer to import the javascript files from a directory without seeing them concatenated at all. It is the case if you have a ‘lib’ folder containing javascript librairies. In that situation, you may use the tag argument expand:

{% jsdir 'lib/' expand=True %}

In production (i.e. with DEBUG = False), jsdir will look for minified versions of the scripts (files named *.min.js) and return corresponding HTML tags. If you don’t want this behavior, you can use the tag argument minified and set it to False:

{% jsdir 'lib' expand=True minified=False %}

Remember that the order in which the HTML tags will appear in the document, and therefore the order in which the JS files will be loaded is still alphabetic. You can however ask django-jsdir to load certain files first or last.

If subdirectories or files in subdirectories must be excluded from the lookup, you may use the exclude keyword, which uses Unix-like patterns (see fnmatch). The following line will exclude all the files in lib and its subdirectories that ends with '-to_exclude.js':

{% jsdir 'lib' exclude='*-to_exclude.js' %}

{% jsdir 'lib' expand=True first='1st_pattern; 2nd_pattern' last='verylast_parttern; 2ndtolast_pattern' %}