fusionbox / django-pyscss

Makes it easier to use PyScss in Django
https://pypi.python.org/pypi/django-pyscss
BSD 2-Clause "Simplified" License
19 stars 13 forks source link

django-pyscss

A collection of tools for making it easier to use pyScss within Django.

.. image:: https://travis-ci.org/fusionbox/django-pyscss.png :target: http://travis-ci.org/fusionbox/django-pyscss :alt: Build Status

.. image:: https://coveralls.io/repos/fusionbox/django-pyscss/badge.png?branch=master :target: https://coveralls.io/r/fusionbox/django-pyscss :alt: Coverage Status

.. note::

This version only supports pyScss 1.3.4 and greater. For pyScss 1.2 support,
you can use the 1.x series of django-pyscss.

Installation

django-pyscss supports Django 1.4+, and Pythons 2 and 3.

You may install django-pyscss off of PyPI::

pip install django-pyscss

Why do we need this?

This app smooths over a lot of things when dealing with pyScss in Django. It

Rendering SCSS manually

You can render SCSS manually from a string like this:

.. code-block:: python

from django_pyscss import DjangoScssCompiler

compiler = DjangoScssCompiler()
compiler.compile_string(".foo { color: green; }")

You can render SCSS from a file like this:

.. code-block:: python

from django_pyscss import DjangoScssCompiler

compiler = DjangoScssCompiler()
compiler.compile('css/styles.scss')

The file needs to be able to be located by staticfiles finders in order to be used.

The DjangoScssCompiler class is a subclass of scss.Compiler that injects the DjangoExtension. DjangoExtension is what overrides the import mechanism.

DjangoScssCompiler also turns on the CompassExtension by default, if you wish to turn this off you do so:

.. code-block:: python

from django_pyscss import DjangoScssCompiler
from django_pyscss.extensions.django import DjangoExtension

compiler = DjangoScssCompiler(extensions=[DjangoExtension])

For a list of options that DjangoScssCompiler accepts, please see the pyScss API documentation <http://pyscss.readthedocs.org/en/latest/python-api.html#new-api>_.

Using in conjunction with django-compressor

django-pyscss comes with support for django-compressor. All you have to do is add it to your COMPRESS_PRECOMPILERS setting. :

.. code-block:: python

COMPRESS_PRECOMPILERS = (
    # ...
    ('text/x-scss', 'django_pyscss.compressor.DjangoScssFilter'),
    # ...
)

Then you can just use SCSS like you would use CSS normally. :

.. code-block:: html+django

{% compress css %}
<link rel="stylesheet" type="text/x-scss" href="https://github.com/fusionbox/django-pyscss/blob/master/{% static 'css/styles.css' %}">
{% endcompress %}

If you wish to provide your own compiler instance (for example if you wanted to change some settings on the DjangoScssCompiler), you can subclass DjangoScssFilter. :

.. code-block:: python

# myproject/scss_filter.py
from django_pyscss import DjangoScssCompiler
from django_pyscss.compressor import DjangoScssFilter

class MyDjangoScssFilter(DjangoScssFilter):
    compiler = DjangoScssCompiler(
        # Example configuration
        output_style='compressed',
    )

# settings.py
COMPRESS_PRECOMPILERS = (
    # ...
    ('text/x-scss', 'myproject.scss_filter.MyDjangoScssFilter'),
    # ...
)

Running the tests

You can run the tests by running.

$ python setup.py test

Please note that this will collecstatic into tmp/static/ automatically as some of the tests require the staticfiles to have been collected.