sinatra-assetpack 0.0.8 → 0.0.9

data/.gitignore

@@ -1,3 +1,4 @@
 /Gemfile.lock
 /.rvmrc
 /.sass-cache
+/doc/

data/HISTORY.md

@@ -1,3 +1,18 @@
+v0.0.9 - Sep 18, 2011
+---------------------
+
+### Fixed:
+  * Fixed a bad route terminating issue. (#9)
+  * Fix the Rake task when the main App class is in a module. (#11)
+
+### Changed:
+  * Use Sinatra's `template_cache`. This makes AssetPack honor Sinatra's 
+`reload_templates` setting. (#15)
+
+### Added:
+  * Added .htc (IE behavior files) to the list of file formats to be served.
+  * Added examples.
+
 v0.0.8 - Sep 06, 2011
 ---------------------
 

data/README.md

@@ -1,9 +1,9 @@
-# Sinatra AssetPack
+# [Sinatra AssetPack](http://ricostacruz.com/sinatra-assetpack)
 #### Asset packer for Sinatra
 
 This is *the* most convenient way to set up your CSS/JS (and images) in a 
-Sinatra app. Seriously. No need for crappy routes to render Sass or whatever.
-No-siree!
+[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`
@@ -14,12 +14,26 @@ No-siree!
    messy *script* and *link* tags
 5. BOOM! You're in business baby!
 
+Installation
+------------
+
+Sinatra AssetPack is a simple Ruby gem. You can install it via `gem install`.
+
+``` console
+$ gem install sinatra-assetpack
+```
+
+#### Bundler users
+If you use Bundler, you will need to add it to your *Gemfile*.
+
+``` ruby
+gem 'sinatra-assetpack', :require => 'sinatra/assetpack'
+```
+
+
 Setup
 -----
 
- * Bundler? Add to *Gemfile*: `gem 'sinatra-assetpack', :require => 'sinatra/assetpack'`
- * Else: `$ gem install sinatra-assetpack`
-
 Install the plugin and add some options. (Feel free to omit the *Optional* 
     items, they're listed here for posterity):
 
@@ -52,18 +66,20 @@ class App < Sinatra::Base
 end
 ```
 
-In your layouts:
+#### Using in layouts
+In your layouts, use the `css` and `js` helpers:
+*(Use haml? Great! Use `!= css :youreawesome` instead.)*
 
 ``` erb
 <%= css :application, :media => 'screen' %>
 <%= js  :app %>
 ```
 
-*(Use haml? Great! Use `!= css :youreawesome`.)*
 
 And then what?
 --------------
 
+#### Development mode
 If you're on **development** mode, it serves each of the files as so:
 
 ``` html
@@ -73,6 +89,7 @@ If you're on **development** mode, it serves each of the files as so:
 <script type='text/javascript' src='/js/app/main.589491.js'></script>
 ```
 
+#### Production mode
 If you're on **production** mode, it serves a compressed version in the URLs you specify:
 
 ``` html
@@ -83,32 +100,32 @@ If you're on **production** mode, it serves a compressed version in the URLs you
 Features
 --------
 
- * __CoffeeScript support__: Just add your coffee files in one of the paths 
+ * __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`).
 
- * __Sass/Less/SCSS support__: Works the same way. Place your dynamic CSS files 
+ * __Sass/Less/SCSS support__ Works the same way. Place your dynamic CSS files 
  in there (say, `app/css/screen.sass`) and they will be available as CSS files 
  (`http://localhost:4567/css/screen.css`).
 
- * __Cache busting__: the `css` and `js` helpers automatically ensures the URL 
+ * __Cache busting__ the `css` and `js` helpers automatically ensures the URL 
  is based on when the file was last modified. The URL `/js/jquery.js` may be 
  translated to `/js/jquery.8237898.js` to ensure visitors always get the latest 
  version.
 
- * __Images support__: Image filenames in your CSS will automatically get a 
+ * __Images support__ Image filenames in your CSS will automatically get a 
  cache-busting suffix (eg, `/images/icon.742958.png`).
 
- * __Embedded images support__: You can embed images in your CSS files as 
+ * __Embedded images support__ You can embed images in your CSS files as 
  `data:` URIs by simply adding `?embed` to the end of your URL.
 
- * __No intermediate files needed__: You don't need to generate compiled files.
+ * __No intermediate files needed__ You don't need to generate compiled files.
  You can, but it's optional. Keeps your source repo clean!
 
- * __Auto minification (with caching)__: JS and CSS files will be compressed as 
+ * __Auto minification (with caching)__ JS and CSS files will be compressed as 
  needed.
 
- * __Heroku support__: Oh yes. That's right.
+ * __Heroku support__ Oh yes. That's right.
 
 Compressors
 -----------
@@ -124,11 +141,11 @@ assets {
 }
 ```
 
-
-----
-
 ### YUI Compressor
 
+This uses Yahoo's Java-powered YUI compressor. For YUI compression, you need the 
+YUI compressor gem (`gem install yui-compressor`).
+
 ``` ruby
 assets {
   js_compression  :yui
@@ -138,30 +155,23 @@ assets {
 }
 ```
 
-For YUI compression, you need the YUI compressor gem.
-
- * Bundler? Add to *Gemfile*: `gem 'yui-compressor', :require => 'yui/compressor'`
- * Else, `gem install 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`.
+
 ``` ruby
 assets {
   css_compression :sass
 }
 ```
 
-For SASS compression, you need the Sass gem.
-
- * Bundler? Add to *Gemfile*: `gem 'sass'`
- * Else, `gem install sass`
-
-----
-
 ### Sqwish CSS compression
 
+[Sqwish](http://github.com/ded/sqwish) is a NodeJS-based CSS compressor.  To use 
+Sqwish with AssetPack, install it using `npm install -g sqwish`. You need NodeJS 
+and NPM installed.
+
 ``` ruby
 assets {
   css_compression :sqwish
@@ -169,13 +179,15 @@ assets {
 }
 ```
 
-[Sqwish](http://github.com/ded/sqwish) is a NodeJS-based CSS compressor.  To use 
-Sqwish with AssetPack, install it using `npm install -g sqwish`. You need NodeJS 
-and NPM installed.
+### Google Closure compression
 
-----
+This uses the [Google closure compiler 
+service](http://closure-compiler.appspot.com/home)
+to compress your JavaScript. Available levels are:
 
-### Google Closure compression
+* `WHITESPACE_ONLY`
+* `SIMPLE_OPTIMIZATIONS`
+* `ADVANCED_OPTIMIZATIONS`
 
 ``` ruby
 assets {
@@ -184,11 +196,6 @@ assets {
 }
 ```
 
-This uses the [Google closure compiler service](http://closure-compiler.appspot.com/home)
-to compress your JavaScript.
-
-Available levels: `WHITESPACE_ONLY`, `SIMPLE_OPTIMIZATIONS`, `ADVANCED_OPTIMIZATIONS`
-
 Images
 ------
 
@@ -201,6 +208,7 @@ ImageMagick is required to generate full image tags with width and height.
 <!-- Output:   --> <img src='/images/email.873842.png' width='16' height='16' />
 ```
 
+#### URL translation
 In your CSS files, `url()`'s will automatically be translated.
 
 ``` css
@@ -208,6 +216,7 @@ In your CSS files, `url()`'s will automatically be translated.
 /* Output:   */    .email { background: url(/images/email.6783478.png); }
 ```
 
+#### Image embedding
 Want to embed images as `data:` URI's? Sure! Just add `?embed` at the end of the 
 URL.
 
@@ -219,24 +228,26 @@ URL.
 Need to build the files?
 ------------------------
 
-Actually, you don't need to--this is optional! But add this to your Rakefile:
+Actually, you don't need to—this is optional! But add this to your `Rakefile`:
 
 ``` ruby
+# Rakefile
 APP_FILE  = 'app.rb'
 APP_CLASS = 'App'
 
 require 'sinatra/assetpack/rake'
 ```
 
-Now:
+#### Invoking
+Now invoke the `assetpack:build` Rake task. This will create files in `/public`.
 
     $ rake assetpack:build
 
-This will create files in `/public`.
 
-API reference: assets block
----------------------------
+API reference
+-------------
 
+#### Assets block
 All configuration happens in the `assets` block. You may invoke it in 2 ways:
 
 ``` ruby
@@ -257,68 +268,82 @@ class App < Sinatra::Base
 end
 ```
 
-Invoking it without a block allows you to access the options.
+#### Getting options
+Invoking it without a block allows you to access the options. This works for 
+almost all the options, with the exception for `css`, `js` and `serve`.
 
 ``` ruby
 App.assets
 App.assets.js_compression   #=> :yui
 ```
 
-----
-
 ### assets.serve
 
-__Usage:__ `serve 'PATH', :from => 'LOCALPATH'`
-
 Serves files from `LOCALPATH` in the URI path `PATH`. Both parameters are 
 required.
 
 ``` ruby
-# ..This makes /app/javascripts/vendor/jquery.js
-# available as http://localhost:4567/js/vendor/jquery.js
-serve '/js', from: '/app/javascripts'
+# Usage
+serve 'PATH', :from => 'LOCALPATH'
 ```
 
-----
+#### Example
+This makes `/app/javascripts/vendor/jquery.js`
+available as `http://localhost:4567/js/vendor/jquery.js`.
 
-### assets.js_compression
-### assets.css_compression
+``` ruby
+serve '/js', from: '/app/javascripts'
+```
 
-__Usage:__ `js_compression :ENGINE`  
-__Usage:__ `js_compression :ENGINE, OPTIONS_HASH`  
-__Usage:__ `css_compression :ENGINE`  
-__Usage:__ `css_compression :ENGINE, OPTIONS_HASH`
+### assets.js\_compression<br>assets.css\_compression
 
 Sets the compression engine to use for JavaScript or CSS. This defaults to 
 `:jsmin` and `:simple`, respectively.
 
 If `OPTIONS_HASH` is given as a hash, it sets options for the engine to use.
 
-__Example 1:__ `css_compression :sqwish`  
-__Example 2:__ `css_compression :sqwish, :strict => true`
+``` ruby
+# Usage:
+assets {
+  js_compression :ENGINE
+  js_compression :ENGINE, OPTIONS_HASH
+  css_compression :ENGINE
+  css_compression :ENGINE, OPTIONS_HASH
+}
+```
 
-----
+#### Examples
+Yo seriously check this out: the first line uses Sqwish with it's defaults, and 
+the second line uses Sqwish with it's magic.
 
-### assets.js_compression_options
-### assets.css_compression_options
+``` ruby
+assets {
+  css_compression :sqwish
+  css_compression :sqwish, :strict => true
+}
+```
 
-__Usage:__ `js_compression_options HASH`  
-__Usage:__ `css_compression_options HASH`
+### assets.js\_compression\_options<br>assets.css\_compression\_options
 
 Sets the options for the compression engine to use. This is usually not needed 
 as you can already set options using `js_compression` and `css_compression`.
 
-__Example:__ `js_compression_options :munge => true`
+``` ruby
+# Usage:
+assets {
+  js_compression_options HASH
+  css_compression_options HASH
+}
+```
 
-----
+#### Example
+This sets the option for `:munge` for the CSS compression engine.
 
-### assets.css
-### assets.js
+``` ruby
+css_compression_options :munge => true
+```
 
-__Usage:__ `css :NAME, [ PATH1, PATH2, ... ]`  
-__Usage:__ `css :NAME, 'URI', [ PATH1, PATH2, ... ]`  
-__Usage:__ `js  :NAME, [ PATH1, PATH2, ... ]`  
-__Usage:__ `js  :NAME, 'URI', [ PATH1, PATH2, ... ]`
+### assets.css<br>assets.js
 
 Adds packages to be used.
 
@@ -326,18 +351,27 @@ The `NAME` is a symbol defines the ID for that given package that you can use
 for the helpers. That is, If a CSS package was defined as `css :main, [ ... ]`, 
 then you will need to use `<%= css :main %>` to render it in views.
 
-the `URI` is a string that defines where the compressed version will be served.  
-It is optional. If not provided, it will default to `"/type/name.type"` (eg: 
-`/css/main.css`).
+the `URI` is a string that defines where the compressed version will be served.
+It is optional. If not provided, it will default to `"/assets/name.type"` (eg:
+`/assets/main.css`).
 
 the `PATHs` is an array that defines files that will be served. Take note that 
 this is an array of URI paths, not local paths.
 
-If a `PATH` contains wildcards, it will be expanded in alphabetical order.  
+If a `PATH` contains wildcards, it will be expanded in alphabetical order.
 Redundancies will be taken care of.
 
-__Examples:__
+``` ruby
+# Usage:
+assets {
+  css :NAME, [ PATH1, PATH2, ... ]
+  css :NAME, 'URI', [ PATH1, PATH2, ... ]
+  js:NAME, [ PATH1, PATH2, ... ]
+  js:NAME, 'URI', [ PATH1, PATH2, ... ]
+}
+```
 
+#### Example
 In this example, JavaScript files will be served compressed as 
 `/js/application.js` (default since no `URI` is given). The files will be taken 
 from `./app/javascripts/vendor/jquery*.js`.
@@ -361,61 +395,100 @@ API reference: helpers
 
 These are helpers you can use in your views.
 
-----
-
-### css
-
-__Usage:__ `css :PACKAGE`  
-__Usage:__ `css :PACKAGE_1, :PACKAGE_2, ...  :PACKAGE_N, OPTIONS_HASH`  
-__Usage:__ `css :PACKAGE, OPTIONS_HASH`
+### <%= css %>
 
 Shows a CSS package named `PACKAGE`. If `OPTIONS_HASH` is given, they will we 
 passed onto the `<link>` tag to be generated as attributes.
 
 You may specify as many packages as you need, as shown in the second usage line.
 
-__Example 1:__ `css :main, media: 'screen'`  
-__Output:__ `<link rel='stylesheet' type='text/css' href='/css/main.873984.css' 
-media='screen' />`
+``` ruby
+# Usage:
+<%= css :PACKAGE %>
+<%= css :PACKAGE_1, :PACKAGE_2, ...  :PACKAGE_N, OPTIONS_HASH %>
+<%= css :PACKAGE, OPTIONS_HASH %>
+```
 
-__Example 2:__ `css :base, :app, :main, media: 'screen'`
+#### Example 1
+This links to the `main` stylesheet for *screen* media.
 
-----
+``` erb
+<%= css :main, media: 'screen' %>
 
-### js
+<!-- Output: -->
+<link rel='stylesheet' type='text/css' href='/css/main.873984.css' media='screen' />
+```
 
-__Usage:__ `js :PACKAGE`  
-__Usage:__ `js :PACKAGE, OPTIONS_HASH`
+#### Example 2
+You may also invoke it with multiple packages.
 
-Same as `css`, but obviously for JavaScript.
+``` erb
+<%= css :base, :app, :main, media: 'screen' %>
 
-You may also specify as many packages as you need.
+<!-- Output: -->
+<link rel='stylesheet' type='text/css' href='/css/base.873984.css' media='screen' />
+<link rel='stylesheet' type='text/css' href='/css/app.873984.css' media='screen' />
+<link rel='stylesheet' type='text/css' href='/css/main.873984.css' media='screen' />
+```
 
-__Example:__ `js :main, id: 'main_script'`  
-__Output:__ `<script type='text/javascript' src='/js/main.783439.js' id='main_script'></script>`
+### <%= js %>
 
-----
+Same as `css`, but obviously for JavaScript. You may also specify as many packages as you need, just with `css`.
 
-### img
+``` erb
+# Usage:
+<%= js :PACKAGE %>
+<%= js :PACKAGE_1, :PACKAGE_2, ...  :PACKAGE_N, OPTIONS_HASH %>
+<%= js :PACKAGE, OPTIONS_HASH %>
+```
+
+#### Example
+This example embeds the *main* package with an ID.
 
-__Usage:__ `img 'SRC'`  
-__Usage:__ `img 'SRC', OPTIONS_HASH`
+``` erb
+<%= js :main, id: 'main_script' %>
+
+<!-- Output: -->
+<script type='text/javascript' src='/js/main.783439.js' id='main_script'></script>
+```
+
+### <%= img %>
 
 Shows an `<img>` tag from the given `SRC`. If the images is found in the asset 
-directories (and ImageMagick is available), `width` and `height` attributes 
-will be added.
+directories (and ImageMagick is available), `width` and `height` attributes will 
+be added.
+
+``` ruby
+# Usage:
+img 'SRC'
+img 'SRC', OPTIONS_HASH
+```
 
 If `OPTIONS_HASH` is given, they will we passed onto the `<img>` tag to be 
 generated as attributes.
 
-__Example:__ `img '/images/icon.png', alt: 'Icon'`  
-__Output:__ `<img src='/images/icon.834782.png' width='24' height='24' alt='Icon' />`
+#### Example
+This example renders an image with an alt tag.
+
+``` erb
+<%= img '/images/icon.png', alt: 'Icon' %>
+
+<!-- Output: -->
+<img src='/images/icon.834782.png' width='24' height='24' alt='Icon' />`
+```
 
 Need Compass support?
 ---------------------
 
-No, AssetPack doesn't have built-in Compass support, but you can use [Sinatra 
-Support](http://sinefunc.com/sinatra-support):
+No, AssetPack doesn't have built-in [Compass](http://compass-style.org) support, 
+but you can use [Sinatra Support](http://sinefunc.com/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]
+
+[compex]: https://github.com/rstacruz/sinatra-assetpack/tree/master/examples/compass
+[compsprite]: http://compass-style.org/reference/compass/utilities/sprites/
 
 ``` ruby
 # gem install sinatra/support
@@ -439,3 +512,21 @@ AssetPack will eventually have:
  * Refactor *Compressor* module
  * CDN (Cloudfront, S3) support
  * Better support for Compass sprites
+
+Acknowledgements
+----------------
+
+© 2011, Rico Sta. Cruz. Released under the [MIT 
+License](http://www.opensource.org/licenses/mit-license.php).
+
+Sinatra-AssetPack is authored and maintained by [Rico Sta. Cruz][rsc] with help 
+from it's [contributors][c]. It is sponsored by my startup, [Sinefunc, Inc][sf].
+
+ * [My website](http://ricostacruz.com) (ricostacruz.com)
+ * [Sinefunc, Inc.](http://sinefunc.com) (sinefunc.com)
+ * [Github](http://github.com/rstacruz) (@rstacruz)
+ * [Twitter](http://twitter.com/rstacruz) (@rstacruz)
+
+[rsc]: http://ricostacruz.com
+[c]:   http://github.com/rstacruz/sinatra-assetpack/contributors
+[sf]:  http://sinefunc.com