# Sprikit (extend from [css-sprite](https://github.com/aslansky/css-sprite.git))

[![NPM version](https://badge.fury.io/js/sprikit.svg)](http://badge.fury.io/js/sprikit) 

> A css sprite generator.

> Generates sprites and proper css files out of a directory of images.

> Can inline base64 encoded sprites.

> Support mutil css unit: px, em, rem.

> Support scaling sprites, so you can apply at retina pattern by special "scale" param.

# Sprikit was extend from [css-sprite](https://github.com/aslansky/css-sprite.git), and add some feature for complex retina case.

## Requirements

Starting with `Sprikit` you shold do this:

## Install

Install with [npm](https://www.npmjs.com/package/sprikit)

```
npm install sprikit --save
```

If you want to use `sprikit` on your cli install with:

```
npm install sprikit -g
```

## Command Line Interface

```sh
Usage: sprikit -c "config.file.name.json"

  -c    config file location
```

Config Options:
```javascript
{
    // path of directory to write sprite file to
    "out":"./app/res",
    // glob strings to find source images to put into the sprite
    "src":"./app/res/res/icons",
    // create css with base64 encoded sprite (css file will be written to <out>)
    "base64":true,
    // http path to images on the web server (relative to css path or absolute path)
    "cssPath":"../res",
    // output format of the sprite (png or jpg)
    "format":"png",
    // name of sprite file without file extension
    "name":"sprite",
    // output format of the css. one of css, less, sass, scss or stylus
    "processor":"css",
    // output template file, overrides processor option
    "template":"",
    // file to write css to, if omitted no css is written
    "style":"",
    // coordinate system scale param
    "scale":"",
    // generate with such unit,for case of "px", "em", "rem"
    "unit":"px",
    // background color of the sprite in hex
    "background":"#FFFFFF",
    // appends a "cache buster" to the background image in the form "?<...>" (random)
    "cachebuster":false,
    // margin in px between tiles
    "margin":4,
    // Interpolation algorithm used when scaling retina images (nearest-neighbor|moving-average|linear|grid|cubic|lanczos)
    "interpolation":"grid",
    // background opacity of the sprite. defaults to 0 when png or 100 when jpg
    "opacity":0,
    // orientation of the sprite image (vertical|horizontal|binary-tree)
    "orientation":"vertical",
    // prefix for the class name used in css (without .)
    "prefix":"",
    // disable sorting of layout'
    "no-sort":""
}
```

## Programatic usage
```
var sprite = require('sprikit');
sprite.create(options, cb);
```

### Options
Just the same with config options

### Example
```js
var sprite = require('css-sprite');
sprite.create({
  src: ['./src/img/*.png'],
  out: './dist/img'
  name: 'sprites',
  style: './dist/scss/_sprites.scss',
  cssPath: '../img',
  processor: 'scss'
}, function () {
  console.log('done');
});
```

## Usage with [Gulp](http://gulpjs.com)
```js
var gulp = require('gulp');
var gulpif = require('gulp-if');
var sprite = require('sprikit').stream;

// generate sprite.png and _sprite.scss
gulp.task('sprites', function () {
  return gulp.src('./src/img/*.png')
    .pipe(sprite({
      name: 'sprite',
      style: '_sprite.scss',
      cssPath: './img',
      processor: 'scss'
    }))
    .pipe(gulpif('*.png', gulp.dest('./dist/img/'), gulp.dest('./dist/scss/')))
});
// generate scss with base64 encoded images
gulp.task('base64', function () {
  return gulp.src('./src/img/*.png')
    .pipe(sprite({
      base64: true,
      style: '_base64.scss',
      processor: 'scss'
    }))
    .pipe(gulp.dest('./dist/scss/'));
});
```

Options to use `sprikit` with [Gulp](http://gulpjs.com) are the same as for the `sprite.create` function with the exception of `src` and `out`.

## Usage with [Grunt](http://gruntjs.com)

Add `sprikit` as a dependency to your grunt project and then use something like this in your `gruntfile.js`:

```js
module.exports = function(grunt) {

  // Project configuration.
  grunt.initConfig({
    css_sprite: {
      options: {
        'cssPath': '../images',
        'processor': 'css',
        'orientation': 'vertical',
        'margin': 4
      },
      sprite: {
        options: {
          'style': 'dest/css/sprite.css'
        },
        src: ['src/images/*', 'src/images2/*'],
        dest: 'dest/images/sprite.png',
      },
      base64: {
        options: {
          'base64': true
        },
        src: ['src/images/*'],
        dest: 'dest/scss/base64.css',
      }
    }
  });

  // Load the plugin that provides the "sprikit" task.
  grunt.loadNpmTasks('sprikit');

  // Default task(s).
  grunt.registerTask('default', ['css_sprite']);
};
```

Options to use `sprikit` with [Grunt](http://gruntjs.com) are the same as for the `sprite.create` function with the exception of `src` and `out`.


## Usage with [sass](http://sass-lang.com/) / [less](http://lesscss.org/) / [stylus](http://learnboost.github.io/stylus/)

#### [scss](http://sass-lang.com/) example

```scss
@import 'sprite'; // the generated style file (sprite.scss)
```

#### [sass](http://sass-lang.com/) example

```sass
@import 'sprite' // the generated style file (sprite.sass)

// camera icon (camera.png in src directory)
.icon-camera
  +sprite($camera)

// cart icon (cart.png in src directory)
.icon-cart
  +sprite($cart)
```

#### [less](http://lesscss.org/) example

```less
@import 'sprite'; // the generated style file (sprite.less)
```

#### [stylus](http://learnboost.github.io/stylus/) example

```stylus
@import 'sprite' // the generated style file (sprite.styl)

// camera icon (camera.png in src directory)
.icon-camera
  sprite($camera)

// cart icon (cart.png in src directory)
.icon-cart
  sprite($cart)
```

## Using your own template

To use your own [mustache](http://mustache.github.io/) template for style file creation pass in the -t option followed by the template path. The following variables are available in the mustache template:

* **items** -- array of objects with the sprite tiles
  * **name** -- name of the tile
  * **x** -- x position
  * **y** -- y position
  * **width**
  * **height**
  * **offset_x** -- x offset within the sprite
  * **offset_y** -- y offset within the sprite
  * **class** -- class name of the tile
  * **px** -- object with pixel values instead of raw data (e.g width: '250px')
      * **x**, **y**, **offset_x**, **offset_y**, **height**, **width**, **total_height**, **total_width**
* **total_width** -- total sprite image width
* **total_height** -- total sprite image height
* **escaped_image** -- sprite image path

Please have a look at the [included templates](https://github.com/vanmess/sprikit/tree/master/lib/templates) to see how they work.