README.md in active_assets-0.3.1 vs README.md in active_assets-1.0.0.rc1

- old
+ new

@@ -1,24 +1,18 @@ Active Assets ============= -A gem that provides an asset management system for css, javascript, and sprites in your Rails applications and engines. ActiveAssets includes two libraries, ActiveExpansions and ActiveSprites. ActiveSprites generates sprites defined by a dsl similar to a route definition. Similarly, ActiveExpansions' dsl creates `ActionView::Helpers::AssetTagHelper` javascript and stylesheet expansions, and adds additional features: +A Railtie that provides an asset management system for css, javascript, and sprites in your Rails applications and engines. ActiveAssets includes two libraries, ActiveExpansions and ActiveSprites. ActiveSprites generates sprites defined by a dsl similar to a route definition. Similarly, ActiveExpansions' dsl creates `ActionView::Helpers::AssetTagHelper` javascript and stylesheet expansions, and adds additional features: * Concatenation of included assets for expansions at boot or deploy time. * Support for environment specific assets, so that, say, you can use one file for development and another for production or one file for development and then a cdn resource for production. -Installation -============ +Gemfile +------- - gem install active_assets -v 0.3.0 - -Using Bundler? --------------- -### Gemfile - ... - gem 'active_assets', '~> 0.3.0' + gem 'active_assets' ... group :development do ... gem 'rmagick' ... OR ... @@ -30,19 +24,33 @@ end ... The above order of image libraries is also the load order precedence. -Run the generator +In your Rails app ----------------- +### application.rb - script/generate active_assets + ... + require 'rails/all' + require 'active_assets/railtie' + ... -The DSLs -======== -## Introduction to Active Sprites +#### You can also include only ActiveSprites or only ActiveExpansions in your application +### application.rb +Instead of the above, + ... + require 'rails/all' + require 'active_assets/active_expansions/railtie' + ... OR ... + require 'active_assets/active_sprites/railtie' + ... + +## The DSLs +### Introduction to Active Sprites + ActiveSprites allows you to generate sprites within your Rails apps with `rake sprites`! All you need is `rmagick`, `chunky_png`, or `mini_magick` and you are on your way. Store the images that make up your sprites within your Rails project, use the dsl below to inform ActiveSprites of which images to include in your sprites as well as the css selector corresponding to each image, the location to write the sprite, and the location to write the stylesheet. A basic example ... #### config/sprites.rb @@ -87,13 +95,13 @@ ... config.active_sprites.sprite_backend = :chunky_png ... -## Introduction to Active Expansions +### Introduction to Active Expansions -ActiveExpansions allow you to register Rails javascript and stylesheet expansions via a simple dsl. Additionally, the assets in the expansion are concatenated when appropriate and the expansion delivers the concatenated (or 'cached') assets' path in the appropriate environments. Also, files can be specified as deploy only or only for a specific environment. For example, you may wish to include jQuery or Prototype src files in development and use minified libraries from cdn sources in production. This is supported. +ActiveExpansions allow you to register Rails javascript and stylesheet expansions via a simple dsl. Addionally, the assets in the expansion are concatenated when appropriate and the expansion delivers the concatenated (or 'cached') assets' path in the appropriate environments. Also, files can be specified as deploy only or only for a specific environment. For example, you may wish to include jQuery or Prototype src files in development and use minified libraries from cdn sources in production. This is supported. * Below demonstration shows several variations on how to declare expansions. Note that these declaration are redundant to demonstrate how to accomplish the same thing in different ways. * Alternatively you can also register your assets in multiple files. Simply omit `config/asets.rb` and add as many .rb files as you like inside a directory `config/assets` * Note the `register` is optional `Rails.application.expansions do` will work the same way @@ -179,14 +187,18 @@ end end `_` and `a` are aliases for `asset` -#### ActiveExpansions caching -By default, ActiveExpansions will not cache your assets automatically. This is because if you are not serving assets from the same server as where your application resides, then you most likely want to cache your assets at deploy time (on the front-end servers). To cache assets, add the following to an initializer to concat assets at boot time or to your deploy scripts if you wish to do it when deploying: +#### ActiveExpansions configuration and deployment +By default, ActiveExpansions will not cache your assets even if `ActionController.perform_caching` is enabled. This is because if you are not serving assets from the same server as where your application resides, then you most likely want to cache your assets at deploy time (on the front-end servers). To cache assets manually, Rails.application.expansions.javascripts.cache! Rails.application.expansions.stylesheets.cache! -Contributing -============ -You know the drill! +To enable your application to cache assets when the application is initialized, i.e. boot time, follow this example, + +##### config/environments/production.rb + + ... + config.active_expansions.precache_assets = true + ...