openstack/deb-python-django-compressor
Code Issues Proposed changes

Merge pull request #200 from diox/develop

Browse Source 
Update behind the scenes doc to match current offline behavior
This commit is contained in:
Jannis Leidel
2012-02-03 09:02:39 -08:00
parent 2c880ac2e5 ed652612ff
commit 82171dbc41
1 changed files with 19 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/behind-the-scenes.txt
View File

@@ -6,20 +6,27 @@ 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.
First step: Offline cache
Offline cache
-------------------------
The first thing {% compress %} tries to do is get the offline cache for its
nodelist if offline cache is activated. 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 cache should return the HTML
containing the element code for the combined file or piece of code (which,
if the cache key exists, is supposed to already exist on disk/custom storage).
If offline cache is activated, rhe first thing {% compress %} tries to do is
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 dictionnary, 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. Generating the offline manifest, using the ``compress``
management command, also generate the combined files referenced in the manifest.
Everything stops here if the cache entry exists.
If offline cache is activated and the nodelist hash can not be found inside the
manifest, {% compress %} will raise an ``OfflineGenerationError``.
Second step: parsing and file list
If offline cache is de-activated, the following happens:
First step: parsing and file list
----------------------------------
A compressor instance is created, which in turns instantiates the HTML parser.
@@ -27,7 +34,7 @@ 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.
Third step: Checking the "main" cache
Second step: Checking the "main" cache
-------------------------------------
Compressor checks if it can get some info about the combined file/hunks
@@ -37,7 +44,7 @@ element code, just like in the offline step before.
Everything stops here if the cache entry exists.
Fourth step: Generating the combined file if needed
Third step: Generating the combined file if needed
---------------------------------------------------
The file is generated if necessary. All precompilers are called and all