Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 168 lines (113 sloc) 6.21 kB
d55adb3 @kellyredding more robust options stuff; reorg of tests to handle new options stuff…
authored
1 = Rack::Less
6715561 @kellyredding basic vanilla gem structure and basic README and Rakefile
authored
2
3 == Description
4
5 A better way to use LESS CSS in Ruby web apps.
6
adc596a @kellyredding version to 3.0.0
authored
7 * Update: rack-less as of v3.x.x \ uses the latest version of the ruby less parser, https://github.com/cowboyd/less.rb (based on less.js). To use the older ruby based parse, require rack-less ~> 2.0.
8
6715561 @kellyredding basic vanilla gem structure and basic README and Rakefile
authored
9 == Installation
10
d55adb3 @kellyredding more robust options stuff; reorg of tests to handle new options stuff…
authored
11 $ gem install rack-less
6715561 @kellyredding basic vanilla gem structure and basic README and Rakefile
authored
12
13 == Basic Usage
14
15 Rack::Less is implemented as a piece of Rack middleware and can be used with
16 any Rack-based application. If your application includes a rackup (`.ru`) file
17 or uses Rack::Builder to construct the application pipeline, simply require
18 and use as follows:
19
20 require 'rack/less'
adc596a @kellyredding version to 3.0.0
authored
21
62b1b69 @kellyredding updated docs for new config stuff
authored
22 # optional - use as necessary
23 Rack::Less.configure do |config|
24 config.compress = true
25 # other configs ...
26 end
c1c8b21 @kellyredding some doc cleanups and options cleanups
authored
27
28 use Rack::Less,
62b1b69 @kellyredding updated docs for new config stuff
authored
29 :source => 'app/less',
30 :hosted_at => '/'
31 # additional options ...
c1c8b21 @kellyredding some doc cleanups and options cleanups
authored
32
6715561 @kellyredding basic vanilla gem structure and basic README and Rakefile
authored
33 run app
34
35 == Using with Rails
36
37 Add this to your `config/environment.rb`:
38
1d47c9b @kellyredding reworked combinations to be more flexible and intuitive
authored
39 config.middleware.use "Rack::Less"
6715561 @kellyredding basic vanilla gem structure and basic README and Rakefile
authored
40
62b1b69 @kellyredding updated docs for new config stuff
authored
41 Add any configs in an initializer (optional - use as necessary):
42
43 Rack::Less.configure do |config|
c788ba7 @kellyredding another readme tweak
authored
44 # for example
45 config.cache = Rails.configuration.action_controller.perform_caching
46 if Rails.env.development?
47 config.cache_bust = true
48 end
62b1b69 @kellyredding updated docs for new config stuff
authored
49 end
50
6715561 @kellyredding basic vanilla gem structure and basic README and Rakefile
authored
51 You should now see `Rack::Less` listed in the middleware pipeline:
52
53 rake middleware
adc596a @kellyredding version to 3.0.0
authored
54
62b1b69 @kellyredding updated docs for new config stuff
authored
55 == Available Configurations
56
9dc7f2d @kellyredding more readme tweaks
authored
57 * .*cache* [false]
58 - Whether to cache the compilation output to a corresponding static file
d55adb3 @kellyredding more robust options stuff; reorg of tests to handle new options stuff…
authored
59
9dc7f2d @kellyredding more readme tweaks
authored
60 * .*compress* [false]
a41e096 @kellyredding updated README; some cleanups
authored
61 - Whether or not to apply compression to the concatenation output
62 - :*yui* - use YUI Compressor (gem install yui-compressor)
63 - :*whitespace* - remove extraneous whitespace only.
1d47c9b @kellyredding reworked combinations to be more flexible and intuitive
authored
64
9dc7f2d @kellyredding more readme tweaks
authored
65 * .*combinations* [{}]
66 - Directives for combining the output of many stylesheets and serving them as a single resource.
62b1b69 @kellyredding updated docs for new config stuff
authored
67
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
68 * .*cache_bust* [nil]
cf42b1b @kellyredding some minor README improvements
authored
69 - Directives for timestamping (cache-busting) stylesheet references
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
70 - :*false* - don't explicitly cache bust (no value added)
71 - :*true* - use Time.now.to_i as the explicit value (will never cache)
72 - :*nil* - change cache bust value if the file is modified (similar to Rails' stylesheet_link_tag)
73 - :*<any other value>* - add the value as "foo.css?<value>"
adc596a @kellyredding version to 3.0.0
authored
74
c788ba7 @kellyredding another readme tweak
authored
75 == Available Options
76
77 * :*root* ["."]
78 - The app root. The reference point for the source and public options.
79
80 * :*source* ['app/stylesheets']
81 - The path (relative to the root) where LESS source files are located
82
83 * :*public* ['public']
84 - The path where static files are located
85
86 * :*hosted_at* ['/stylesheets']
87 - The public HTTP path for hosted stylesheets.
88
cf42b1b @kellyredding some minor README improvements
authored
89 == Using in layouts
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
90
cf42b1b @kellyredding some minor README improvements
authored
91 === Cache Busting
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
92
93 Rails does a lot of helpful things with 'stylesheet_link_tag' to help reference your stylesheets into your layouts - things like cache busting stylesheet hrefs. However, Rails' will only cache bust your stylesheets if the file exists in the public/stylesheets directory. When using Rack::Less a file may never exist at that path or, when caching is used, only exist after the initial request.
94
95 To help provide this behavior, Rack::Less provides a helper for generating reference paths to your stylesheets.
96
97 # equivalent to: stylesheet_link_tag 'reset'
98 stylesheet_link_tag Rack::Less.stylesheet('reset')
9bc7cfd @kellyredding version to 1.3.0
authored
99
cf42b1b @kellyredding some minor README improvements
authored
100 === Combinations
62b1b69 @kellyredding updated docs for new config stuff
authored
101
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
102 At times, it is useful to combine multiple stylesheets and serve them as one resource. For example you may have two sets of stylesheets: one for traditional web views and one for mobile web views. Rails' provides the :cache option on 'stylesheet_link_tag' helper to provide this function.
1d47c9b @kellyredding reworked combinations to be more flexible and intuitive
authored
103
62b1b69 @kellyredding updated docs for new config stuff
authored
104 stylesheet_link_tag 'reset', 'common', 'app_web', :cache => 'web'
105 stylesheet_link_tag 'reset', 'common', 'iui', 'app_mobile', :cache => 'mobile'
adc596a @kellyredding version to 3.0.0
authored
106
62b1b69 @kellyredding updated docs for new config stuff
authored
107 Rack::Less uses combinations, in conjunction with the :cache config setting, to provide this function. Combinations are configured using a hash, where the key is the resource name and the value is an array of names corresponding to stylesheets to combine as the named resource. For the above example, use a configuration like this:
1d47c9b @kellyredding reworked combinations to be more flexible and intuitive
authored
108
62b1b69 @kellyredding updated docs for new config stuff
authored
109 Rack::Less.configure do |config|
110 config.combinations = {
111 'web' => ['reset', 'common', 'app_web'],
112 'mobile' => ['reset', 'common', 'iui', 'app_mobile']
113 }
114 end
1d47c9b @kellyredding reworked combinations to be more flexible and intuitive
authored
115
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
116 and stylesheet link tags like this:
1d47c9b @kellyredding reworked combinations to be more flexible and intuitive
authored
117
62b1b69 @kellyredding updated docs for new config stuff
authored
118 # equivalent to: stylesheet_link_tag 'reset', 'common', 'app_web'
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
119 stylesheet_link_tag Rack::Less.stylesheet('web')
adc596a @kellyredding version to 3.0.0
authored
120
62b1b69 @kellyredding updated docs for new config stuff
authored
121 # equivalent to: stylesheet_link_tag 'reset', 'common', 'iui', 'app_mobile'
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
122 stylesheet_link_tag Rack::Less.stylesheet('mobile')
adc596a @kellyredding version to 3.0.0
authored
123
115b15a @kellyredding doc cleanups
authored
124 If you configure Rack::Less to cache, with something like this:
62b1b69 @kellyredding updated docs for new config stuff
authored
125
126 Rack::Less.config.cache = true
adc596a @kellyredding version to 3.0.0
authored
127
62b1b69 @kellyredding updated docs for new config stuff
authored
128 then the same stylesheet link tags behave like they have the :cache option set, respectively:
129
130 # equivalent to: stylesheet_link_tag 'reset', 'common', 'app_web', :cache => 'web'
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
131 stylesheet_link_tag Rack::Less.stylesheet('web')
62b1b69 @kellyredding updated docs for new config stuff
authored
132
133 # equivalent to: stylesheet_link_tag 'reset', 'common', 'iui', 'app_mobile', :cache => 'mobile'
5a0483d @kellyredding set up a default behavior to use the mtime of your rack app's root (i…
authored
134 stylesheet_link_tag Rack::Less.stylesheet('mobile')
d55adb3 @kellyredding more robust options stuff; reorg of tests to handle new options stuff…
authored
135
136 == Links
137
0530b49 @kellyredding some README cleanups
authored
138 * *GitHub*
139 - http://github.com/kelredd/rack-less
c7495d3 @kellyredding doc cleanups
authored
140
0530b49 @kellyredding some README cleanups
authored
141 * *Less* *CSS*
142 - http://lesscss.org
6715561 @kellyredding basic vanilla gem structure and basic README and Rakefile
authored
143
144 == License
145
146 Copyright (c) 2010 Kelly Redding (mailto:kelly@kelredd.com)
147
148 Permission is hereby granted, free of charge, to any person
149 obtaining a copy of this software and associated documentation
150 files (the "Software"), to deal in the Software without
151 restriction, including without limitation the rights to use,
152 copy, modify, merge, publish, distribute, sublicense, and/or sell
153 copies of the Software, and to permit persons to whom the
154 Software is furnished to do so, subject to the following
155 conditions:
156
157 The above copyright notice and this permission notice shall be
158 included in all copies or substantial portions of the Software.
159
160 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
161 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
162 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
163 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
164 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
165 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
166 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
167 OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.