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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
:tocdepth: 3
django-assets
=============
.. module:: django_assets
.. toctree::
:maxdepth: 1
jinja2
settings
django-assets helps you to integrate `webassets`_ into your `Django`_
application.
.. _webassets: http://github.com/miracle2k/webassets
.. _Django: https://www.djangoproject.com/
Quickstart
----------
First, add ``django_assets`` to your ``INSTALLED_APPS`` setting:
.. code-block:: python
INSTALLED_APPS = (
...,
'django_assets',
)
Create an ``assets.py`` file inside your *application* directory. This
is where you define your assets, and like Django's ``admin.py`` files,
they will automatically be picked up:
.. code-block:: python
from django_assets import Bundle, register
js = Bundle('common/jquery.js', 'site/base.js', 'site/widgets.js',
filters='jsmin', output='gen/packed.js')
register('js_all', js)
.. note::
Make sure your ``assets.py`` is inside a Django *application*, not in
the *project*. That is, the path might be something like
``my_project/my_application/assets.py``.
If you want to define assets in a different place, you can use the
:data:`~django_assets.settings.ASSETS_MODULES` setting.
Finally, include the bundle you defined in the appropriate place within your
templates:
.. code-block:: django
{% load assets %}
{% assets "js_all" %}
<script type="text/javascript" src="{{ ASSET_URL }}"></script>
{% endassets %}
``django-assets`` will now automatically merge and compress your bundle's
source files the first time the template is rendered, and will
automatically update the compressed file every time a source file changes.
If :data:`~django_assets.settings.ASSETS_DEBUG` is enabled, then each source
file will be outputted individually instead.
Templates only
~~~~~~~~~~~~~~
If you prefer, you can also do without defining your bundles in code, and
simply define everything inside your template:
.. code-block:: django
{% load assets %}
{% assets filters="jsmin", output="gen/packed.js", "common/jquery.js", "site/base.js", "site/widgets.js" %}
<script type="text/javascript" src="{{ ASSET_URL }}"></script>
{% endassets %}
You can also pass in ``depends`` through templatetags with a slightly
modified comma-delimated syntax, e.g.
``depends="myfile.js,path/to/file.js"``.
The management command
~~~~~~~~~~~~~~~~~~~~~~
``django-assets`` also provides a management command, ``manage.py assets``.
It can be used to manually cause your bundles to be rebuilt::
$ ./manage.py assets build
Building asset: cache/site.js
Building asset: cache/ie7.js
Building asset: cache/site.css
Note that this is more difficult if you are defining your bundles within
your templates, rather than in code. You then need to use the
``--parse-templates`` option, so the ``build`` command can find the bundles.
``staticfiles`` integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~
``django-assets`` can integrate with Django's
:doc:`django.contrib.staticfiles <staticfiles>`.
Jinja2 support
~~~~~~~~~~~~~~
See :doc:`jinja2` if you want to use ``django-assets`` with the Jinja2
templating language.
Settings
~~~~~~~~~~~~
See :doc:`settings` for on overview of Django configuration values.
webassets documentation
-----------------------
For further information, have a look at the complete
:ref:`webassets documentation <index>`, and in particular, the
following topics:
- :ref:`All about bundles <webassets:bundles>`
- :ref:`Builtin filters <webassets:builtin-filters>`
- :ref:`Custom filters <webassets:custom-filters>`
- :ref:`CSS compilers <webassets:css-compilers>`
- :ref:`FAQ <webassets:faq>`
|
