Merge pull request #770 from karyon/clarify_offline_compression
Clarify offline compression
This commit is contained in:
commit
36e8f34c4d
|
@ -1,6 +1,6 @@
|
|||
.. _behind_the_scenes:
|
||||
|
||||
Behind the scenes
|
||||
Behind the Scenes
|
||||
=================
|
||||
|
||||
This document assumes you already have an up and running instance of
|
||||
|
@ -8,25 +8,25 @@ 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 cache
|
||||
Offline compression
|
||||
-------------
|
||||
|
||||
If offline cache is activated, the first thing {% compress %} tries to do is
|
||||
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,
|
||||
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. Generating the offline manifest, using the ``compress``
|
||||
management command, also generates the combined files referenced in the manifest.
|
||||
being the value. The ``compress`` management command generates the
|
||||
offline manifest as well as the combined files referenced in the manifest.
|
||||
|
||||
If offline cache is activated and the nodelist hash can not be found inside the
|
||||
If offline compression is enabled 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:
|
||||
If offline compression is disabled, the following happens:
|
||||
|
||||
First step: parsing and file list
|
||||
---------------------------------
|
||||
|
|
|
@ -1,10 +1,11 @@
|
|||
Jinja2 In-Request Support
|
||||
=========================
|
||||
Jinja2 Support
|
||||
==============
|
||||
|
||||
Django Compressor comes with support for Jinja2_ via an extension.
|
||||
|
||||
Plain Jinja2
|
||||
------------
|
||||
|
||||
In-Request Compression
|
||||
----------------------
|
||||
|
||||
In order to use Django Compressor's Jinja2 extension we would need to pass
|
||||
``compressor.contrib.jinja2ext.CompressorExtension`` into environment::
|
||||
|
@ -25,20 +26,21 @@ From now on, you can use same code you'd normally use within Django templates::
|
|||
template.render({'STATIC_URL': settings.STATIC_URL})
|
||||
|
||||
|
||||
Jinja2 Offline Compression Support
|
||||
==================================
|
||||
You'd need to configure ``COMPRESS_JINJA2_GET_ENVIRONMENT`` so that
|
||||
Offline Compression
|
||||
-------------------
|
||||
|
||||
Usage
|
||||
^^^^^
|
||||
First, you will need to configure ``COMPRESS_JINJA2_GET_ENVIRONMENT`` so that
|
||||
Compressor can retrieve the Jinja2 environment for rendering.
|
||||
This can be a lambda or function that returns a Jinja2 environment.
|
||||
|
||||
Usage
|
||||
-----
|
||||
Run the following compress command along with an ``--engine`` parameter. The
|
||||
parameter can be either jinja2 or django (default). For example,
|
||||
Then, run the following compress command along with an ``--engine`` parameter.
|
||||
The parameter can be either jinja2 or django (default). For example,
|
||||
``./manage.py compress --engine jinja2``.
|
||||
|
||||
Using both Django and Jinja2 templates
|
||||
--------------------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
There may be a chance that the Jinja2 parser is used to parse Django templates
|
||||
if you have a mixture of Django and Jinja2 templates in the same location(s).
|
||||
This should not be a problem since the Jinja2 parser will likely raise a
|
||||
|
@ -56,7 +58,7 @@ However, it is still recommended that you do not mix Django and Jinja2
|
|||
templates in the same project.
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
^^^^^^^^^^^
|
||||
- Does not support ``{% import %}`` and similar blocks within
|
||||
``{% compress %}`` blocks.
|
||||
- Does not support ``{{super()}}``.
|
||||
|
@ -65,7 +67,7 @@ Limitations
|
|||
should run fine.
|
||||
|
||||
Jinja2 templates location
|
||||
-------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
IMPORTANT: For Compressor to discover the templates for offline compression,
|
||||
there must be a template loader that implements the ``get_template_sources``
|
||||
method, and is in the ``TEMPLATE_LOADERS`` setting.
|
||||
|
@ -86,7 +88,7 @@ the filesystem loader (``django.template.loaders.filesystem.Loader``) in the
|
|||
``TEMPLATE_DIRS`` setting.
|
||||
|
||||
Using your custom loader
|
||||
------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
You should configure ``TEMPLATE_LOADERS`` as such::
|
||||
|
||||
TEMPLATE_LOADERS = (
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
.. _remote_storages:
|
||||
|
||||
Remote storages
|
||||
Remote Storages
|
||||
---------------
|
||||
|
||||
In some cases it's useful to use a CDN_ for serving static files such as
|
||||
|
|
|
@ -45,7 +45,9 @@ You will find offline compression beneficial if:
|
|||
:attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` binaries in one
|
||||
location.
|
||||
|
||||
* You store compressed files on a CDN.
|
||||
* You store compressed files on a CDN.
|
||||
|
||||
* You want the best possible performance.
|
||||
|
||||
Caveats
|
||||
-------
|
||||
|
|
|
@ -459,9 +459,7 @@ Offline settings
|
|||
:Default: ``False``
|
||||
|
||||
Boolean that decides if compression should be done outside of the
|
||||
request/response loop. (See :ref:`behind_the_Scenes` for more.) This allows
|
||||
to pre-compress CSS and JavaScript files and works just like the automatic
|
||||
compression with the ``{% compress %}`` tag.
|
||||
request/response loop. See :ref:`offline_compression` for details.
|
||||
|
||||
.. attribute:: COMPRESS_OFFLINE_TIMEOUT
|
||||
|
||||
|
|
|
@ -107,22 +107,22 @@ access it in the `post_compress signal <signals>`.
|
|||
.. _memcached: http://memcached.org/
|
||||
.. _caching documentation: https://docs.djangoproject.com/en/1.8/topics/cache/#memcached
|
||||
|
||||
.. _pre-compression:
|
||||
|
||||
Pre-compression
|
||||
.. _offline_compression:
|
||||
|
||||
Offline Compression
|
||||
---------------
|
||||
|
||||
Django Compressor comes with an optional ``compress`` management command to
|
||||
run the compression outside of the request/response loop -- independent
|
||||
from user requests. This allows to pre-compress CSS and JavaScript files and
|
||||
works just like the automatic compression with the ``{% compress %}`` tag.
|
||||
Django Compressor has the ability to run the compression "offline",
|
||||
i.e. outside of the request/response loop -- independent from user requests.
|
||||
If offline compression is enabled, no new files are generated during a request
|
||||
and the ``{% compress %}`` tag simply inserts links to the files in the
|
||||
offline cache (see :ref:`behind_the_scenes` for details). This results in better
|
||||
performance and enables certain deployment scenarios (see :ref:`scenarios`).
|
||||
|
||||
To compress the files "offline" and update the offline cache you have
|
||||
to use the ``compress`` management command, ideally during deployment.
|
||||
Also make sure to enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
|
||||
setting. In case you don't use the ``compress`` management command, Django
|
||||
Compressor will automatically fallback to the automatic compression using
|
||||
the template tag.
|
||||
To use offline compression, enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
|
||||
setting and then run the ``compress`` management command to compress your assets
|
||||
and update the offline cache.
|
||||
|
||||
The command parses all templates that can be found with the template
|
||||
loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for
|
||||
|
@ -137,20 +137,18 @@ in the blocks, e.g.:
|
|||
|
||||
{% load compress %}
|
||||
{% compress js %}
|
||||
<script src="{{ path_to_files }}js/one.js" type="text/javascript" charset="utf-8"></script>
|
||||
<script type="text/javascript">
|
||||
alert("{{ greeting }}");
|
||||
</script>
|
||||
{% endcompress %}
|
||||
|
||||
Since this template requires a variable (``path_to_files``) you need to
|
||||
specify this in your settings before using the ``compress`` management
|
||||
command::
|
||||
Since this template requires a variable (``greeting``) you need to specify
|
||||
this in your settings before using the ``compress`` management command::
|
||||
|
||||
COMPRESS_OFFLINE_CONTEXT = {
|
||||
'path_to_files': '/static/js/',
|
||||
'greeting': 'Hello there!',
|
||||
}
|
||||
|
||||
If not specified, the ``COMPRESS_OFFLINE_CONTEXT`` will by default contain
|
||||
the commonly used setting to refer to saved files ``STATIC_URL``.
|
||||
|
||||
The result of running the ``compress`` management command will be cached
|
||||
in a file called ``manifest.json`` using the :attr:`configured storage
|
||||
<django.conf.settings.COMPRESS_STORAGE>` to be able to be transferred from your development
|
||||
|
|
Loading…
Reference in New Issue