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