Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100755 191 lines (138 sloc) 4.917 kB
0e97b8a @petebrowne Rewording README a bit
petebrowne authored
1 sprockets-sass
2 ==============
72b8c81 @petebrowne Setting up the gem
petebrowne authored
3
cf3f0ba @petebrowne Update README.md
petebrowne authored
4 **Better Sass integration with [Sprockets 2.x](http://github.com/sstephenson/sprockets)**
1af094a @petebrowne Updating README
petebrowne authored
5
88935ff @petebrowne Updating README to reflect changes
petebrowne authored
6 When using Sprockets 2.x with Sass you will eventually run into a pretty big issue. `//= require` directives will not allow Sass mixins, variables, etc. to be shared between files. So you'll try to use `@import`, and that'll also blow up in your face. `sprockets-sass` fixes all of this by creating a Sass::Importer that is Sprockets aware.
1af094a @petebrowne Updating README
petebrowne authored
7
0e97b8a @petebrowne Rewording README a bit
petebrowne authored
8 _Note: This works in Rails 3.1, thanks to the [sass-rails gem](http://github.com/rails/sass-rails). But if you want to use Sprockets and Sass anywhere else, like Sinatra, use `sprockets-sass`._
9
10 ### Features
1af094a @petebrowne Updating README
petebrowne authored
11
12 * Imports Sass _partials_ (filenames prepended with "_").
27f4c9e @petebrowne Updating README to list glob import feature
petebrowne authored
13 * Import paths work exactly like `require` directives.
1af094a @petebrowne Updating README
petebrowne authored
14 * Imports either Sass syntax, or just regular CSS files.
15 * Imported files are preprocessed by Sprockets, so `.css.scss.erb` files can be imported.
16 Directives from within imported files also work as expected.
941cfe0 @petebrowne Version bump
petebrowne authored
17 * Automatic integration with Compass.
27f4c9e @petebrowne Updating README to list glob import feature
petebrowne authored
18 * Supports glob imports, like sass-rails.
d4cdbda @petebrowne Updating README to include info about asset helpers.
petebrowne authored
19 * Asset path Sass functions. **New in 0.4!**
0e97b8a @petebrowne Rewording README a bit
petebrowne authored
20
21
72b8c81 @petebrowne Setting up the gem
petebrowne authored
22 Installation
23 ------------
24
25 ``` bash
74ff2a4 @petebrowne Renaming sass-sprockets to sprockets-sass
petebrowne authored
26 $ gem install sprockets-sass
72b8c81 @petebrowne Setting up the gem
petebrowne authored
27 ```
28
0e97b8a @petebrowne Rewording README a bit
petebrowne authored
29
72b8c81 @petebrowne Setting up the gem
petebrowne authored
30 Usage
31 -----
1af094a @petebrowne Updating README
petebrowne authored
32
33 In your Rack application, setup Sprockets as you normally would, and require "sprockets-sass":
34
35 ``` ruby
36 require "sprockets"
37 require "sprockets-sass"
38 require "sass"
39
40 map "/assets" do
41 environment = Sprockets::Environment.new
42 environment.append_path "assets/stylesheets"
43 run environment
44 end
45
46 map "/" do
47 run YourRackApp
48 end
49 ```
50
51 Now `@import` works essentially just like a `require` directive, but with one essential bonus:
52 Sass mixins, variables, etc. work as expected.
53
54 Given the following Sass _partials_:
55
56 ``` scss
57 // assets/stylesheets/_mixins.scss
58 @mixin border-radius($radius) {
59 -webkit-border-radius: $radius;
60 -moz-border-radius: $radius;
61 border-radius: $radius;
62 }
63 ```
64
65 ``` scss
66 // assets/stylesheets/_settings.scss
67 $color: red;
68 ```
69
70 In another file - you can now do this - from within a Sprockets asset:
71
72 ``` scss
73 // assets/stylesheets/application.css.scss
74 @import "mixins";
75 @import "settings";
76
77 button {
78 @include border-radius(5px);
79 color: $color;
80 }
81 ```
82
83 And `GET /assets/application.css` would return something like:
84
85 ``` css
86 button {
87 -webkit-border-radius: 5px;
88 -moz-border-radius: 5px;
89 border-radius: 5px;
90 color: red; }
91 ```
72b8c81 @petebrowne Setting up the gem
petebrowne authored
92
0e97b8a @petebrowne Rewording README a bit
petebrowne authored
93
941cfe0 @petebrowne Version bump
petebrowne authored
94 Compass Integration
95 -------------------
96
97 As of version 0.3.0, Compass is automatically detected and integrated. All you have to do
98 is configure Compass like you normally would:
99
100 ``` ruby
101 require "sprockets"
102 require "sprockets-sass"
103 require "sass"
104 require "compass"
105
106 Compass.configuration do |compass|
107 # ...
108 end
109
110 map "/assets" do
111 environment = Sprockets::Environment.new
112 environment.append_path "assets/stylesheets"
113 run environment
114 end
115
116 # etc...
117 ```
118
119 The load paths and other options from Compass are automatically used:
120
121 ``` scss
122 // assets/stylesheets/application.css.scss
123 @import "compass/css3";
124
125 button {
126 @include border-radius(5px);
127 }
128 ```
129
d4cdbda @petebrowne Updating README to include info about asset helpers.
petebrowne authored
130
131 Asset Path Sass Functions
132 -------------------------
133
88935ff @petebrowne Updating README to reflect changes
petebrowne authored
134 As of version 0.4.0, asset path helpers have been added. In order to use them you must add [sprockets-helpers](https://github.com/petebrowne/sprockets-helpers) to your Gemfile:
135
136 ``` ruby
137 gem "sprockets-sass", "~> 0.5"
138 gem "sprockets-helpers", "~> 0.2"
139 # etc...
140 ```
141
142 Here's a quick guide to setting up sprockets-helpers in your application (look at the project's [README](https://github.com/petebrowne/sprockets-helpers/blob/master/README.md) for more information):
d4cdbda @petebrowne Updating README to include info about asset helpers.
petebrowne authored
143
144 ``` ruby
33c8da9 @petebrowne Adding a bit about requiring sprockets-helpers
petebrowne authored
145 require "sprockets"
146 require "sprockets-sass"
147 require "sprockets-helpers"
148 require "sass"
149
d4cdbda @petebrowne Updating README to include info about asset helpers.
petebrowne authored
150 map "/assets" do
151 environment = Sprockets::Environment.new
152 environment.append_path "assets/stylesheets"
153
154 Sprockets::Helpers.configure do |config|
155 config.environment = environment
156 config.prefix = "/assets"
157 config.digest = false
158 end
159
160 run environment
161 end
162
163 # etc...
164 ```
165
166 The Sass functions are based on the ones in sass-rails. So there is a `-path` and `-url` version of each helper:
167
168 ``` scss
169 background: url(asset-path("logo.jpg")); // background: url("/assets/logo.jpg");
170 background: asset-url("logo.jpg"); // background: url("/assets/logo.jpg");
171 ```
172
173 The API of the functions mimics the helpers provided by sprockets-helpers, using Sass keyword arguments as options:
174
175 ``` scss
7740a53 @petebrowne Update README.md
petebrowne authored
176 background: asset-url("logo.jpg", $digest: true); // background: url("/assets/logo-27a8f1f96afd8d4c67a59eb9447f45bd.jpg");
177 background: asset-url("logo", $prefix: "/themes", $ext: "jpg"); // background: url("/themes/logo.jpg");
178 ```
179
180 As of version 0.6.0, `#asset_data_uri` has been added, which creates a data URI for the given asset:
181
182 ``` scss
183 background: asset-data-uri("image.jpg"); // background: url(data:image/jpeg;base64,...);
d4cdbda @petebrowne Updating README to include info about asset helpers.
petebrowne authored
184 ```
185
186
72b8c81 @petebrowne Setting up the gem
petebrowne authored
187 Copyright
188 ---------
189
190 Copyright (c) 2011 [Peter Browne](http://petebrowne.com). See LICENSE for details.
Something went wrong with that request. Please try again.