Welcome to django-auto-webassets’s documentation!¶

django-auto-webassets is a Django app that automates the creation of webassets/django-assets bundles. Besides these python libraries, it makes heavy use of requirejs.

The library was written for one particular use-case in mind which will be described here. Contributions are always welcome!

Contents:

Reference

Quickstart¶

Prerequisites¶

I assume that you have nodejs including npm installed. I also assume that the required javascript packages are declared in the package.json file and npm update installs these in a folder called node_modules. Most importantly, requirejs must be one of the required javascript packages.

I also assume that one .js file exists that configures requirejs. Here is an example:

require.config({
    "baseUrl": "/static",

    "nodeRequire": "require",

    "shim": {
        "bootstrap": {"deps": ["jquery"]},
    },

    "paths": {
        "jquery": "jquery/dist/jquery",
        "bootstrap": "bootstrap-sass/assets/javascripts/bootstrap",
    },
});

Install¶

pip install django-auto-webassets

This will also install django-assets and all necessary dependencies.

Configure¶

Next, include django-assets and django-auto-webassets in the INSTALLED_APPS section of the Django settings.py:

INSTALLED_APPS = [
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_assets',
    'django_auto_webassets'
    ]

And also make sure to include django_assets.finders.AssetsFinder in STATICFILES_FINDERS:

STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'django_assets.finders.AssetsFinder',
)

Next, make sure that the node_modules folder is included in the STATICFILES_DIRS. If the node_modules folder is in the base folder of your project, this would look like this:

STATICFILES_DIRS = [
    os.path.join(BASE_DIR, 'node_modules'),
    ...
]

Also, make sure to the django-auto-webassets where it finds the configuration file for requirejs:

WEBASSETS_PATH_TO_REQUIREJS_CFG = 'requirejs_cfg.js'

For now, I recommend that you turn off optimization and turn on assets debugging:

WEBASSETS_OPTIMIZE = False
ASSETS_DEBUG = False

The use case¶

The use case for this library is that your templates and views are hierarchical and reusable. You basically have one base.html template that basically defines your theme. Then you extend this template to create one template that displays lists and maybe another one that displays and processes forms.

As each child-template becomes more specialized, so does the javascript. There is some javascript that you need on any given page. A page that displays a list might need the general purpose javascript plus some list-displaying specifics. A specific view might then need to add the specific javascript for that view but might be able to use the generic list-displaying template.

django-auto-webassets in conjunction with requirejs makes it really easy to do this adhering to the DRY principle.

Setting up the base template¶

Assuming you have a javascript file called init_general.js that does the general javascript stuff for your pages, add this to your base template:

{% load auto_webassets %}

{% block javascript %}
   {% webassets_js "init_general.js" %}
{% endblock %}

The webassets tag automatically adds requirejs, the requirejs configuration file you defined above and init_general.js to the html output.

Depending on the configuration, it also applies optimization (e.g., bundling…) and adds the resulting file to the html output.

If you want to use a different javascript file in a child-template, just override the javascript block.

Using a different javascript file in a view¶

You can use django_auto_webassets.views.mixins.AutoWebassetsJSMixin to specify a different javascript file for that specific view.

Attention

Always include mixins before the view class!

from django_auto_webassets.views.mixins import AutoWebassetsJSMixin
from django.views.generic import TemplateView

class MyView(AutoWebassetsJSMixin, TemplateView):
   template_name = 'generic.html'
   webasset_js_file = 'specific_javascript.js'

Now specific_javascript.js is used instead of the javascript file specified in the template.

Build assets by command¶

When optimization is turned on by setting WEBASSETS_OPTIMIZE = True in the settings.py, webassets needs to build and optimize the javascript for the website. It normally does that when the specific page is requested for the first time. However, this takes a few seconds which is not good for the user experience.

Instead, you can use the management command that comes with django-auto-webassets to pre-build all bundles:

python manage.py webassetsrequirejs