Sprite Factory 1.4.1 and the Rails asset pipeline

Sat, Aug 6, 2011

I have updated the sprite-factory gem to v1.4.1.

This version adds improved support for the upcoming Rails 3.1 asset pipeline.

You can find the instructions on github, but I want to flesh them out a little bit here and show how I installed Rails 3.1 and added sprite-factory support to an empty Rails application.

Installing Rails 3.1

How to install rails 3.1 has already been covered well by others:

To summarize: use rvm to create a new gemset, update rake, install rails and create a new application:

$ rvm use 1.9.2@sprite-factory-and-rails31 --create --default
$ gem update rake
$ gem install rails --pre
$ rails new sprite-factory-and-rails31

For linux/ubuntu you also need to add a missing gem to the Gemfile to ensure a javascript runtime is available

  gem 'therubyracer', '>= 0.8.2'

Ensure all your gems are installed, migrate the database and run the server

$ bundle install
$ bundle exec rake db:migrate
$ rails server thin

Add sprite-factory to your Gemfile

Plus its image library dependency (either rmagick or chunkypng)

group :assets do
  ...
  gem 'sprite-factory', '>= 1.4.1'
  gem 'chunky_png'
end

Store sprite images in app/assets/images sub-folders

E.g

app/assets/images/avatars/*.png
app/assets/images/icons/*.png
...

Create a Rake task for regenerating your sprites

E.g. in lib/tasks/assets.rake

namespace :assets do

 desc 'recreate sprite images and css'
 task :resprite => :environment do 
   
   require 'sprite_factory'

   # YOUR options here      
   SpriteFactory.report  = true                         # output report during generation
   SpriteFactory.library = :chunkypng                   # use simple chunkypng gem to handle .png sprite generation
   SpriteFactory.layout  = :packed                      # pack sprite sheets into optimized rectangles
   SpriteFactory.csspath = "<%%= asset_path '$IMAGE' %>" # embed ERB into css file to be evaluated by asset pipeline

   # YOUR sprite config here
   SpriteFactory.run!('app/assets/images/avatars', :output_style => 'app/assets/stylesheets/avatars.css.erb')
   SpriteFactory.run!('app/assets/images/icons',   :output_style => 'app/assets/stylesheets/icons.css.erb',  :selector => 'img.icon_')
 
 end

end

NOTE: the :csspath option embeds erb into the generated css file to allow Rails to provide the correct path to the images, along with cache-busting version numbers.

NOTE: the :output_style option is used to override the default behavior and instead of generating the css file alongside the image, it saves it in the app/assets/stylesheets folder so that it will automatically get picked up by the rails asset pipeline. It is also given a .erb extension to tell the asset pipeline to process with ERB in order to evaluate the #asset_path calls.

Show some sprites

Add a helper method to application_helper.rb

def sprite_tag(klass, options = {})
  image_tag('s.gif', {:class => klass, :alt => klass}.merge(options))
end

Somewhere in a view, lets show a sprite:

<%= sprite_tag('icon_email') %>

GO!

Run your rake task

bundle exec rake assets:resprite

Generates

sprite images in app/assets/images
sprite styles in app/assets/stylesheets - automatically picked up by the asset pipeline and included in your generated application.css

View your page in a browser

You can find the code here and a working example here