Permalink
Browse files

Merge pull request #200 from diox/develop

Update behind the scenes doc to match current offline behavior
  • Loading branch information...
2 parents 2c880ac + ed65261 commit 82171dbc41d0c71fb950da758e707107e18f34b8 Jannis Leidel committed Feb 3, 2012
Showing with 19 additions and 12 deletions.
  1. +19 −12 docs/behind-the-scenes.txt
View
@@ -6,28 +6,35 @@ 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``.
+
+If offline cache is de-activated, the following happens:
-Second step: parsing and file list
+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.
-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

0 comments on commit 82171db

Please sign in to comment.