Skip to main content

Django template tags to compile all kinds of static files (SASS, LESS, CoffeeScript).

Project description

Django Static Precompiler

Django Static Precompiler provides template tags to compile CoffeeScript, SASS / SCSS and LESS. It works with both inline code and extenal files.

Build Status

Installation

  1. Add “static_precompiler” to INSTALLED_APPS setting.

  2. Run syncdb or migrate static_precompiler if you use South.

  3. Make sure that you have necessary compilers installed.

  4. Optionally, you can specify the full path to compilers (for example SCSS_EXECUTABLE='/usr/local/bin/sass').

  5. In case you use Django’s staticfiles contrib app you have to add static-precompiler’s file finder to the STATICFILES_FINDERS setting, for example:

    STATICFILES_FINDERS = (
        'django.contrib.staticfiles.finders.FileSystemFinder',
        'django.contrib.staticfiles.finders.AppDirectoriesFinder',
        # other finders..
        'static_precompiler.finders.StaticPrecompilerFinder',
    )

Note that by default compiled files are saved into COMPILED folder under your STATIC_ROOT (or MEDIA_ROOT if you have no STATIC_ROOT in your settings). You can change this folder with STATIC_PRECOMPILER_ROOT and STATIC_PRECOMPILER_OUTPUT_DIR settings.

Note that all relative URLs in your stylesheets are converted to absolute URLs using your STATIC_URL setting.

General settings

STATIC_PRECOMPILER_COMPILERS

List of enabled compilers. You can modify it to enable your custom compilers. Default:

STATIC_PRECOMPILER_COMPILERS = (
    'static_precompiler.compilers.CoffeeScript',
    'static_precompiler.compilers.SASS',
    'static_precompiler.compilers.SCSS',
    'static_precompiler.compilers.LESS',
)
STATIC_PRECOMPILER_ROOT

Controls the absolute file path that compiled files will be written to. Default: STATIC_ROOT.

STATIC_PRECOMPILER_OUTPUT_DIR

Controls the directory inside STATIC_PRECOMPILER_ROOT that compiled files will be written to. Default: "COMPILED".

STATIC_PRECOMPILER_USE_CACHE

Whether to use cache for inline compilation. Default: True.

STATIC_PRECOMPILER_CACHE_TIMEOUT

Cache timeout for inline styles (in seconds). Default: 30 days.

STATIC_PRECOMPILER_MTIME_DELAY

Cache timeout for reading the modification time of source files (in seconds). Default: 10 seconds.

STATIC_PRECOMPILER_CACHE_NAME

Name of the cache to be used. If not specified then the default django cache is used. Default: None.

STATIC_PRECOMPILER_PREPEND_STATIC_URL

Add STATIC_URL to the output of template tags. Default: False

STATIC_PRECOMPILER_DISABLE_AUTO_COMPILE

Disable automatic compilation from template tags or compile_static utility function. Files are compiled only with compilestatic command (see below).

{% compile %} tag

{% compile %} is a template tag that allows to compile any source file supported by compilers configured with STATIC_PRECOMPILER_COMPILERS settings. For example:

{% load compile_static %}

<script src="{{ STATIC_URL}}{% compile "path/to/script.coffee" %}"></script>
<link rel="stylesheet" href="{{ STATIC_URL}}{% compile "path/to/styles1.less" %}" />
<link rel="stylesheet" href="{{ STATIC_URL}}{% compile "path/to/styles2.scss" %}" />

renders to:

<script src="/static/COMPILED/path/to/script.js"></script>
<link rel="stylesheet" href="/static/COMPILED/path/to/styles1.css" />
<link rel="stylesheet" href="/static/COMPILED/path/to/styles2.css" />

CoffeeScript

Settings

COFFEESCRIPT_EXECUTABLE

Path to CoffeeScript compiler executable. Default: "coffee".

Example Usage

Inline CoffeeScript:

{% load coffeescript %}

<script type="text/javascript">
  {% inlinecoffeescript %}
    console.log "Hello, World!"
  {% endinlinecoffeescript %}
</script>

renders to:

<script type="text/javascript">
  (function() {
    console.log("Hello, World!");
  }).call(this);
</script>

External file:

{% load coffeescript %}

<script src="{{ STATIC_URL}}{% coffeescript "path/to/script.coffee" %}"></script>

