README.md in sinatra-assetpack-0.2.0 vs README.md in sinatra-assetpack-0.2.1
- old
+ new
@@ -1,88 +1,78 @@
# [Sinatra AssetPack](http://ricostacruz.com/sinatra-assetpack)
-> Package your assets transparently in Sinatra.
+> The most convenient way to manage your assets in Sinatra.
[](https://travis-ci.org/rstacruz/sinatra-assetpack)
[](http://badge.fury.io/rb/sinatra-assetpack)
[](https://gemnasium.com/rstacruz/sinatra-assetpack)
[](https://codeclimate.com/github/rstacruz/sinatra-assetpack)
-How it works
-------------
+## Installation
-This is *the* most convenient way to set up your CSS/JS (and images) in a
-[Sinatra](http://sinatrarb.com) app. Seriously. No need for crappy routes to
-render Sass or whatever. No-siree!
-
-1. Drop your assets into `/app` like so (you can configure directories don't worry):
- * JavaScript/CoffeeScript files in `/app/js`
- * CSS/Sass/Less/CSS files in `/app/css`
- * Images into `/app/images`
-3. Add `register Sinatra::AssetPack` and set up options to your app (see below).
-4. Use `<%= js :app %>` and `<%= css :application %>` to your layouts. Use these instead of
- messy *script* and *link* tags.
-5. BOOM! You're in business baby!
-
-Installation
-------------
-
-Add to your `Gemfile` :
-
``` ruby
+# Gemfile
gem 'sinatra-assetpack', :require => 'sinatra/assetpack'
```
+## Setup
-Setup
------
+Register the extension and set your assets configuration.
-Install the plugin and add some options. (Feel free to omit the *Optional*
- items, they're listed here for posterity):
-
``` ruby
require 'sinatra/assetpack'
class App < Sinatra::Base
- set :root, File.dirname(__FILE__)
+ set :root, File.dirname(__FILE__) # You must set app root
+
register Sinatra::AssetPack
assets {
- serve '/js', from: 'app/js' # Optional
- serve '/css', from: 'app/css' # Optional
- serve '/images', from: 'app/images' # Optional
+ serve '/js', from: 'app/js' # Default
+ serve '/css', from: 'app/css' # Default
+ serve '/images', from: 'app/images' # Default
# The second parameter defines where the compressed version will be served.
# (Note: that parameter is optional, AssetPack will figure it out.)
js :app, '/js/app.js', [
'/js/vendor/**/*.js',
- '/js/app/**/*.js'
+ '/js/lib/**/*.js'
]
css :application, '/css/application.css', [
'/css/screen.css'
]
- js_compression :jsmin # Optional
- css_compression :sass # Optional
+ js_compression :jsmin # :jsmin | :yui | :closure | :uglify
+ css_compression :simple # :simple | :sass | :yui | :sqwish
}
end
```
+## Usage
+
+1. Drop your assets into `/app/css`, `/app/js`, `/app/images`.
+2. Add `register Sinatra::AssetPack` (see setup options).
+3. Use `<%= js :app %>` and `<%= css :application %>` in your layout.
+4. You now have proper assets management!
+
#### Using in layouts
In your layouts, use the `css` and `js` helpers:
-*(Use haml? Great! Use `!= css :youreawesome` instead.)*
``` erb
+# layout.erb
<%= css :application, :media => 'screen' %>
<%= js :app %>
```
+```
+# layout.haml
+!= css :application, :media => 'screen'
+!= css :app
+```
+## Results
-And then what?
---------------
-
#### Development mode
If you're on **development** mode, it serves each of the files as so:
``` html
<link rel='stylesheet' href='/css/screen.849289.css' media='screen' type='text/css' />
@@ -97,12 +87,11 @@
``` html
<link rel='stylesheet' href='/css/application.849289.css' media='screen' type='text/css' />
<script type='text/javascript' src='/js/app.589491.js'></script>
```
-Features
---------
+## Features
* __CoffeeScript support__ Just add your coffee files in one of the paths
served (in the example, `app/js/hello.coffee`) and they will be available as JS
files (`http://localhost:4567/js/hello.js`).
@@ -127,12 +116,11 @@
* __Auto minification (with caching)__ JS and CSS files will be compressed as
needed.
* __Heroku support__ Oh yes. That's right.
-Compressors
------------
+## Compressors
By default, AssetPack uses [JSMin](http://rubygems.org/gems/jsmin) for JS
compression, and simple regexes for CSS compression. You can specify other
compressors in the `assets` block:
@@ -143,45 +131,39 @@
}
```
### YUI Compressor
-This uses Yahoo's Java-powered YUI compressor. For YUI compression, you need the
-YUI compressor gem (`gem install yui-compressor`).
+This uses Yahoo's Java-powered YUI compressor.
``` ruby
assets {
js_compression :yui
js_compression :yui, :munge => true # Munge variable names
css_compression :yui
}
```
-__Note:__ This depends on the `yui-compressor` gem. You will need to install it.
-(`gem install yui-compressor`) If you use Bundler, you will need to add it to
-your Gemfile as well.
+__Note:__ This depends on the `yui-compressor` gem :
``` ruby
# Gemfile
gem 'yui-compressor', :require => 'yui/compressor'
```
### SASS compression
-For SASS compression, you need the Sass gem (`gem install sass`). This treats
-the CSS files as Scss files and uses Sass's `:output => :compressed`.
+This treats the CSS files as Scss files and uses Sass's `:output => :compressed`.
``` ruby
assets {
css_compression :sass
}
```
-__Note:__ This depends on the `sass` gem. You will need to install it (`gem
-install sass`). If you use Bundler, you will need to add it to your Gemfile as
-well.
+__Note:__ This depends on the `sass` gem :
``` ruby
# Gemfile
gem 'sass'
```
@@ -230,26 +212,19 @@
js_compression :uglify
js_compression :uglify, [options]
}
```
-__Note:__ This depends on the `uglifier` gem. In your Gemfile, you will need to
-add it. For Heroku support, you will need to add the `therubyracer-heroku` gem
-as well.
+__Note:__ This depends on the `uglifier` gem :
``` ruby
# Gemfile
gem 'uglifier'
-
-# If you're on Heroku:
-gem "therubyracer-heroku", "0.8.1.pre3", :require => false
```
+## Images
-Images
-------
-
To show images, use the `img` helper.
This automatically adds width, height, and a cache buster thingie.
ImageMagick is required to generate full image tags with width and height.
``` html
@@ -272,15 +247,12 @@
``` css
/* Original: */ .email { background: url(/images/email.png?embed); }
/* Output: */ .email { background: url(data:image/png;base64,NF8dG3I...); }
```
-Need to build the files?
-------------------------
+## Precompile
-Actually, you don't need to—this is optional! But add this to your `Rakefile`:
-
``` ruby
# Rakefile
APP_FILE = 'app.rb'
APP_CLASS = 'App'
@@ -291,14 +263,14 @@
Now invoke the `assetpack:build` Rake task. This will create files in `/public`.
$ rake assetpack:build
-API reference
--------------
+## Settings
#### Assets block
+
All configuration happens in the `assets` block. You may invoke it in 2 ways:
``` ruby
class App < Sinatra::Base
register Sinatra::AssetPack
@@ -552,14 +524,39 @@
expires 86400*365, :public
}
end
```
+### assets.cache_dynamic_assets
+Caches dynamic files unless they have been modified.
-API reference: helpers
-----------------------
+Useful during development if asset compilation of all dynamic assets on each request is slow.
+If set to true, dynamic assets will be compiled on the initial asset request, but only be re-compiled when the asset's mtime changes.
+``` ruby
+# Usage:
+cache_dynamic_assets {true|false}
+```
+
+#### Example
+In this example, all dynamic files will be compiled on first request, but later requests will be served from a cache unless the file is modified
+
+``` ruby
+class App < Sinatra::Base
+ assets {
+ js_compression :closure
+
+ js :application, [
+ '/js/vendor/jquery.*.js',
+ '/js/vendor/jquery.js'
+ ]
+ cache_dynamic_assets true
+ }
+end
+
+## Helpers
+
These are helpers you can use in your views.
### <%= css %>
Shows a CSS package named `PACKAGE`. If `OPTIONS_HASH` is given, they will we
@@ -640,39 +637,24 @@
<!-- Output: -->
<img src='/images/icon.834782.png' width='24' height='24' alt='Icon' />`
```
-Need Compass support?
----------------------
+## Compass
-No, AssetPack doesn't have built-in [Compass](http://compass-style.org) support,
-but you can use [Sinatra Support](http://sinefunc.com/sinatra-support).
+AssetPack doesn't have built-in [Compass](http://compass-style.org)
+support, but you can include it easily with
+[Sinatra Support](https://github.com/sinefunc/sinatra-support/).
-For an example of how to use AssetPack with Compass, including on how to use it
-to generate image [sprites][compsprite], see the [Compass example
-application.][compex]
+See also the [Compass example application.][compass]
-[compex]: https://github.com/rstacruz/sinatra-assetpack/tree/master/examples/compass
-[compsprite]: http://compass-style.org/reference/compass/utilities/sprites/
+[compass]: https://github.com/rstacruz/sinatra-assetpack/tree/master/examples/compass
-``` ruby
-# gem install sinatra/support
-Encoding.default_external = 'utf-8'
-require 'sinatra/support'
+## Contributing
-class Main
- register Sinatra::CompassSupport
-end
-```
-
-Contributing
-------------
-
See [CONTRIBUTING.md](https://github.com/rstacruz/sinatra-assetpack/blob/master/CONTRIBUTING.md) for details on contributing and running test.
-Acknowledgements
-----------------
+## Acknowledgements
© 2011-2013, Rico Sta. Cruz. Released under the [MIT
License](http://www.opensource.org/licenses/mit-license.php).
Sinatra-AssetPack is authored by [Rico Sta. Cruz][rsc] with help
\ No newline at end of file