Flask-Funnel¶

Summary ¶

A Flask extension for compressing/minifying assets.

A Flask-Script submanager is also provided.

https://api.travis-ci.org/rehandalal/flask-funnel.png

Documentation ¶

Documentation is at http://flask-funnel.readthedocs.org/en/latest/.

Install ¶

To install:

$ pip install Flask-Funnel

You can also install the development version https://github.com/rehandalal/flask-funnel/tarball/master#egg=Flask-Funnel-dev:

$ pip install Flask-Funnel==dev

or:

$ git clone git://github.com/rehandalal/flask-funnel.git
$ mkvirtualenv flaskfunnel
$ python setup.py develop
$ pip install -r requirements.txt

Quickstart ¶

To get started using Flask-Funnel simply add the following to your Flask app:

from flask import Flask
from flask.ext.import Funnel

app = Flask(__name__)
Funnel(app)

Test ¶

To run tests from a tarball or git clone:

$ python setup.py test

Requirements ¶

Flask 0.8 (or later)

One of the following:

Java: if you want to use YUI Compressor.
NodeJS: if you want to use `Coffee-Script`_ , UglifyJS or clean-css.

Optionally:

LESS: if you need to compile LESS files.
SCSS: if you need to compile SCSS files.
Stylus: if you need to compule Stylus files.
COFFEE: if you need to compile COFFEE files.
Autoprefixer: if you want to have your CSS files autoprefixed.

Installing YUI Compressor ¶

To use YUI Compressor you must install Java. Once Java has been installed make sure to set JAVA_BIN in your application config.

You can download YUI Compressor from https://github.com/yui/yuicompressor/downloads and make sure that YUI_COMPRESSOR_BIN points to the yuicompressor-x.y.z.jar file.

Configuration ¶

There are several configuration options available for Flask-Funnel:

CSS_BUNDLES

A dict of CSS bundles:

app.config['CSS_BUNDLES'] = {
    'bundle1': (
        'stylesheet.css',
        'another.css',
        'tobecompile.less',
        'tobecompile2.scss',
    ),
}

Defaults to: {}

JS_BUNDLES

A dict of JavaScript bundles:

app.config['JS_BUNDLES'] = {
    'the_bundle': (
        'jquery.js',
        'jquery-ui.js',
        'tubecompile.coffee',
    ),
}

Defaults to: {}

CSS_MEDIA_DEFAULT

This is the default value for the media attribute of the <link> tag for stylesheets.

Defaults to: 'screen,projection,tv'

BUNDLES_DIR

The subdirectory of the static directory that the generated bundles are saved to.

Defaults to: 'bundles'

YUI_COMPRESSOR_BIN

If you plan on using YUI Compressor you must set this variable.

It has no default value.

JAVA_BIN

If you plan on using YUI Compressor you must set this variable.

It has no default value.

LESS_BIN

If you require LESS support you must point this to lessc.

Defaults to: 'lessc'

LESS_PREPROCESS

If you want LESS files to be compiled when app.debug is True and compressed files are not being used.

Defaults to: True

SCSS_BIN

If you require SCSS support you must point this to scss.

Defaults to: 'scss'

SCSS_PREPROCESS

If you want SCSS files to be compiled when app.debug is True and compressed files are not being used.

Defaults to: True

STYLUS_BIN

If you require Stylus support you must point this to stylus.

Defaults to: 'stylus'

STYLUS_PREPROCESS

If you want Stylus files to be compiled when app.debug is True and compressed files are not being used.

Defaults to: True

COFFEE_BIN

If you require COFFEE support you must point this to coffee.

Defaults to: 'coffee'

COFFEE_PREPROCESS

If you want CoffeeScript files to be compiled when app.debug is True and compressed files are not being used.

Defaults to: True

AUTOPREFIXER_BIN

If you want to use Autoprefixer you must point this to autoprefixer.

Defaults to: 'autoprefixer'

AUTOPREFIXER_ENABLED

Flag to indicated whether to run Autoprefixer on bundles and preprocessed files.

Defaults to: False

AUTOPREFIXER_BROWSERS

Determines which browsers to prefix for. See Autoprefixer documentation for more information.

Defaults to: 'last 2 versions'

UGLIFY_BIN

If you want to use UglifyJS you must set this variable.

It has no default value.

CLEANCSS_BIN

If you want to use clean-css you must set this variable.

It has no default value.

FUNNEL_USE_S3

If you are using Flask-S3 you must set this to use Flask-S3’s url_for() function.

Defaults to: False

Including bundles in templates ¶

To include a bundle in a template you can use the css() or js() function:

{# Jinja2 template #}
<!doctype html>
<html>
<head>
    <title>The Title</title>
    {{ css('bundle-name') }}
</head>
<body>
    <h1>Headline</h1>
    {{ js('bundle-name') }}
</body>
</html>

This will generate the appropriate markup for each bundle.

Note: When app.debug is True these will output markup for each file in the bundle.

Media types for stylesheets ¶

The css() function will, by default, generate <link> tags with a media attribute set to CSS_MEDIA_DEFAULT. You can override this by passing an optional second argument.

Using the manager to bundle and minify assets ¶

The extension provides a sub-manager for Flask-Script which can be used as follows:

from flask.ext.script import Manager
from flask.ext.funnel.manager import manager as funnel_manager

manager = Manager(app)
manager.add_command('funnel', funnel_manager)

You can now use the manager to bundle and minify your assets using:

$ ./manage.py funnel bundle_assets

This will create a bundle folder within the app’s static folder to store the bundled files. CSS bundles go into a css subfolder and JavaScript bundles go into the js subfolder. Each of these subfolders will have a number of *-min.* files which are the compressed and minified versions of the bundles.