Django Gears¶

This application provides integration with Django and Gears. Gears is a Python application that compiles and concatenates JavaScript and CSS assets. Inspired by Ruby’s Sprockets.

Source code is available on github: https://github.com/gears/django-gears

Contents¶

Installation¶

Get the code¶

You can install Django Gears with pip:

$ pip install django-gears

It’s strongly recommended to install Django Gears within an activated virtualenv.

If you want to work with the latest version of Django Gears, install it from the public repository:

$ pip install -e git+https://github.com/gears/django-gears@develop#egg=django-gears

Add to settings¶

Add django_gears to your INSTALLED_APPS settings:

INSTALLED_APPS = (
    #  ...
    'django_gears',
    #  ...
)

Configure development urls¶

from django_gears.urls import gears_urlpatterns

# url definitions here

urlpatterns += gears_urlpatterns()

Note

If you use Django’s staticfiles_urlpatterns, you should replace that with gears_urlpatterns. Django Gears falls back to serving static files when matching assets aren’t found.

Moving on¶

Congratulations. You have a working installation. Now, continue to the tutorial to learn how to use Gears in your templates.

Tutorial¶

The assets directories¶

Django Gears searches for assets in the defined assets directories. By default, this includes all assets folders defined in your installed applications. You’ll find this approach familiar if you’ve used Django’s application template loader or static files finder.

For this tutorial, imagine you have an assets directory like this:

assets/
    css/
        buttons.css
        styles.css
    js/
        script.js
        app.js
    vendor/
        jquery.js
        underscore.js

Using directives¶

The primary Gears preprocessor is based on directives. Directives are a way to handle dependencies in your css and scripts.

For example, script.js in the example folder may look like this:

/* Dependencies:
 *= require ../vendor/jquery
 *= require ../vendor/underscore
 *= require app
*/

Each line that starts with *= is a directive. Directives let you include files, trees, or directory contents into a single file. Directives are always relative to the file that contains them.

For another example, the style.css file may look like this:

/* Dependencies:
 *= require buttons.css
 *= require_self
*/

# more styles here

You can see a list of available directives here.

Adding scripts and css to templates¶

Now that the script.js and styles.css files are defined they can be included in your templates. You can do this with the {% gears %} template tags.

{% load gears %}
{% css_asset_tag "css/style.css" %}
{% js_asset_tag "js/script.js" %}

What happened?¶

Gears will construct link or script tags to the proper assets. When using the gears_urlpatterns(), the django_gears.views.serve() view will be called. This will process and serve the assets at the time of the request. You can edit the assets and reload the page to immediately see the changes.

For production, the assets will be pre-built using the collectassets command. The urls will point to these files that should be served as static files by the web server. We’ll discuss this more later.

Asset finders¶

Django Gears searches for assets to build in the defined assets directories. By default, this includes:

all assets directories in your installed applications
all assets directories listed in the GEARS_DIRS setting

We’ll cover how both of these work below.

Application finder¶

Consider a directory structure like the following, where myapp1 and myapp1 are installed applications:

myapp1/
  assets/
    js/
      script.js
      app.js

myapp2/
  assets/
    js/
      test.js

Next, consider that script.js has the following directives:

/*
 *= require test
 *= require app
*/

When script.js is processed it will include test.js from myapp2 and app.js from myapp1.

How does this happen?¶

Directives, as written, are always relative to the asset file. The idea of relative isn’t solely based on the filesystem, though. In the above example, both myapp1/assets and myapp2/assets are on the search paths. This means when test.js isn’t found in the current directory, the directive processor continues on through the rest of the directories on the search path. Here, it is found in myapp2.

Note, Gears will use the first asset it finds that matches the given path. Therefore, if you have multiple assets whose name and location is the same, Gears won’t distinguish between them. The easiest way to ensure this doesn’t happen is to place assets in custom named directories within the assets folder.

File System Finder¶

In addition to the application finder, Django Gears will look for static files in specified directories in the filesystem. These directories are controlled through the GEARS_DIRS setting.

For example, you may add an assets directory in your project root:

import os
SITE_ROOT = os.path.realpath(os.path.dirname(__file__))
GEARS_DIRS = (
    os.path.join(SITE_ROOT, "assets"),
)

By default, the file system finder has precedence over the application finders.

Configuring finders¶

If you want to configure or add custom finders of your own, see the docs on the GEARS_FINDERS setting.

Asset views¶

Serving assets in development¶

django_gears.views.serve(request, path, **kwargs)¶

Django Gears provides the serve() view for use in development. This view will process and serve any matching assets on the fly. This means you can simply reload your pages to see the latest changes.

Further, if no matching asset is found, serve() falls back to Django’s staticfiles.views.serve view. This means your application can happily serve static files alongside Gear’s assets.

