Skip to content
This repository
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 332 lines (219 sloc) 10.169 kb
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 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
Django compressor
=================

Compresses linked and inline JavaScript or CSS into a single cached file.

Syntax
------

.. code-block:: django

    {% load compress %}
    {% compress <js/css> %}
    <html of inline or linked JS/CSS>
    {% endcompress %}

Examples
--------

.. code-block:: django

    {% load compress %}

    {% compress css %}
    <link rel="stylesheet" href="/static/css/one.css" type="text/css" charset="utf-8">
    <style type="text/css">p { border:5px solid green;}</style>
    <link rel="stylesheet" href="/static/css/two.css" type="text/css" charset="utf-8">
    {% endcompress %}

Which would be rendered something like:

.. code-block:: django

    <link rel="stylesheet" href="/static/cache/css/f7c661b7a124.css" type="text/css" charset="utf-8">

or:

.. code-block:: django

    {% load compress %}

    {% compress js %}
    <script src="/static/js/one.js" type="text/javascript" charset="utf-8"></script>
    <script type="text/javascript" charset="utf-8">obj.value = "value";</script>
    {% endcompress %}

Which would be rendered something like:

.. code-block:: django

    <script type="text/javascript" src="/static/cache/js/3f33b9146e12.js" charset="utf-8"></script>

Linked files must be accesible via COMPRESS_URL_. If DEBUG is true off-site
files will throw exceptions. If DEBUG is false they will be silently stripped.

If COMPRESS is ``False`` (defaults to the opposite of DEBUG) the ``compress``
template tag simply returns exactly what it was given, to ease development.