renders to:

<script src="/static/COMPILED/path/to/script.js"></script>

SASS / SCSS

Settings

SCSS_EXECUTABLE

Path to SASS compiler executable. Default: “sass”.

SCSS_USE_COMPASS

Boolean. Wheter to use compass or not. Compass must be installed in your system. Run “sass –compass” and if no error is shown it means that compass is installed.

Example Usage

Inline SCSS:

{% load scss %}

<style>
  {% inlinescss %}
    #header {
      h1 {
        font-size: 26px;
        font-weight: bold;
      }
      p { font-size: 12px;
        a { text-decoration: none;
          &:hover { border-width: 1px }
        }
      }
    }
  {% endinlinescss %}
</style>

renders to:

<style>
  #header h1 {
    font-size: 26px;
    font-weight: bold; }
  #header p {
    font-size: 12px; }
    #header p a {
      text-decoration: none; }
      #header p a:hover {
        border-width: 1px; }
</style>

External file:

{% load scss %}

<link rel="stylesheet" href="{{ STATIC_URL}}{% scss "path/to/styles.scss" %}" />

renders to:

<link rel="stylesheet" href="/static/COMPILED/path/to/styles.css" />

LESS

Settings

LESS_EXECUTABLE

Path to LESS compiler executable. Default: "lessc".

Example Usage

Inline LESS:

{% load less %}

<style>
  {% inlineless %}
    #header {
      h1 {
        font-size: 26px;
        font-weight: bold;
      }
      p { font-size: 12px;
        a { text-decoration: none;
          &:hover { border-width: 1px }
        }
      }
    }
  {% endinlineless %}
</style>

renders to:

<style>
  #header h1 {
    font-size: 26px;
    font-weight: bold;
  }
  #header p {
    font-size: 12px;
  }
  #header p a {
    text-decoration: none;
  }
  #header p a:hover {
    border-width: 1px;
  }
</style>

External file:

{% load less %}

<link rel="stylesheet" href="{{ STATIC_URL}}{% less "path/to/styles.less" %}" />

renders to:

<link rel="stylesheet" href="/static/COMPILED/path/to/styles.css" />

Usage with forms media

If you want to use static_precompiler in form media definitions, you can use the following approach:

from django import forms
from static_precompiler.utils import compile_static

class MyForm(forms.Form):

    @property
    def media(self):
        return forms.Media(
            css={"all": (
                compile_static("styles/myform.scss"),
            )},
            js=(
                compile_static("scripts/myform.coffee"),
            )
        )

compilestatic management command

Django Static Precompiler includes a management command compilestatic. If will scan your static files for source files and compile all of them.

You can use this command in conjunction with STATIC_PRECOMPILER_DISABLE_AUTO_COMPILE setting if you use custom STATICFILES_STORAGE such as S3 or some CDN. In that case you can should run compilestatic every time when your source files change and then run collectstatic.

You can run compilestatic in watch mode (--watch option). In watch mode it will monitor the changes in your source files and re-compile them on the fly. It can be handy if you use tools such as LiveReload.

You should install Watchdog to use watch mode.

Changes

0.7

  • Add compilestatic management command (replaces static_precompiler_watch)

  • Add STATIC_PRECOMPILER_DISABLE_AUTO_COMPILE to settings

  • Add STATIC_PRECOMPILER_CACHE_NAME to settings

  • Bugfixes

0.6

  • Add STATIC_PRECOMPILER_PREPEND_STATIC_URL to settings

  • Add {% compile %} template tag

0.5.3

  • Update the parsing of @import statements. Fix the bug with URLs containing commas.

0.5.2

  • static_precompiler_watch: watch for changes in all directories handled by static finders, not only STATIC_ROOT

  • static_precompiler_watch: add --no-initial-scan option

0.5.1

  • Fix SCSS compilation error when importing Compass styles

0.5

  • Add Python 3 support

0.4

  • Add compile_static and compile_static_lazy utility functions.

0.3

  • Bug fixes

  • Add Windows compatibility

0.2

  • Reduce the max length of varchar fields in Dependency model to meet MySQL limitations

  • static_precompiler_watch: don’t fall with exception on compilation errors or if source file is not found

0.1

  • Initial release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-static-precompiler-0.7.tar.gz (21.3 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page