.. _behind_the_scenes:

Behind the Scenes
=================

This document assumes you already have an up and running instance of
Django Compressor, and that you understand how to use it in your templates.
The goal is to explain what the main template tag, {% compress %}, does
behind the scenes, to help you debug performance problems for instance.

Offline compression
-------------

If offline compression is activated, the {% compress %} tag will try to
retrieve the compressed version for its nodelist from the offline manifest
cache. It doesn't parse, doesn't check the modified times of the files, doesn't
even know which files are concerned actually, since it doesn't look inside the
nodelist of the template block enclosed by the ``compress`` template tag.
The offline cache manifest is just a json file, stored on disk inside the
directory that holds the compressed files. The format of the manifest is simply
a key-value dictionary, with the hash of the nodelist being the key,
and the HTML containing the element code for the combined file or piece of code
being the value. The ``compress`` management command generates the
offline manifest as well as the combined files referenced in the manifest.

If offline compression is enabled and the nodelist hash can not be found inside the
manifest, {% compress %} will raise an ``OfflineGenerationError``.

If offline compression is disabled, the following happens:

First step: parsing and file list
---------------------------------

A compressor instance is created, which in turns instantiates the HTML parser.
The parser is used to determine a file or code hunk list. Each file mtime is
checked, first in cache and then on disk/storage, and this is used to
determine an unique cache key.

Second step: Checking the "main" cache
--------------------------------------

Compressor checks if it can get some info about the combined file/hunks
corresponding to its instance, using the cache key obtained in the previous
step. The cache content here will actually be the HTML containing the final
element code, just like in the offline step before.

Everything stops here if the cache entry exists.

Third step: Generating the combined file if needed
--------------------------------------------------

The file is generated if necessary. All precompilers are called and all
filters are executed, and a hash is determined from the contents. This in
turns helps determine the file name, which is only saved if it didn't exist
already. Then the HTML output is returned (and also saved in the cache).
And that's it!