.. warning::

    For production sites it is **strongly recommended** to use a real cache
    backend such as memcached_ to speed up the checks of compressed files.
    Make sure you set your Django cache backend appropriately (also see
    COMPRESS_CACHE_BACKEND_ and Django's `caching documentation`_).

.. _memcached: http://memcached.org/
.. _caching documentation: http://docs.djangoproject.com/en/1.2/topics/cache/#memcached

CSS Notes
---------

All relative ``url()`` bits specified in linked CSS files are automatically
converted to absolute URLs while being processed. Any local absolute URLs (those
starting with a ``'/'``) are left alone.

Stylesheets that are ``@import``'d are not compressed into the main file.
They are left alone.

If the media attribute is set on <style> and <link> elements, a separate
compressed file is created and linked for each media value you specified.
This allows the media attribute to remain on the generated link element,
instead of wrapping your CSS with @media blocks (which can break your own
@media queries or @font-face declarations). It also allows browsers to avoid
downloading CSS for irrelevant media types.

Recommendations
^^^^^^^^^^^^^^^

* Use only relative or full domain absolute URLs in your CSS files.
* Avoid @import! Simply list all your CSS files in the HTML, they'll be combined anyway.

Why another static file combiner for Django?
--------------------------------------------

Short version: None of them did exactly what I needed.

Long version:

**JS/CSS belong in the templates**
  Every static combiner for Django I've seen makes you configure
  your static files in your settings.py. While that works, it doesn't make
  sense. Static files are for display. And it's not even an option if your
  settings are in completely different repositories and use different deploy
  processes from the templates that depend on them.

**Flexibility**
  django_compressor doesn't care if different pages use different combinations
  of statics. It doesn't care if you use inline scripts or styles. It doesn't
  get in the way.

**Automatic regeneration and cache-foreverable generated output**
  Statics are never stale and browsers can be told to cache the output forever.

**Full test suite**
  I has one.

Settings
--------

Django compressor has a number of settings that control its behavior.
They've been given sensible defaults.

COMPRESS
^^^^^^^^

:Default: the opposite of ``DEBUG``

Boolean that decides if compression will happen.

COMPRESS_URL
^^^^^^^^^^^^

:Default: ``STATIC_URL`` (``MEDIA_URL`` for older Django versions)

Controls the URL that linked files will be read from and compressed files
will be written to.

.. note::

    This setting defaults to ``MEDIA_URL`` in case ``STATIC_URL``
    is not given, e.g. on older Django versions (<1.3).

COMPRESS_ROOT
^^^^^^^^^^^^^

:Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` for older Django versions)

Controls the absolute file path that linked static will be read from and
compressed static will be written to.

.. note::

    This setting defaults to ``MEDIA_ROOT`` in case ``STATIC_ROOT``
    is not given, e.g. on older Django versions (<1.3).

COMPRESS_OUTPUT_DIR
^^^^^^^^^^^^^^^^^^^

:Default: ``'cache'``

Controls the directory inside COMPRESS_ROOT_ that compressed files will
be written to.

COMPRESS_CSS_FILTERS
^^^^^^^^^^^^^^^^^^^^

:Default: ``['compressor.filters.css_default.CssAbsoluteFilter']``

A list of filters that will be applied to CSS.

COMPRESS_JS_FILTERS
^^^^^^^^^^^^^^^^^^^

:Default: ``['compressor.filters.jsmin.JSMinFilter']``

A list of filters that will be applied to javascript.

COMPRESS_STORAGE
^^^^^^^^^^^^^^^^

:Default: ``'compressor.storage.CompressorFileStorage'``

The dotted path to a Django Storage backend to be used to save the
compressed files.

``compressor`` ships with one additional storage backend:

* ``'compressor.storage.GzipCompressorFileStorage'``

  A subclass of the default storage backend, which will additionally
  create ``*.gz`` files of each of the compressed files.

COMPRESS_PARSER
^^^^^^^^^^^^^^^

:Default: ``'compressor.parser.BeautifulSoupParser'``

The backend to use when parsing the JavaScript or Stylesheet files.
The backends included in ``compressor``:

- ``compressor.parser.BeautifulSoupParser``
- ``compressor.parser.LxmlParser``

See `Dependencies`_ for more info about the packages you need for each parser.

COMPRESS_CACHE_BACKEND
^^^^^^^^^^^^^^^^^^^^^^

:Default: ``"default"`` or ``CACHE_BACKEND``

The backend to use for caching, in case you want to use a different cache
backend for compressor.

If you have set the ``CACHES`` setting (new in Django 1.3),
``COMPRESS_CACHE_BACKEND`` defaults to ``"default"``, which is the alias for
the default cache backend. You can set it to a different alias that you have
configured in your ``CACHES`` setting.

If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND``
setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting.

COMPRESS_REBUILD_TIMEOUT
^^^^^^^^^^^^^^^^^^^^^^^^

:Default: ``2592000`` (30 days in seconds)

The period of time after which the compressed files are rebuilt even if
no file changes are detected.

This is also used by the ``compress`` management command which pre-compresses
the contents of ``{% compress %}`` template tags in the cache.

COMPRESS_MINT_DELAY
^^^^^^^^^^^^^^^^^^^

:Default: ``30`` (seconds)

The upper bound on how long any compression should take to run. Prevents
dog piling, should be a lot smaller than COMPRESS_REBUILD_TIMEOUT_.

COMPRESS_MTIME_DELAY
^^^^^^^^^^^^^^^^^^^^

:Default: ``10``

The amount of time (in seconds) to cache the modification timestamp of a
file. Disabled by default. Should be smaller than COMPRESS_REBUILD_TIMEOUT_
and COMPRESS_MINT_DELAY_.

COMPRESS_OFFLINE
^^^^^^^^^^^^^^^^

:Default: ``False``

Boolean that decides if compression should also be done outside of the
request/response loop -- independent from user requests. This allows to
pre-compress CSS and JavaScript files and works just like the automatic
compression with the ``{% compress %}`` tag.

To compress the files "offline" and update the offline cache you have
to use the ``compress`` management command, e.g. during deployment.
In case you don't use the ``compressor`` management command ``compressor``
will automatically fallback to the automatic compression.

It'll will look in the templates that can be found with the template
loader you specify in ``TEMPLATE_LOADERS`` for ``{% compress %}`` blocks
and use COMPRESS_OFFLINE_CONTEXT_ to render its content. So if you use
any variables inside the ``{% compress %}`` blocks, make sure to list
all values you require in COMPRESS_OFFLINE_CONTEXT_.

The result of running the ``compress`` management command will be saved
in the cache as defined in COMPRESS_CACHE_BACKEND_ for the number of
seconds defined in COMPRESS_OFFLINE_TIMEOUT_.

COMPRESS_OFFLINE_TIMEOUT
^^^^^^^^^^^^^^^^^^^^^^^^

:Default: ``31536000`` (1 year in seconds)

The period of time with which the ``compress`` management command stores
the pre-compressed the contents of ``{% compress %}`` template tags in
the cache.

COMPRESS_OFFLINE_CONTEXT
^^^^^^^^^^^^^^^^^^^^^^^^

:Default: ``{'MEDIA_URL': settings.MEDIA_URL}``

The context to be used by the ``compress`` management command when rendering
the contents of ``{% compress %}`` template tags and saving the result in the
offline cache. It's similar to a template context and should be used if a
variable is used in the blocks, e.g.:

.. code-block:: django

    {% load compress %}
    {% compress js %}
    <script src="{{ path_to_files }}js/one.js" type="text/javascript" charset="utf-8"></script>
    {% endcompress %}

Since this template requires a variable (``path_to_files``) you need to
specify this in your settings before using the ``compress`` management
command::

    COMPRESS_OFFLINE_CONTEXT = {
        'path_to_files': '/static/js/',
    }

If not specified the COMPRESS_OFFLINE_CONTEXT will fall back to contain
the commonly used setting to refer to saved files ``MEDIA_URL``.

For forward compatibility ``compressor`` will also add the ``STATIC_URL``
setting (added in Django 1.3) to the COMPRESS_OFFLINE_CONTEXT_ if it's set.

Dependencies
------------

* BeautifulSoup_ (for the default ``compressor.parser.BeautifulSoupParser``)

::

    pip install BeautifulSoup

* lxml_ (for the optional ``compressor.parser.LxmlParser``, requires libxml2_)

::

    STATIC_DEPS=true pip install lxml

.. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/
.. _lxml: http://codespeak.net/lxml/
.. _libxml2: http://xmlsoft.org/
Something went wrong with that request. Please try again.