Well. Spriting. Do you know what it is? While I’ve included a very brief summary, you may want to just skip that part if you already know about it, or find a better description of the technique. Also, while this article is specifically aimed at SproutCore, the concepts (and the script download) can easily be applied elsewhere.

Well, here are your options:

1. Read the whole article. Could be amusing, if I’m having a bad writing day.
2. Skip to the download and “how to use.” No, I’m not going to explain the code. Well, not here, at any rate. I’ll explain it in the code itself. Yes, of course there are comments.

What is Spriting?

Example Sprited Images

The goal of spriting is to reduce the effect of latency on your web app’s performance.

To your left is an example set of sprited images.

Using a Script

You may thing that combining several images into one larger image might be a bit time-consuming and, overall, a tad challenging, especially if you are often updating the individual images.

You are not alone. I feel the same way.

However, I do know a little about writing scripts—even if I’d like to know a lot more; I’m still only learning Python. So, there is a simple answer:

Write a darn script!

The Product

If you just want the script and how to use it, you’re in luck. Because there are, in fact, some comments in the script, I’ll leave the explanation of how the code works for there.

You can download the code from GitHub.

The script is written in Python. It requires: Either: Python 2.6+ or Python 2.5 with simplejson installed PIL (Python Imaging Library)

Very briefly, here is what it does:

• Takes a “sets” folder, which should have sub-folder sets of icons to be sprited.
• Takes an output folder, under which it will create new set folders containing CSS and image files.
• Combines images under a maximum size (128×128 by default—see Configuration) into a sprites.png file in the output set folder.
• Creates CSS referencing these images using a URL template (SproutCore oriented at first—see URL)

Sets

You often might have more than one set of icons. For instance, you could have a main set, and then an alternate set that you only want to load on demand. You still want that additional set to be sprited.

Or, perhaps, you may have images meant for repeating backgrounds, but that you still want to sprite.

To facilitate this, the spriting script takes, as its first argument, the location to a sets folder. You put your sets as subfolders into this folder. For instance, this could be your folder layout:

my-sets
	common
		delete-32.png
		delete-64.png
		refresh-32.png
		refresh-64.png
		refresh-512.png
	repeat-x
		config.js       — see Configuration
		toolbar.png
		footer.png
		header.png
	odd-feature
		some-icon.png
		other-icon.png

URLs

The CSS has to reference the images. Only problem: it doesn’t know where those images are.

Usually, you’d just be able to use paths relative to the StyleSheet. However, if you are using SproutCore, this won’t work because it moves around all the CSS and JavaScript.

With SproutCore, you need something more like:

static_url('images/set/sprites.png')

This is what the script does by default. Just like above. It uses a URL template of

static_url('images/{set}/{image}')

It is a string which will be passed through the Python format function, with set and image as arguments.

Configuration

There are a few things that are configurable. Configuration is done per-set.

Configuration files are JSON files, and are very simple. They are optional, and take at most four parameters:

• max-size: Default: 128.
  The maximum size for sprited images. Images above this size will be put as separate images. Useful if you have some really high-res icons you don’t want to sprite, but want to keep with the set.

• repeat: Default: “none”; can also be “x” or “y”.
  Determines the repeat mode. If repeat is “x,” the sprites will be laid out in rows; if “y,” the sprites will be laid out in columns. The generated CSS will include repeat-x or repeat-y, respectively.

Note that all images in a repeat-x set must be the same width, and all images in a repeat-y set must be the same height. The width or height of these images should be set using repeat-width and repeat height, which are discussed below.

• repeat-width: Default: 32.
  If repeat=“x,” the width of the repeat images. If your repetition does not require a pattern, you could set this to 1.

• repeat-height: See that lovely summary of repeat-width above? Well, this is the same, but for y/height.

The CSS

As you may know, SproutCore automatically includes any CSS files. So, since this generates CSS files (and, if you provide the right argument, puts them directly into a SproutCore-watched folder), the CSS is automatically added. So, how do you use it?

Very simply. The script generates CSS rules in this format:

.set-name .icon-name.icon, .set-name .icon-name.icon { /* CSS */ }

For example, to show “refresh-64″ icon in set “common”, you’d do something like this:

ImageView.design({
  layout: { left: 100, top: 100, width: 64, height: 64 },
  value: "common refresh-64 icon" // using SproutCore's built-in className support for spriting
}

Or, as you may have noticed from the rule above, you can accomplish some basic theming very easily by treating set names as themes:

View.design({
  layout: {left: 100, top:100, width:256, height: 256},
  classNames: ["common"], // the theme
  childViews: ["styledView"],
  styledView: ImageView.design({
    layout: { left: 100, top: 100, width: 64, height: 64 },
    value: "refresh-64 icon" // using SproutCore's built-in className support for spriting
  })
})

Nice and simple, eh?