css_sprite

automatically css sprite.

---

Best Practices

I have written posts “css sprite best practices” to introduce the idea that the css_sprite gem follows.
english version
chinese version

otaviofcs wrote a brazilian version to introduce the css_sprite gem, check it here: http://blog.riopro.com.br/2010/04/22/acabaram-as-desculpas-para-nao-usar-css-sprite-na-sua-aplicacao/
and he also build a demo, http://github.com/riopro/css_sprite_demo

---

What css_sprite does?

css sprite generates css_sprite image and css files automatically for you follow the conventions as follows.

images under css_sprite directory	class name in css_sprite css
twitter_icon.png	.twitter_icon
facebook_icon.png	.facebook_icon
hotmail-logo.png	.hotmail-logo
gmail-logo.png	.gmail-logo
icons/twitter_icon.png	.icons .twitter_icon
widget/icons/twitter_icon.png	.widget .icons .twitter_icon
twitter_icon_hover.png	.twitter_icon:hover
twitter-icon-hover.png	.twitter-icon:hover
logos_hover/gmail_logo.png	.logos:hover .gmail_logo
logos-hover/gmail-logo.png	.logos:hover .gmail-logo
gmail_logo_active.png	.gmail_logo.active
gmail-logo-active.png	.gmail-logo.active
logos_active/gmail_logo.png	.logos.active .gmail_logo
logos-active/gmail-logo.png	.logos.active .gmail-logo

css_sprite directory is the directory whose name is “css_sprite” or “css_sprite” suffixed under public/images directory.
css_sprite image is the image file automatically generated under public/images directory.
css_sprite css is the css file automatically generated under public/stylesheets directory.

---

Install

css_sprite depends on the rmagick gem, please make sure RMagick is successfully installed on your system.
css_sprite also depends on the optipng tool as default image optimization, but you can use any other image optimization tool, check the Configuration section. If you use the default optipng tool, please make sure it is successfully installed on your system.

install css_sprite as a gem:

sudo gem install css_sprite

or install css_sprite as a plugin:

script/plugin install git://github.com/flyerhzm/css_sprite.git

---

Usage

1. create a directory whose name is css_sprite or ends with css_sprite (e.g. widget_css_sprite) under public/images directory

2. if you install the css_sprite as a gem, you should add css_sprite task in Rakefile

require 'css_sprite'

If you install it as a plugin, you can skip this step
If you use rails3, you can skip this step too

2. define config/css_sprite.yml, it is not necessary by default.

3. start css_sprite server

rake css_sprite:start

4. put any images which you need to do the css sprite under the css_sprite directory, then you will see the automatically generated css sprite image and css files.

5. include the stylesheet in your view page

<%= stylesheet_link_tag 'css_sprite' %>

You can stop the css_sprite server by rake css_sprite:stop

You can restart the css_sprite server by rake css_sprite:start

Or you can just do the css sprite manually by rake css_sprite:build

---

Configuration

There is no need to create any configuration by default. If you want some customizations as follows, you need to define config/css_sprite.yml file.

Example for rails 3.1

engine: css.scss
image_path: app/assets/images
stylesheet_path: app/assets/stylesheets
css_images_path: assets
disable_optimization: true

ImageType

css_sprite uses RMagick to compose the images by default. It uses PaletteMatteType as default image_type, you can change it to any image_type which RMagick supports.

image_type: PaletteType

Check the detailed information of image_type here: http://www.imagemagick.org/RMagick/doc/constants.html#ImageType

Destination Image Format

css_sprite saves the css sprite image as a png file by default. You can change it to gif or any other format like

image_type: TrueColorMatteType
format: GIF

Sass

css_sprite generates css file by default. If you like sass, you can just add following line in the configuration file.

engine:sass

Image Optimization

css_sprite uses optipng with optimization level 2 to optimize the auto generated css_sprite image by default. You can change it to any image optimization command.

optimization: optipng -o 7

You can also disable the image optimization by

disable_optimization: true

Customization styles

• For css
  

  
  suffix:
    button: |
      text-indent: -9999px;
      display: block;
      cursor: pointer;
      font-size: 0;
      line-height: 15px;
      border: 0;
      outline: 0;
    icon: |
      text-indent: -9999px;
      cursor: pointer;
  

• For sass
  

  
  engine: sass
  suffix:
    button: |
      text-indent: -9999px
      display: block
      cursor: pointer
      font-size: 0
      line-height: 15px
      border: 0
      outline: 0
    icon: |
      text-indent: -9999px
      cursor: pointer
  

engine defines css (default) or sass file to generate.
suffix defines the customization styles for specified images.
The customization above means if your image filename is button suffixed (e.g. post_button.png), the corresponding class .post_button has the additional style with (outline: 0; border: 0; and so on),
if your image filename is icon suffixed (e.g. twitter_icon.png), the correspondiing class .twitter_icon has the additional style with (text-indent: -9999px; cursor: pointer)

Customization directories

css_sprite follows the conventions that images are under public/images directory and css files are under public/stylesheets, but you can change them.

image_path: app/images
stylesheet_path: app/stylesheets

By default, image_path is public/images and stylesheet_path is public/stylesheets.

Compass support (SCSS)

You can use the following configuration to support compass.

engine: scss
stylesheet_path: app/stylesheets

---

Copyright © 2009 – 2012 [Richard Huang (flyerhzm@gmail.com)], released under the MIT license