.. _usage: Usage ===== .. code-block:: django {% load compress %} {% compress [] %} {% endcompress %} Examples -------- .. code-block:: django {% load compress %} {% compress css %} {% endcompress %} Which would be rendered something like: .. code-block:: django or: .. code-block:: django {% load compress %} {% compress js %} {% endcompress %} Which would be rendered something like: .. code-block:: django Linked files **must** be accessible via :ref:`COMPRESS_URL `. If the :ref:`COMPRESS_ENABLED ` setting is ``False`` (defaults to the opposite of DEBUG) the ``compress`` template tag does nothing and simply returns exactly what it was given. If both DEBUG and :ref:`COMPRESS_ENABLED ` are set to ``True``, incompressible files (off-site or non existent) will throw an exception. If DEBUG is ``False`` these files will be silently stripped. .. warning:: For production sites it is **strongly recommended** to use a real cache backend such as memcached_ to speed up the checks of compressed files. Make sure you set your Django cache backend appropriately (also see :ref:`COMPRESS_CACHE_BACKEND ` and Django's `caching documentation`_). The compress template tag supports a second argument specifying the output mode and defaults to saving the result in a file. Alternatively you can pass '``inline``' to the template tag to return the content directly to the rendered page, e.g.: .. code-block:: django {% load compress %} {% compress js inline %} {% endcompress %} would be rendered something like:: .. _memcached: http://memcached.org/ .. _caching documentation: http://docs.djangoproject.com/en/1.2/topics/cache/#memcached .. _pre-compression: Pre-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. 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 :ref:`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. The command parses all templates that can be found with the template loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for ``{% compress %}`` blocks. It then will use the context as defined in :ref:`COMPRESS_OFFLINE_CONTEXT ` to render its content. So if you use any variables inside the ``{% compress %}`` blocks, make sure to list all values you require in ``COMPRESS_OFFLINE_CONTEXT``. It's similar to a template context and should be used if a variable is used in the blocks, e.g.: .. code-block:: django {% load compress %} {% compress js %} {% endcompress %} Since this template requires a variable (``path_to_files``) you need to specify this in your settings before using the ``compress`` management command:: COMPRESS_OFFLINE_CONTEXT = { 'path_to_files': '/static/js/', } If not specified, the ``COMPRESS_OFFLINE_CONTEXT`` will by default contain the commonly used setting to refer to saved files ``MEDIA_URL`` and ``STATIC_URL`` (if specified in the settings). The result of running the ``compress`` management command will be saved in the cache defined in :ref:`COMPRESS_CACHE_BACKEND ` for the number of seconds defined in the :ref:`COMPRESS_OFFLINE_TIMEOUT ` setting. .. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders CSS Notes --------- All relative ``url()`` bits specified in linked CSS files are automatically converted to absolute URLs while being processed. Any local absolute URLs (those starting with a ``'/'``) are left alone. Stylesheets that are ``@import``'d are not compressed into the main file. They are left alone. If the media attribute is set on