README.rdoc in rack-less-1.3.1 vs README.rdoc in rack-less-1.4.0
- old
+ new
@@ -72,20 +72,32 @@
- :*whitespace* - remove extraneous whitespace only.
* .*combinations* [{}]
- Directives for combining the output of many stylesheets and serving them as a single resource.
-* .*combination_timestamp* [false]
+* .*cache_bust* [nil]
- Directives for timestamping (cache-busting) while using combinations
- - :*false* - don't explicitly add timestamps
- - :*true* - add Time.now.to_i as the explicit timestamp (will never cache)
- - :*<any other value>* - add the value as "foo.css?<value>" (use something like a File.mtime to cache-bust like Rails does)
+ - :*false* - don't explicitly cache bust (no value added)
+ - :*true* - use Time.now.to_i as the explicit value (will never cache)
+ - :*nil* - change cache bust value if the file is modified (similar to Rails' stylesheet_link_tag)
+ - :*<any other value>* - add the value as "foo.css?<value>"
+
+=== Using in layouts
-=== Combinations
+==== Cache Busting
-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, ie:
+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.
+To help provide this behavior, Rack::Less provides a helper for generating reference paths to your stylesheets.
+
+ # equivalent to: stylesheet_link_tag 'reset'
+ stylesheet_link_tag Rack::Less.stylesheet('reset')
+
+==== Combinations
+
+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.
+
stylesheet_link_tag 'reset', 'common', 'app_web', :cache => 'web'
stylesheet_link_tag 'reset', 'common', 'iui', 'app_mobile', :cache => 'mobile'
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:
@@ -94,28 +106,28 @@
'web' => ['reset', 'common', 'app_web'],
'mobile' => ['reset', 'common', 'iui', 'app_mobile']
}
end
-and stylesheet link tags like this, respectively:
+and stylesheet link tags like this:
# equivalent to: stylesheet_link_tag 'reset', 'common', 'app_web'
- stylesheet_link_tag Rack::Less.combinations('web')
+ stylesheet_link_tag Rack::Less.stylesheet('web')
# equivalent to: stylesheet_link_tag 'reset', 'common', 'iui', 'app_mobile'
- stylesheet_link_tag Rack::Less.combinations('mobile')
+ stylesheet_link_tag Rack::Less.stylesheet('mobile')
If you configure Rack::Less to cache, with something like this:
Rack::Less.config.cache = true
then the same stylesheet link tags behave like they have the :cache option set, respectively:
# equivalent to: stylesheet_link_tag 'reset', 'common', 'app_web', :cache => 'web'
- stylesheet_link_tag Rack::Less.combinations('web')
+ stylesheet_link_tag Rack::Less.stylesheet('web')
# equivalent to: stylesheet_link_tag 'reset', 'common', 'iui', 'app_mobile', :cache => 'mobile'
- stylesheet_link_tag Rack::Less.combinations('mobile')
+ stylesheet_link_tag Rack::Less.stylesheet('mobile')
== Links
* *GitHub*
- http://github.com/kelredd/rack-less