Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
generate css sprites automagically
Branch: minimagick

This branch is even with merbjedi:minimagick

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
rails
spec
tasks
.gitignore
MIT-LICENSE
README.md
Rakefile
VERSION
sprite.gemspec

README.md

sprite

sprite is a gem that helps generate css sprite images automagically. It's aim is to support all web frameworks (Merb/Rails/Sinatra), and have extensible output generator. By default, it supports CSS and SASS output (via mixins).

INSTALL

Install ImageMagick

sprite requires the ImageMagick command line tools. to install it, use

install it via macports:

sudo port install ImageMagick  

Install the sprite gem

Install the sprite gem from gemcutter

gem sources -a http://gemcutter.org
gem install sprite

if using Merb

With Merb 1.1 and Bundler, just add the line gem 'sprite' your ./Gemfile and then run gem bundle

if using Rails

add to environment.rb

config.gem "sprite"

or install as a plugin

script/plugin install git://github.com/gistinc/sprite.git

USAGE

if installed as a gem, at your root project folder you can just run

sprite

if you would rather not install the gem, you can also use it with rake

rake sprite:build

Intelligent Defaults

Without having to configure anything, sprite will allow you to easily generate sprites based on a couple default folder settings we give you right off the bat.

For example, given you have the following setup:

public/
  images/
    sprites/
      black-icons/
        stop.png
        go.png
        back.png
        forward.png

      weather/
        sunny.gif
        rainy.gif
        cloudy.gif

Running sprite with no configuration file will generate the following new files:

public/
  stylesheets/
    sprites.css
  images/
    sprites/
      black-icons.png
      weather.png

Any folders within public/images/sprites/ will get compressed into a merged image file at the same location. Then sprites.css will get generated in the stylesheets folder with all the class definitions for these files. Just add a link to sprites.css into your html and you're ready to go!

CONFIGURATION

Configuration of sprite is done via config/sprite.yml. It allows you to set sprite configuration options, and fine tune exactly which sprites get generated where.

  • config: section defines all the global properties for sprite generation. Such as how it generates the styles, where it looks for images, where it writes it output file to, and what image file format it uses by default

    • style: defines how the style rules are outputted. built in options are css, sass, and sass_mixin. (defaults to css)
    • style_output_path: defines the file path where your style settings get written (defaults to stylesheets/sprites). the file extension not needed as it will be set based on the style: setting
    • image_output_path: defines the folder path where the combined sprite images files are written (defaults to images/sprites/)
    • image_source_path: defines the folder where source image files are read from (defaults to images/)
    • public_path: defines the root folder where static assets live (defaults to public/)
    • sprites_class: defines the class name that gets added to all sprite stylesheet rules (defaults to sprites)
    • default_format: defines the default file image format of the generated files. (defaults to png)
    • class_separator: used to generated the class name by separating the image name and sprite name (defaults to -)
  • images: section provides an array of configurations which define which image files are built, and where they get their sprites from. each image setup provides the following config options:

    • name: name of image (required)
    • sources: defines a list of source image filenames to build the target image from (required). They are parsed by Dir.glob
    • align: defines the composite gravity type, horizontal or vertical. (defaults to vertical)
    • spaced_by: spacing (in pixels) between the combined images. (defaults to 0)
    • format: define what image file format gets created (optional, uses default_format setting if not set)

All image and style paths should be set relative to the public folder (which is configurable via public_path setting).

Sample Configuration config/sprite.yml

# defines the base configuration options (file paths, etc, default style, etc)

config:
  style: css
  style_output_path: sass/mixins/sprites.sass
  image_output_path: images/sprites/
  image_source_path: images/
  public_path: public/
  sprites_class: 'sprites'
  class_separator: '-'
  default_format: png

# defines what sprite collections get created
images:    

  # creates a public/images/sprites/blue_stars.png image with 4 sprites in it
  - name: blue_stars
    format: png
    align: horizontal
    spaced_by: 50
    sources:
      - icons/blue-stars/small.png
      - icons/blue-stars/medium.png
      - icons/blue-stars/large.png
      - icons/blue-stars/xlarge.png

  # creates a public/images/sprites/green-stars.jpg image with 
  # all the gif files contained within /images/icons/green-stars/
  - name: green_stars
    format: png
    align: vertical
    spaced_by: 50
    sources:
      - icons/green-stars/*.gif

Style Settings

By default, it will use with style: css and generate the file at public/stylesheets/sprites.css

.sprites.blue-stars-small {
  background: url('/images/icons/blue-stars/small.png') no-repeat 0px 0px;
  width: 12px;
  height: 6px;
}
.sprites.blue-stars-medium {
  background: url('/images/icons/blue-stars/medium.png') no-repeat 0px 6px;
  width: 30px;
  height: 15px;
}
.sprites.blue-stars-large {
  background: url('/images/icons/blue-stars/large.png') no-repeat 0px 21px;
  width: 60px;
  height: 30px;
}
.sprites.blue-stars-xlarge {
  background: url('/images/icons/blue-stars/xlarge.png') no-repeat 0px 96px;
  width: 100px;
  height: 75px;
}

We also support mixin syntax via style: sass_mixin. If set, sprite will only generate a yml with your specific sprite configurations. It then provides a SASS mixin which you can use in order to mix in these sprites anywhere within your SASS stylesheets.

// you can then use your sprite like this
.largebluestar
  +sprite("blue-stars", "large")

.mysmallbluestar
  +sprite("blue-stars", "small")

ABOUT sprite

sprite was originally based off of Richard Huang's excellent Rails plugin: css_sprite

Since then it's been rebuilt (with some reuse of the image generation code) to be a general purpose ruby executable, with hooks for merb/rails/sinatra

LICENSE

Released under the MIT License

COPYRIGHT

Copyright (c) 2009 Gist

Original Codebase Copyright (c) 2009 [Richard Huang]

Something went wrong with that request. Please try again.