The easiest way to make use of the serve() view in your application is to use the included gears_urlpatterns() function.

from django_gears.urls import gears_urlpatterns

# url definitions here

urlpatterns += gears_urlpatterns()

Sites using these urlpatterns will not need to use Django’s staticfiles urlpatterns.

Warning

Like staticfiles_urlpatterns, gears_urlpatterns only registers patterns when settings.Debug is True. This isn’t for production use. See the Deployment docs for more information.

Gears urlpatterns¶

django_gears.urls.gears_urlpatterns(prefix=None)¶

Returns development urlpatterns for serving assets.

If settings.DEBUG is false, the returned urlpatterns will be empty.

Parameters:	prefix – The url prefix to server assets under. Defaults to the `GEARS_URL` setting.

Asset template tags¶

Loading assets¶

Django Gears provides two template tags for use in templates: one for css and one for javascript.

The usage of these tags looks like:

{% load gears %}
{% css_asset_tag "css/style.css" %}
{% js_asset_tag "js/script.js" %}

This outputs script and link tags like the following:

<link rel="stylesheet" href="/<staticroot>/css/style.5d9fedbb2fdb499586390e3969277fe4208122b8.css">
<script src="/<staticroot>/js/script.2b4ef7ddce5b87d9b7fe6c7b5df40d32b923359f.js"></script>

Debug settings¶

If GEARS_DEBUG is true, the directives will not be processed into a single file. Instead, each asset will be processed and linked to individually.

For example, consider the directives:

/*
 *= require jquery
 *= require underscore
*/

The output when GEARS_DEBUG is true looks like:

<script src="/<staticroot>/jquery.js?body=1&v=1396028840.58"></script>
<script src="/<staticroot>/underscore.js?body=1&v=1396035841.85"></script>
<script src="/<staticroot>/script.js?body=1&v=1396035841.85"></script>

This behavior can also be triggered from within a template by adding a debug argument to the asset tags:

{% css_asset_tag "css/style.css" debug %}
{% js_asset_tag "js/script.js" debug %}

Asset compilers and processors¶

The asset building process consists of multiple steps. At it’s simplest, only the directives are processed and dependencies are included into the build files. The build process can do much more though, like compiling less files with lessjs or compressing js files with uglifyjs.

Each build follows these fives steps that can be customized for your environment.

Preprocess
Compile
Postprocess
Compress
Save to filesystem

1. Preprocess¶

The first step is where dependencies are managed. Gears looks for directives within assets and includes them within the asset file. As explained elsewhere, directives are simple comments in the header of script or css files. For example:

/*
 *= require jquery
 *= require underscore
 *= require backbone
*/

It’s not common to change the preprocess step, but if you wish to do so, this can be done by modifying the GEARS_PREPROCESSORS setting.

2. Compile¶

The second step compiles source files like CoffeeScript, Stylus, or Less into javascript and css. Compilers are defined in the GEARS_COMPILERS setting.

Various compilers are just a pip install away. You can browse plugins that are available at the Gears repositories github page. If you find a compiler not supported, it’s easy to create a plugin of your own.

3. Postprocess¶

The third step is where files are postprocessed. By default, Django Gears runs the gears.processors.HexdigestPathsProcessor for css files. This processor replaces url declarations in the css with fingerprinted versions. Note, this processor only works if all paths in url declarations refer to local files.

The post processors can be modified with the GEARS_POSTPROCESSORS setting.

4. Compress¶

The fourth step is where tools like SlimIt, UglifyJS, or clean-css are run. These produce minified files and minimize bandwidth requirements.

For users of Python 2.X, Gears has built-in support for SlimIt and cssmin.

Other compilers are just a pip install away. You can browse plugins that are available at the Gears repositories github page.

5. Save to filesystem¶

The fifth step is where processed files are saved to the file system. The destination directory is controlled by the GEARS_ROOT setting.

Unless GEARS_FINGERPRINTING is set to false, the asset will be fingerprinted and added to the .manifest.json file.

During this step, the file can optionally be gzipped. This is controlled by the GEARS_GZIP setting.

Deploying¶

The gears_urlpatterns() work great in development, but you don’t want to build files during the request cycle in production. Instead, the files should be built once and served as static files by your web server. The collectassets command lets you do that.

Collecting assets¶

The collectassets command is a Django management command that is invoked using the manage.py script:

python manage.py collectassets

This command collects all public assets, processes them, and saves them to the directory specified by the GEARS_ROOT setting.

In addition to processing the assets, Gears adds a .manifest.json file to the directory root. An example manifest file looks like:

{
  "files": {
    "css/styles.css": "css/style.588bb73e7fff720ac360b924fd9b33ddd2fa71c7.css",
    "js/script.js": "js/script.d78f84d27230e157031fc8ed26d1099f44d878dd.js"
  }
}

