# node-sprite
A CSS Sprite Generation Library with Stylus and Retina Support.

## Requirements
It uses **ImageMagick** for its graphics operations. So make sure you have the `convert` and `identify` command available in your envirnoment.

## Usage

`node-sprite` exports three functions: `sprite`, `sprites` and `stylus`. The following examples show how to use them.

### Example Directory Stucture

```
- app.js
- images/
  - global/
    - bar.jpg     // 200x100px image
    - foo.png     // 10x50px   image
  - animals/
    - cat.gif     // 64x64px   image
    - duck.png    // 64x64px   image
    - mouse.gif   // 64x64px   image
```

## Single Sprite

```javascript
var sprite = require('node-sprite');

sprite.sprite('global', {path: './images'}, function(err, globalSprite) {
  console.log(globalSprite.filename())
  console.log('foo', globalSprite.image('foo'));
  console.log('bar', globalSprite.image('bar'));
});
```

This code will generate a sprite image named `./images/global-[checksum].png` and output the following:

    global-45c81.png
    foo, {width: 200, height: 100, positionX: 0, positionY: 52}
    bar, {width: 64, height: 64, positionX: 0, positionY: 0}

## Multiple Sprites

```javascript
var sprite = require('node-sprite');

sprite.sprites({path: './images'}, function(err, result) {
  var globalSprite = result['global'];
  var animalsSprite = result['animals'];
  console.log(globalSprite.filename());
  console.log(animalsSprite.filename());
  console.log('animals/duck', animalsSprite.image('duck'));
});
```

This code will generate a sprite image for every subfolder of `./images`. The images are named `./images/[folder]-[checksum].png`.

    global-45c81.png
    animals-b775d.png
    animals/duck, {width: 10, height: 50, positionX: 0, positionY: 66}

## Stylus Integration

```
// screen.styl
#duck
  sprite animal duck
#mouse
  sprite global mouse false
```

The `sprite` function generates the correct `background` image and position for the specified image. By default it also adds `width` and `height` properties. You can prevent this behaviour by setting the third optional parameter to `false`.

```css
/* screen.css */
#duck {
  background: url('./images/animals-b775d.png') 0px -66px;
  width: 64px;
  height: 64px;
}
#mouse {
  background: url('./images/animals-b775d.png') 0px -132px;
}
```

The `sprite.stylus` function behaves similar to `sprite.sprites`, but it returns a helper object, with provides a stylus helper function `helper.fn`.

```javascript
var sprite = require('node-sprite');
var stylus = require('stylus');

var str = require("fs").readFileSync("screen.styl")

sprite.stylus({path: './images'}, function (err, helper) {
  stylus(str)
    .set('filename', 'screen.styl')
    .define('sprite', helper.fn)
    .render(function (err, css) {
      console.log(css);
    });
});
```

## Retina / High Resolution Sprite Support

node-sprite has a special mode for high resolution sprites. When your sprite folder ends with `-2x` it will be treated differently.

### Basic Example

    animals-2x/
    - cat.gif    // 128x128px image
    - duck.png   // 128x128px image

Although we have 128x128px images. The elements should only have the size of 64x64px and the background has to be scaled down.

```
// screen.styl
#duck
  sprite(animal-2x, duck)
  background-size sprite-dimensions(animal-2x, name)
```

will be transformed to

```css
/* screen.css */
#duck {
  background: url('./images/animals-2x-c575d.png') 0px -66px;
  width: 64px;
  height: 64px;
  background-size: 64px 194px;
}
```

For this to work you have to add the `sprite-dimensions` helper in you stylus configuration:

`.define('sprite-dimensions', helper.dimensionsFn)`

### Retina Mixin

If you want to have a retina and a non-retina sprite it makes sense to create a mixin like this one:

```
// screen.styl
retina-sprite(folder, name)
  sprite(folder, name)
  hidpi = s("(min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 1.5dppx)");
  @media hidpi
    sprite(folder+"-2x", name, false)
    background-size sprite-dimensions(folder+"-2x", name)

#duck
  retina-sprite animals duck
```

This will generate the following css code:

```css
#duck {
  background: url('./images/animals-b775d.png') 0px -66px;
  width: 64px;
  height: 64px;
}
@media (min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (-webkit-min-device-pixel-ratio: 1.5), (min-resolution: 1.5dppx) {
  #duck {
    background: url('./images/animals-2x-c575d.png') 0px -66px;
    background-size: 64px 194px;
  }
}
```

*Note: All images in the retina folder should have even height and width pixels.*

## Options

All three functions accept an optional options parameter.

```javascript
{
  path: './images',     // sprite directory
  padding: 2,           // pixels between images
  httpPath: './images', // used be the stylus helper
  watch: false,         // auto update sprite in background
  retina: '-2x'         // postfix for retina sprite folders
}
```

## Auto Update on Image Change

If you pass `watch: true` as an option node-sprite will watch the sprite folders and regenerate the sprite when something changes.

You can subscribe to the `update` event of the `sprite` or `helper` object to get notified.

```javascript
var generateCss = function () {...};

sprite.stylus({watch: true}, function (err, helper) {
  generateCss();
  helper.on("update", generateCss);
});
```

## Structural Sprite Information / JSON

node-sprite will put a `./images/[folder].json` next to every generated sprite image. This file contains structural information of the generated sprite. This files can be used by other modules or applications.

They are also usefull if you running your application on a production machine without ImageMagick. In this case node-sprite will fallback to this data.

```javascript
{
  "name": "animals",
  "checksum": "b775d6fa89ad809d7700c32b491c50f0",
  "shortsum": "b775d",
  "images": [
    {
      "name": "cat",
      "filename": "cat.gif",
      "checksum": "25ce6895f8ed03aa127123430997bbdf",
      "width": 64,
      "height": 64,
      "positionX": 0,
      "positionY": 0
    },
    ...
  ]
}
```

## License
The MIT License