.. _usage: Usage ===== .. code-block:: django {% load compress %} {% compress [ [block_name]] %} {% 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 .. note:: Remember that django-compressor will try to :ref:`group outputs by media `. Linked files **must** be accessible via :attr:`~django.conf.settings.COMPRESS_URL`. If the :attr:`~django.conf.settings.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. .. note:: If you've configured any :attr:`precompilers ` setting :attr:`~django.conf.settings.COMPRESS_ENABLED` to ``False`` won't affect the processing of those files. Only the :attr:`CSS ` and :attr:`JavaScript filters ` will be disabled. If both DEBUG and :attr:`~django.conf.settings.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 :attr:`~django.conf.settings.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:: The compress template tag also supports a third argument for naming the output of that particular compress tag. This is then added to the context so you can access it in the `post_compress signal `. .. _memcached: http://memcached.org/ .. _caching documentation: https://docs.djangoproject.com/en/1.8/topics/cache/#memcached .. _offline_compression: Offline Compression --------------- 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 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 ``{% compress %}`` blocks. It then will use the context as defined in :attr:`django.conf.settings.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 (``greeting``) you need to specify this in your settings before using the ``compress`` management command:: COMPRESS_OFFLINE_CONTEXT = { 'greeting': 'Hello there!', } The result of running the ``compress`` management command will be cached in a file called ``manifest.json`` using the :attr:`configured storage ` to be able to be transferred from your development computer to the server easily. .. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders .. _signals: Signals ------- .. function:: compressor.signals.post_compress(sender, type, mode, context) Django Compressor includes a ``post_compress`` signal that enables you to listen for changes to your compressed CSS/JS. This is useful, for example, if you need the exact filenames for use in an HTML5 manifest file. The signal sends the following arguments: ``sender`` Either :class:`compressor.css.CssCompressor` or :class:`compressor.js.JsCompressor`. .. versionchanged:: 1.2 The sender is now one of the supported Compressor classes for easier limitation to only one of them, previously it was a string named ``'django-compressor'``. ``type`` Either "``js``" or "``css``". ``mode`` Either "``file``" or "``inline``". ``context`` The context dictionary used to render the output of the compress template tag. If ``mode`` is "``file``" the dictionary named ``compressed`` in the context will contain a "``url``" key that maps to the relative URL for the compressed asset. If ``type`` is "``css``", the dictionary named ``compressed`` in the context will additionally contain a "``media``" key with a value of ``None`` if no media attribute is specified on the link/style tag and equal to that attribute if one is specified. Additionally, ``context['compressed']['name']`` will be the third positional argument to the template tag, if provided. .. note:: When compressing CSS, the ``post_compress`` signal will be called once for every different media attribute on the tags within the ``{% compress %}`` tag in question. .. _css_notes: 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