sprites.markdown

Sprites

Project Structure

images_dir/
  sprites/
    toolbar/
      new.png
      save.png
      open.png
      undo.png

Low Level API

There are four custom functions that would be exposed via compass into both sass & scss:

• sprite-image-url - generates a url to a sprite image asset. adheres to all the logic that compass's image-url helper does (asset hosts, cache busting)
• sprite-image-data - like sprite-image-url, but it generates a data url eliminating another round-trip to the server.
• sprite-image - generates output suitable for using with the CSS background property. This is a concatenation of calling sprite-image-url and sprite-position
• sprite-width - returns the width, in pixels, of the original image file that got sprited.
• sprite-height - returns the height, in pixels, of the original image file that got sprited.
• sprite-position - returns the offsets for background positioning

Usage Example of these functions:

.toolbar-base {
  background-image: sprite-image-url("toolbar");
  /* -or- use a data url */
  background-image: sprite-image-data("toolbar");
}
#toolbar {
  .new {
    @extend .toolbar-base;
    width: sprite-width("toolbar/new");
    height: sprite-height("toolbar/new");
    background-position: sprite-position("toolbar/new");
    background-repeat: no-repeat;
  }
  .save {
    @extend .toolbar-base;
    width: sprite-width("toolbar/save");
    height: sprite-height("toolbar/save");
    background-position: sprite-position("toolbar/save");
  }
}

Standard Usage

To make sprites even easier to use, compass will provide a magic import on the load path for sprites.

Magic import

@import "sprites/toolbar";

Imports an on-the-fly generated scss file that looks like this:

/* The user can change the base class if they feel strongly about it */
$toolbar-sprite-base-class : ".toolbar-sprite" !default;

/* Whether the toolbar sprite mixins should include dimensions */
$toolbar-sprite-dimensions: false;

/* Configurable spacing around the sprites */
/* Set the spacing around them all with one variable */
$toolbar-spacing: 0px !default;
/* Additionally, you can specify the spacing individually */
$toolbar-new-spacing: $toolbar-spacing !default;
$toolbar-save-spacing: $toolbar-spacing !default;
$toolbar-open-spacing: $toolbar-spacing !default;
$toolbar-undo-spacing: $toolbar-spacing !default;

$all-toolbar-spacings: $toolbar-new-spacing $toolbar-save-spacing $toolbar-open-spacing $toolbar-undo-spacing;

/* They can set this to true if they want the sprite to be inlined. */
$toolbar-sprite-inline : false !default;

/* establish the base class for them */
#{$toolbar-sprite-base-class} {
  @if $toolbar-sprite-inline {
    background: sprite-image-data("toolbar", $toolbar-spacing);
  }
  @else {
    background-image: sprite-image-url("toolbar", $toolbar-spacing);
  }
  background-repeat: no-repeat;
}

/* XXX Open Question: should this api make the user pass in the image extension? */

/* Generates the contents of a sprite sub class */
@mixin toolbar-sprite-dimensions($sprite) {
  width: sprite-width("toolbar/#{$sprite}");
  height: sprite-height("toolbar/#{$sprite}");
}

@mixin toolbar-sprite-position($sprite) {
  background-position: sprite-position("toolbar/#{$sprite}");  
}

/* Emits one sprite.
   $sprite: the name of the image that got sprited. E.g. "foo"
*/
@mixin toolbar-sprite($sprite, $dimensions: $toolbar-sprite-dimensions) {
  @extend #{$toolbar-sprite-base-class};
  @include toolbar-sprite-position($sprite);
  @if $dimensions {
    @include toolbar-sprite-dimensions($sprite);
  }
}

/* Generate 1 class per sprite */
@mixin all-toolbar-sprites {
  .toolbar-new  { @include toolbar-sprite("new");  }
  .toolbar-save { @include toolbar-sprite("save"); }
  .toolbar-open { @include toolbar-sprite("open"); }
  .toolbar-undo { @include toolbar-sprite("undo"); }
}

This makes it drop-dead easy to use and access sprites in your stylesheets.

Most Basic Usage

@import "sprites/toolbar";
@include all-toolbar-sprites;

Generates:

.toolbar-sprite, .toolbar-new, .toolbar-save,
.toolbar-open, .toolbar-undo {
  background-image: url(/images/toolbar.png);
  background-repeat: no-repeat;
}
.toolbar-new { background-position: 0 0; }
.toolbar-save { background-position: 25px 0; }
.toolbar-open { background-position: 50px 0; }
.toolbar-undo { background-position: 75px 0; }

Conventional Usage

@import "sprites/toolbar";
#toolbar {
  .new  { @include toolbar-sprite("new");  }
  .open { @include toolbar-sprite("open"); }
  .save { @include toolbar-sprite("save"); }
  .undo { @include toolbar-sprite("undo"); }
}

Generates:

.toolbar-sprite,
#toolbar .new,
#toolbar .open,
#toolbar .save,
#toolbar .undo {
  background-image: url(/images/toolbar.png);
  background-repeat: no-repeat;
}

#toolbar .new { background-position: 0 0; }
#toolbar .open { background-position: 50px 0; }
#toolbar .save { background-position: 25px 0; }
#toolbar .undo { background-position: 75px 0; }

Advanced Usage

However the API presented allows even more flexibility than these examples. For instance if you want widths and spacing applied, you could do this instead:

$toolbar-sprite-base-class: ".tb-sprite";
$toolbar-sprite-dimensions: true;
$toolbar-spacing: 10px;
@import "sprites/toolbar";
#toolbar {
  .new  { @include toolbar-sprite("new");  }
  .open { @include toolbar-sprite("open"); }
  .save { @include toolbar-sprite("save"); }
  .undo { @include toolbar-sprite("undo"); }
}

Generates:

.toolbar-sprite,
#toolbar .new,
#toolbar .open,
#toolbar .save,
#toolbar .undo {
  background-image: url(/images/toolbar.png);
  background-repeat: no-repeat;
}

#toolbar .new { background-position: 0 0; width: 35px; height: 35px; }
#toolbar .save { background-position: 35px 0; width: 35px; height: 35px; }
#toolbar .open { background-position: 70px 0; width: 35px; height: 35px; }
#toolbar .undo { background-position: 105px 0; width: 35px; height: 35px;}