Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Update behind the scenes doc to match current offline behavior #200

Merged
merged 1 commit into from

2 participants

@diox
Owner

This patch simply updates the behind the scenes doc first paragraph about offline cache.

@jezdez jezdez merged commit 82171db into django-compressor:develop
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 19 additions and 12 deletions.
  1. +19 −12 docs/behind-the-scenes.txt
View
31 docs/behind-the-scenes.txt
@@ -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``.
+
+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.
@@ -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
Something went wrong with that request. Please try again.