jac 0.18.0
A Jinja extension (compatible with Flask and other frameworks) to compile and/or compress your assets.

.. image:: https://travis-ci.org/jaysonsantos/jinja-assets-compressor.svg?branch=master
    :target: https://travis-ci.org/jaysonsantos/jinja-assets-compressor
    :alt: Build Status

jinja-assets-compressor
=======================

A Jinja2 extension to compile and/or compress your assets.


Installing
----------

::

    pip install jac

For LESS and CSS support, install `less <https://www.npmjs.org/package/less>`_::

    npm install -g less

For COFFEE support, install `coffee-script <https://www.npmjs.com/package/coffee-script>`_::

    npm install -g coffee-script

For Sass and SCSS support, install `sass <https://rubygems.org/gems/sass>`_::

    gem install sass

JavaScript minification is built-in using the Python
`rJsmin <https://pypi.python.org/pypi/rjsmin>`_ package.

When installing on Mac OS X set this shell variable, because jac dependencies
contain C code::

    export CFLAGS=-Qunused-arguments


Usage
-----

To use it, you just have to put your css or js inside a compress tag.

.. code-block:: python

    {% compress 'css' %}
    <style type="text/sass">
    sass stuff
    </style>
    <link rel="stylesheet" type="text/sass" href="file.sass">
    {% endcompress %}

    {% compress 'js' %}
    <script type="text/coffeescript">
    coffee stuff
    </script>
    <script type="text/coffeescript" src="file.coffee"></script>
    {% endcompress %}


Configuring Jinja
-----------------

You just have to create an environment with jac on it and configure output dir,
static prefix and say where it can find your sources.

.. code-block:: python

    import jinja2

    from jac import CompressorExtension

    env = jinja2.Environment(extensions=[CompressorExtension])
    env.compressor_output_dir = './static/dist'
    env.compressor_static_prefix = '/static'
    env.compressor_source_dirs = './static_files'

After that just use ``template = env.from_string(html); template.render()`` to
get it done.


Configuring Flask
-----------------

Where you configure your app, just do this:

.. code-block:: python

    from jac.contrib.flask import JAC

    app = Flask(__name__)
    app.config['COMPRESSOR_DEBUG'] = app.config.get('DEBUG')
    app.config['COMPRESSOR_OUTPUT_DIR'] = './static/dist'
    app.config['COMPRESSOR_STATIC_PREFIX'] = '/static'
    jac = JAC(app)

And you are done.


Offline Compression
-------------------

JAC supports compressing static assets offline, then deploying to a production
server. Here is a command to compress your static assets if using Flask: ::

    python -m jac.contrib.flask my_flask_module:create_app

Replace ``my_flask_module`` with the correct import path to find your Flask app.


Custom Compressors
------------------

The ``compressor_classes`` template env variable tells jac which compressor to
use for each mimetype. The default value for ``compressor_classes`` is:

.. code-block:: python

    {
        'text/css': LessCompressor,
        'text/coffeescript': CoffeeScriptCompressor,
        'text/less': LessCompressor,
        'text/javascript': JavaScriptCompressor,
        'text/sass': SassCompressor,
        'text/scss': SassCompressor,
    }

To use an alternate compressor class, provide a class with a ``compile`` class
method accepting arg ``text`` and kwargs ``mimetype``, ``cwd``, ``uri_cwd``,
and ``debug``. For example, to use
`libsass-python <https://github.com/dahlia/libsass-python>`_ for SASS files
instead of the built-in SassCompressor, create your custom compressor class:

.. code-block:: python

    import sass

    class CustomSassCompressor(object):
        """Custom compressor for text/sass mimetype.

        Uses libsass-python for compression.
        """

        @classmethod
        def compile(cls, text, cwd=None, **kwargs):

            include_paths = []
            if cwd:
                include_paths += [cwd]

            return sass.compile(string=text, include_paths=include_paths)

Then tell jac to use your custom compressor for ``text/sass`` mimetypes:

.. code-block:: python

    env.compressor_classes['text/sass'] = CustomSassCompressor

The equivalent for Flask is:

.. code-block:: python

    jac.set_compressor('text/sass', CustomSassCompressor)

To only customize the path of a compressor which forks a subprocess for the
compile step (LessCompressor, CoffeeScriptCompressor, and SassCompressor), just
extend the compressor class and overwrite the ``binary`` class attribute:

.. code-block:: python

    from jac.compressors import SassCompressor

    class CustomSassCompressor(SassCompressor):
        """Custom SASS compressor using Compass binary instead of libsass for text/sass mimetype.

        Uses the faster libsass wrapper sassc for SASS compression.
        https://github.com/sass/sassc
        """

        binary = '/usr/bin/sassc'

    # Tell Flask to use our custom SASS compressor
    jac.set_compressor('text/sass', CustomSassCompressor)


Running Tests
-------------

::

    virtualenv venv
    . venv/bin/activate
    pip install -r requirements_tests.txt
    make coverage
    make lint

Or use tox to run with multiple python versions:

::

    pip install tox
    tox


CHANGELOG
---------

0.17.2
``````

- Make sure that flask contrib script always push an app context.

0.17.1
``````

- Fix error when the blueprint cannot be found (i.e. flask debug toolbar)

0.17.0
``````

- Fix app factory initialization
- Change how tests and linters run
- Add compress command to `jac.contrib.flask`