README.rst
1django-pyscss
2-------------
3
4A collection of tools for making it easier to use pyScss within Django.
5
6.. image:: https://travis-ci.org/fusionbox/django-pyscss.png
7 :target: http://travis-ci.org/fusionbox/django-pyscss
8 :alt: Build Status
9
10.. image:: https://coveralls.io/repos/fusionbox/django-pyscss/badge.png?branch=master
11 :target: https://coveralls.io/r/fusionbox/django-pyscss
12 :alt: Coverage Status
13
14
15.. note::
16
17 This version only supports pyScss 1.3.4 and greater. For pyScss 1.2 support,
18 you can use the 1.x series of django-pyscss.
19
20
21Installation
22============
23
24django-pyscss supports Django 1.4+, and Pythons 2 and 3.
25
26You may install django-pyscss off of PyPI::
27
28 pip install django-pyscss
29
30
31Why do we need this?
32====================
33
34This app smooths over a lot of things when dealing with pyScss in Django. It
35
36- Overwrites the import system to use Django's staticfiles app. This way you
37 can import SCSS files from any app (or any file that's findable by the
38 STATICFILES_FINDERS) with no hassle.
39
40- Configures pyScss to work with the staticfiles app for its image functions
41 (e.g. inline-image and sprite-map).
42
43- It provides a django-compressor precompile filter class so that you can
44 easily use pyScss with django-compressor without having to bust out to the
45 shell. This has the added benefit of removing the need to configure pyScss
46 through its command-line arguments AND makes it possible for the exceptions
47 and warnings that pyScss emits to bubble up to your process so that you can
48 actually know what's going on.
49
50
51Rendering SCSS manually
52=======================
53
54You can render SCSS manually from a string like this:
55
56.. code-block:: python
57
58 from django_pyscss import DjangoScssCompiler
59
60 compiler = DjangoScssCompiler()
61 compiler.compile_string(".foo { color: green; }")
62
63You can render SCSS from a file like this:
64
65.. code-block:: python
66
67 from django_pyscss import DjangoScssCompiler
68
69 compiler = DjangoScssCompiler()
70 compiler.compile('css/styles.scss')
71
72The file needs to be able to be located by staticfiles finders in order to be
73used.
74
75The ``DjangoScssCompiler`` class is a subclass of ``scss.Compiler`` that
76injects the ``DjangoExtension``. ``DjangoExtension`` is what overrides the
77import mechanism.
78
79``DjangoScssCompiler`` also turns on the CompassExtension by default, if you
80wish to turn this off you do so:
81
82.. code-block:: python
83
84 from django_pyscss import DjangoScssCompiler
85 from django_pyscss.extensions.django import DjangoExtension
86
87 compiler = DjangoScssCompiler(extensions=[DjangoExtension])
88
89For a list of options that ``DjangoScssCompiler`` accepts, please see the
90pyScss `API documentation <http://pyscss.readthedocs.org/en/latest/python-api.html#new-api>`_.
91
92
93Using in conjunction with django-compressor
94===========================================
95
96django-pyscss comes with support for django-compressor. All you have to do is
97add it to your ``COMPRESS_PRECOMPILERS`` setting. :
98
99.. code-block:: python
100
101 COMPRESS_PRECOMPILERS = (
102 # ...
103 ('text/x-scss', 'django_pyscss.compressor.DjangoScssFilter'),
104 # ...
105 )
106
107Then you can just use SCSS like you would use CSS normally. :
108
109.. code-block:: html+django
110
111 {% compress css %}
112 <link rel="stylesheet" type="text/x-scss" href="{% static 'css/styles.css' %}">
113 {% endcompress %}
114
115If you wish to provide your own compiler instance (for example if you wanted to
116change some settings on the ``DjangoScssCompiler``), you can subclass
117``DjangoScssFilter``. :
118
119.. code-block:: python
120
121 # myproject/scss_filter.py
122 from django_pyscss import DjangoScssCompiler
123 from django_pyscss.compressor import DjangoScssFilter
124
125 class MyDjangoScssFilter(DjangoScssFilter):
126 compiler = DjangoScssCompiler(
127 # Example configuration
128 output_style='compressed',
129 )
130
131 # settings.py
132 COMPRESS_PRECOMPILERS = (
133 # ...
134 ('text/x-scss', 'myproject.scss_filter.MyDjangoScssFilter'),
135 # ...
136 )
137
138
139Running the tests
140=================
141
142You can run the tests by running.
143
144 $ python setup.py test
145
146Please note that this will collecstatic into ``tmp/static/`` automatically as
147some of the tests require the staticfiles to have been collected.
148
