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!
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