1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
~~~~~~~~~~~~~~~~~~~
Staticfiles support
~~~~~~~~~~~~~~~~~~~
.. note::
As a general rule, everything on this page only applies if
``django.contrib.staticfiles`` is found in your ``INSTALLED_APPS``
setting.
As a refresher, this is how Django's ``staticfiles`` application works:
* You spread your assets across multiple directories; often, for
example, you'd have a separate static folder for each application.
* For development, a special view is provided that will search all
these static directories, and serve the the requested file from
wherever it is found.
* For production, a ``collectstatic`` management command is
provided that will copy the files from all these locations
into a single folder, and then this directory can be served by
the webserver.
All the individual static directories are thus part of the same
url space. A ``foo.png`` in one folder will overwrite a ``foo.png``
in another.
*django-assets* integrates into this in the following way:
* When Django is in debug mode (``DEBUG=True``), webassets uses the
staticfiles mechanism to find the files you reference in bundles,
in the same way the ``staticfiles`` serve view does. You can work
with all of your assets the way you'd expect.
This even works with globs, so "\*.js" will query Javascript files
from across all of your applicatnion's static directories.
* In production, this mechanism is disabled, and you are expected to
run ``./manage.py collectstatic`` before you deploy your application
and/or want to use ``./manage.py assets build``.
.. warning::
If you are using automatic rebuilding in production, changes
will not be picked up until you have run ``collectstatic``.
Specific steps to make ``django-assets`` work with staticfiles
--------------------------------------------------------------
0. Make sure ``django.contrib.staticfiles`` is listed in ``INSTALLED_APPS``.
1. Add ``django_assets.finders.AssetsFinder`` to your ``STATICFILES_FINDERS``.
It might then look like this::
STATICFILES_FINDERS = (
"django.contrib.staticfiles.finders.FileSystemFinder",
"django.contrib.staticfiles.finders.AppDirectoriesFinder",
"django_assets.finders.AssetsFinder"
)
This is necessary so that output files written to ``STATIC_ROOT`` are
served in debug mode by the ``staticfiles`` *serve view*, which is not
the case by default. If you are not building anything in debug mode
(e.g. CoffeeScript, Sass), you can get away without this addition, but
it doesn't hurt to have it anway.
2. Make sure you run ``./manage.py collectstatic`` in production first,
before letting webassets build.
``CachedStaticFileStorage``
---------------------------
The new ``CachedStaticFileStorage`` in Django 1.4 is able to rename all
files to include their content hash in the filename, and rewrite references
to them within other static files.. This is somewhat overlapping with
webassets' own :ref:`versioning system <webassets:expiry>`.
If you prefer to use ``CachedStaticFileStorage``, you shouldn't run into
any problems. Just make sure you run ``./manage.py assets build`` first,
and ``./manage.py collectstatic`` second, so that ``collectstatic`` may
version the output files generated by your ``django-assets`` bundles.
The only case where this doesn't *just work* is if you are defining
bundles in your templates. If that is the case, you currently need to
define an ``ASSETS_ROOT`` setting that points to a different directory
then ``STATIC_ROOT``. Only then will ``collectstatic`` be able to find the
output files created with ``./manage.py build --parse-templates``, and
process them into ``STATIC_ROOT``, like any other static file.
``ManifestStaticFileStorage`` or White Noise
--------------------------------------------
If you are using Django's ``ManifestStaticFilesStorage`` or White Noise's
``GzipManifestStaticFilesStorage`` then you must build your assets after
calling ``collectstatic`` using the ``--manifest django`` option::
./manage.py assets build --manifest django
This will add the built assets to Django's static files manifest. In particular,
this ensures that White Noise realises they are cacheable static files and
will add appropriate far-future expiry headers when serving them.
|
