Source

django-coat / README

Full commit
-*- markdown -*-

## Description

django-coat is the media files handler for Django. Represented with `{% coat %}` template tag. Can add cache-aware marks and compile files (with `sass` and etc.).

## Installation

django-coat can be easily installed with `easy_install`/`pip` or from source code.

## Setup

Two simple steps:

 - Add `coat` to project's `INSTALLED_APPS`
 - Add `from coat.settings import *` to the project's settings file

## Usage

django-coat mainly consists of `{% coat %}` template tag. This tag accepts relative to `MEDIA_URL` filename and optional string of flags. Then it returns compiled (if required) version of requested file's filename with cache-aware tag. Tag is `?something` suffix of file url. It can be created with different strategies that fits the most frequent use-cases.

Media file compiling is the action of processing source media files with external programs. This programs can compress, translate or do anything they what with source files. Results of this processing are stored into filesystem and can be served this web server.

Basic usage example:

    {% load coat %}

    <link rel="stylesheet" type="text/css" href="{% coat "style.css" "absolute" %}">

Assume that `MEDIA_URL` equals to `/media/` then tag will produce:


    <link rel="stylesheet" type="text/css" href="http://example.com/media/style.css?123456">


where `123456` is file's mtime.

Available flags:

 - no-tag - do not append cache-aware tag
 - absolute - force to produce absolute url

## Settings

Available settings:

 - `COAT_COMPILED_PATTERN` (default: `'_%(name)s.%(ext)s'`) - filename pattern for compiled media files

 - `COAT_COMPILED_ROOT` (default: `None`) - absolute path to directory where compiled files will be stored. If `None` `MEDIA_ROOT` is used.

 - `COAT_COMPILED_URL` (default: `None`) - base url for compiled media files. If `None` `MEDIA_URL` is used.

 - `COAT_COMPILERS` dict (default keys: `'sass'`) - where keys are source media files extensions and values are tuples with compiled files extension and processing command.

 - `COAT_TAGGER` (default: `'coat.taggers.mtime'`) - tagger function with filename as argument.

    Available taggers:

    - `coat.taggers.mtime` - returns file mtime
    - `coat.taggers.md5` - returns file content md5 hash sum
    - `coat.taggers.md5_cached` - cached version of `md5` tagger.

 - `COAT_CACHE_PREFIX` (default: `'coat_'`) - name prefix for tagger generated cache keys

 - `COAT_CACHE_TIME` (default: `None`) - timeout for cached taggers

 - `COAT_MAX_FILE_SIZE` (default: `1024 * 2`) - maximum handled file size to tagger that try to read whole line (`md5` for example)