This file is a map between asset names and processed files. When an asset is included using a {% gears %} tag in production, instead of producing a url to the development view, it produces a url to the asset as specified in the manifest file.

Defining public assets¶

When collectassets is run, Gears will only process assets that are public. Gears considers any asset public that matches the GEARS_PUBLIC_ASSETS setting.

For instance, you may have a script.js file that includes many dependencies. After processing script.js, there is no need to Gears to additionally process the individual dependencies and collect them as separate files into GEARS_ROOT. This is an optimization that results in faster build times.

The default rules for collecting public assets:

include all files that either aren’t css or javascript or aren’t set to compile to css or javascript (less, style, coffee, etc.)
include css/style.css
include js/script.js

If you namespace your assets, or use a different naming convention, you’ll want to specify your own public asset patterns. For instance, if you want to process all files mapping to site.css or site.js, you could do:

GEARS_PUBLIC_ASSETS = (
    lambda path: not any(path.endswith(ext) for ext in ('.css', '.js')),
    r'site\.css$',
    r'site\.js$',
)

Serving files with your web server¶

By default, Django Gears collects assets into the STATIC_ROOT directory. If your web server is configured to serve static files already, no additional configuration is needed. If you haven’t configured this, you can follow Django’s advice on deploying static files or use a wsgi app like dj‑static.

If you specify a custom directory in GEARS_ROOT, you’ll need to update your server accordingly.

Settings¶

GEARS_CACHE¶

This defines the cache used in the Gears environment. The default values is gears.cache.SimpleCache.

GEARS_COMPRESSORS¶

A mapping of mimetype to compressors. For example:

GEARS_COMPRESSORS = {
    'application/javascript': 'gears_uglifyjs.UglifyJSCompressor',
    'text/css': 'gears_clean_css.CleanCSSCompressor',
}

By default, this setting is equal to {}. No compressors are defined.

GEARS_COMPILERS¶

A mapping of file extension to compilers. For example:

GEARS_COMPILERS = {
    '.styl': 'gears_stylus.StylusCompiler',
    '.coffee': 'gears_coffeescript.CoffeeScriptCompiler',
}

By default, this setting is equal to {}. No compilers are defined.

GEARS_DEBUG¶

Whether Gears is in debug mode or not. Defaults to the value of settings.DEBUG. This affects how the template tags process assets. See the Asset template tags docs for more information.

GEARS_DIRS¶

The list of directories to search for assets. This is used when the gears.finders.FileSystemFinder is specified in GEARS_FINDERS. Defaults to []. No directories are defined.

GEARS_FINDERS¶

The list of finders to use when searching for assets. The default finders are:

GEARS_FINDERS = (
    ('gears.finders.FileSystemFinder', {
        'directories': getattr(settings, 'GEARS_DIRS', ()),
    }),
    ('django_gears.finders.AppFinder', {}),
)

GEARS_FINGERPRINTING¶

Whether Gears should save a fingerprinted version of the asset in the build directory. A fingerprint is based on the contents of the file and thus unique for each version of it. Fingerprinted files are also added to the .manifest.json file. Defaults to True.

GEARS_GZIP¶

Whether Gears should gzip processed files at the end of the build process. Defaults to False.

GEARS_MIMETYPES¶

The mimetypes for asset file extensions. Mimetypes are used by post and preprocessors as well as compressors. The default mimetypes are:

GEARS_MIMETYPES = {
    '.css': 'text/css',
    '.js': 'application/javascript',
}

GEARS_POSTPROCESSORS¶

The list of postprocessors to run when assets are served or collected. The default postprocessors are:

GEARS_POSTPROCESSORS = {
    'text/css': 'gears.processors.HexdigestPathsProcessor',
}

GEARS_PREPROCESSORS¶

The list of preprocessors to run when assets are served or collected. The default preprocessors handle dependency management through directives.

GEARS_PREPROCESSORS = {
    'text/css': 'gears.processors.DirectivesProcessor',
    'application/javascript': 'gears.processors.DirectivesProcessor',
}

GEARS_PUBLIC_ASSETS¶

The patterns that define public assets. Only assets matching one of these patterns will be processed when collectassets is run. The default values are:

GEARS_PUBLIC_ASSETS = (
    lambda path: not any(path.endswith(ext) for ext in ('.css', '.js')),
    r'^css/style\.css$',
    r'^js/script\.js$',
)

Each pattern can either be a regular expression or a function that takes a path and returns a boolean.

GEARS_REGISTER_ENTRY_POINTS¶

If set to True plugins will be searched and registered using entry points. False by default.

GEARS_ROOT¶

The directory where built assets are stored. Defaults to settings.STATIC_ROOT.

GEARS_URL¶

The url to serve processed assets under. Defaults to settings.STATIC_URL.