openstack/deb-python-django-compressor
Code Issues Proposed changes

Extended the extension of the extension of the README.

Browse Source
This commit is contained in:
Jannis Leidel
2011-04-18 13:43:04 +02:00
parent f46533e556
commit 5873ae933a
1 changed files with 45 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
README.rst
View File

@@ -1,54 +1,65 @@
Django Compressor
=================
Django Compressor can combine and compress linked and inline Javascript
or CSS found inside a Django template into cacheable static files. It does so
through use of a template tag called `compress`.
Django Compressor combines and compresses linked and inline Javascript
or CSS in a Django templates into cacheable static files by using the
``compress`` template tag.
HTML in between `{% compress js/css %}` and `{% endcompress %}` is parsed
and searched for CSS or JS. These styles and scripts are then processed and
concatenated.
HTML in between ``{% compress js/css %}`` and ``{% endcompress %}`` is
parsed and searched for CSS or JS. These styles and scripts are subsequently
processed with optional, configurable compilers and filters.
The default action for CSS is to rewrite paths to static files and fit them
with a cache busting timestamp. For Javascript it is to compress it using
`jsmin`.
The default filter for CSS rewrites paths to static files to be absolute
and adds a cache busting timestamp. For Javascript the default filter
compresses it using ``jsmin``.
As the final result the template tag outputs a `<script>` or `<link>` tag
pointing to the optimized file. These files are stored inside Django's static
media folder and given an unique name based on their content.
As the final result the template tag outputs a ``<script>`` or ``<link>``
tag pointing to the optimized file. These files are stored inside a folder
and given an unique name based on their content. Alternatively it can also
return the resulting content to the original template directly.
Since the file name is dependend on the content these files can be given a far
future expiration date without worrying about stale browser caches.
Since the file name is dependend on the content these files can be given
a far future expiration date without worrying about stale browser caches.
The concatenation and compressing process can also be jump started outside of
the request/response cycle by using the Django management command
`manage.py compress`.
The concatenation and compressing process can also be jump started outside
of the request/response cycle by using the Django management command
``manage.py compress``.
Configurability & Extendibility
-------------------------------
Django Compressor is highly configurable and extendible. By default HTML parsing
is done using `BeautifulSoup`. As an alternative django-compress provides an
`lxml` based parser, as well as an abstract base class that makes it easy to
write a custom parser.
Django Compressor is highly configurable and extendible. The HTML parsing
is done using BeautifulSoup_ by default. As an alternative Django Compressor
provides an lxml_ and a html5lib_ based parser, as well as an abstract base
class that makes it easy to write a custom parser.
Django Compressor also comes with built in support for CSS Tidy, YUI CSS and
JS minification, the Google's Closure Compiler and a filter to convert (some)
images into `data:` URIs.
Django Compressor also comes with built-in support for `CSS Tidy`_,
`YUI CSS and JS`_ compressor, the Google's `Closure Compiler`_, a Python
port of Douglas Crockford's JSmin_, a Python port of the YUI CSS Compressor
cssmin_ and a filter to convert (some) images into `data URIs`_.
If your setup requires a different compressor, or other post-processing tool it
will be fairly easy to implement a custom filter. Simply extend from one of
the available base classes.
If your setup requires a different compressor or other post-processing
tool it will be fairly easy to implement a custom filter. Simply extend
from one of the available base classes.
More documentation about the usage and settings of django-compressor can be
found on `readthedocs.org/docs/django_compressor/en/latest`_.
More documentation about the usage and settings of Django Compressor can be
found on `django_compressor.readthedocs.org`_.
The source code for django-compressor can be found and contributed to on
The source code for Django Compressor can be found and contributed to on
`github.com/jezdez/django_compressor`_. There you can also file tickets.
The `in-development version`_ of django-compressor can be installed with
The `in-development version`_ of Django Compressor can be installed with
``pip install django_compressor==dev`` or ``easy_install django_compressor==dev``.
.. _readthedocs.org/docs/django_compressor/en/latest: http://readthedocs.org/docs/django_compressor/en/latest
.. _github.com/jezdez/django_compressor: http://github.com/jezdez/django_compressor
.. _in-development version: http://github.com/jezdez/django_compressor/tarball/master#egg=django_compressor-dev
.. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/
.. _lxml: http://lxml.de/
.. _html5lib: http://code.google.com/p/html5lib/
.. _CSS Tidy: http://csstidy.sourceforge.net/
.. _YUI CSS and JS: http://developer.yahoo.com/yui/compressor/
.. _Closure Compiler: http://code.google.com/closure/compiler/
.. _JSMin: http://www.crockford.com/javascript/jsmin.html
.. _cssmin: https://github.com/zacharyvoase/cssmin
.. _data URIs: http://en.wikipedia.org/wiki/Data_URI_scheme
.. _django_compressor.readthedocs.org: http://django_compressor.readthedocs.org/
.. _github.com/jezdez/django_compressor: https://github.com/jezdez/django_compressor
.. _in-development version: http://github.com/jezdez/django_compressor/tarball/develop#egg=django_compressor-dev