grunt-spritesmith-hd/README.md

Uses grunt-spritesmith along with some image-manipulation and SCSS-trickery to generate HD-compatible sprites and corresponding SCSS stylesheets.

# grunt-spritesmith-hd

> Uses [grunt-spritesmith](https://github.com/Ensighten/grunt-spritesmith) along with some image-manipulation and SCSS-trickery to generate HD-compatible sprites and corresponding SCSS stylesheets.

## Requirements

[grunt-spritesmith](https://github.com/Ensighten/grunt-spritesmith) — allows for a variety of spriting engines ([check out its requirements](https://github.com/Ensighten/grunt-spritesmith#requirements)).

grunt-spritesmith-hd, though, is more restricted. It uses [GraphicsMagick for Node](http://aheckmann.github.io/gm/) for image processessing, and that **requires that you already have either GraphicsMagick or ImageMagick installed.** *(Note that if you have installed ImageMagick and not GraphicsMagick, you need to specify this in the [`resizeEngine` setting](#resizeengine).)*

## Installation

This plugin requires Grunt `~0.4.0`

If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

```js
npm install grunt-spritesmith-hd --save-dev
```

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

```js
grunt.loadNpmTasks('grunt-spritesmith-hd');
```

## SpriteHD Task

*Run this task with the `grunt spriteHD` command.*

First, [have a look at the configuration options available for grunt-spritesmith](https://github.com/Ensighten/grunt-spritesmith#usage). Most of those relate to grunt-spritesmith-hd — except `cssFormat` and `cssTemplate`, since this plugin relies special SCSS.

*(If you would like grunt-spritesmith-hd to be more flexible, please contribute!)*

Unlike the original grunt-spritesmith, this plugin utilizes [Grunt's `options`](http://gruntjs.com/api/grunt.option), so you can pass the same options to multiple targets.

### Required Parameters

The following parameters must be defined for every target.

#### src

Type: `String | Array`

The assets that will be aggregated into your sprite.

#### spriteName

Type: `String`

A name that will designate your sprite's files.

For example, if you were to provide the `spriteName` "genuflect",  your sprite images would end up as `hd-genuflect.png` and `ld-genuflect.png` and your stylesheets would be `_sprite-genuflect.scss` and `_sprite-genuflect-hd.scss`.

### Options

As with other Grunt tasks, these options can be task-wide or target-specific.

*All of these options are optional*, because they all either have default values or can be ignored.

#### hd
Type: `Boolean`
Default: `true`

Do you want your spritesheet high-def-ready? Are your sprite assets 2x the size that they will appear?

Set to `false` if your sprite assets aren't up for it.

If `hd` is `false`, grunt-spritesmith-hd will simply run grunt-spritesmith with the parameters and options you've passed.

#### destImg
Type: `String`
Default: `images/sprites`

A directory where your generated sprite image(s) will go.

#### destCSS
Type: `String`
Default: `style/scss/sprites`

A directory where your generated SCSS file(s) will go.

#### hdPrefix
Type: `String`
Default: `hd`

A prefix for your high-def sprite files.

#### ldPrefix
Type: `String`
Default: `ld`

A prefix for your low-def sprite files.

#### resizeEngine
Options: `gm`, `im`
Default: `gm`

The engine that will be used behind-the-scenes for resizing. Defaults to GraphicsMagick; but if you only have ImageMagick installed and want to use that, instead, specify it here.

#### algorithm
Options: `top-down`, `left-right`, `diagonal`, `alt-diagonal`, `binary-tree`
Default: `binary-tree`

A packing algorithm to use. [See details in grunt-spritesmith's documentation.](https://github.com/Ensighten/grunt-spritesmith#algorithms)

#### algorithmOpts
[See details in grunt-spritesmith's documentation.](https://github.com/Ensighten/grunt-spritesmith#usage)

#### padding
Type: `Number`
Default: 1

Padding to be placed between images on the generated spritesheet(s).

#### engine
Options: `auto`, `phantomjs`, `canvas`, `gm`
Default: `gm`

Specify your spritesmith engine. [See details in grunt-spritesmith's documentation.](https://github.com/Ensighten/grunt-spritesmith#requirements)

#### engineOpts
Type: `Object`
Default: `{}`

Specify settings for your engine. [See details in grunt-spritesmith's documentation.](https://github.com/Ensighten/grunt-spritesmith#gm-graphics-magick--image-magick)

#### imageOpts
Type: `Object`
Default: `{}`

Specify image processing options. [See details in grunt-spritesmith's documentation.](https://github.com/Ensighten/grunt-spritesmith#usage)

#### assetFormats
Type: `Array`
Default: `['.png', '.jpg', '.jpeg']`

Accepted extensions for your sprite assets.

#### imgPath
Type: `String`
Default: *The default value is the relative path between your `destCSS` and `destImg` directories.*

Manually override the sprite image's path in the generated stylesheet's `background-image` url(s). Here are a couple of use cases:

- If the relative path from your `destCSS` directory (where the SCSS files go) to your `destImg` directory (where your sprite images go) will not be the same as the relative path from your compiled CSS to `destImg`.
- If you will be hosting the images elsewhere, eventually, on a CDN or something.

#### cssOpts
Type: `Object`
Default: `{}`

Options to pass to the Mustache template that generates your stylesheets.
  - `{ functions: false }`: the generated SCSS includes variables only, not mixins. This is handy if you are using multiple sprites in a project and don't want to duplicate the mixin definitions.
  - `{ createMap: false }`: If true, will create a variabble map in the SCSS file
  - `{ varPrefix: none }`: String value to set a prefix for the variables in the generated SCSS

#### failOnOddImageSize
Type: `Boolean`
Default: `false`

Set it to `true` in order to interrupt the build process if any of the standard source images size (width or height) is not even.

If it's set to `false` the build process just raise a warning.

All the images should have an even height and an even width `(e.g. 22x26px)`


#### ldCssTemplate
Type: `String`
Default: undefined

The default results in the use of the default template for the `scss` extension of json2css.
You can pass a path to a template that is then passed to grunt-spritesmith as the cssTemplate option. The path can be relative to the directory where you call grunt or relative to the tasks directory of grunt-spritesmith-hd.

#### hdCssTemplate
Type: `String`
Default: path.join(__dirname, 'templates/scss-hd.template.mustache')

If you don't pass this option, the scss-hd.template.mustache from grunt-spritesmith-hd is used.
You can pass a path to a template that is then passed to grunt-spritesmith as the cssTemplate option. The path can be relative to the directory where you call grunt or relative to the tasks directory of grunt-spritesmith-hd.

## Examples

### Basic:
```javascript
spriteHD: {
  options: {
    destImg: "sprites",
    destCSS: "scss/sprites",
    imgPath: "sprites"
  }
  all {
    src: ["images/sprite-assets/all/*"],
    spriteName: "all"
  }
  home: {
    src: ["images/sprite-assets/home/*"],
    spriteName: "home",
    options: {
      cssOpts: {
        functions: false,
        createMap: true,
        varPrefix: 'icon-medium'
      }
    }
  }
}
```
### combined scss maps:
This uses the template at https://github.com/benib/json2css_scss_combined_maps
```javascript
spriteHD: {
  options: {
    destImg: "sprites",
    destCSS: "scss/sprites",
    imgPath: "sprites",
    hdCssTemplate: 'node_modules/json2css_scss_combined_maps/scss_combined_maps.template.mustache',
    ldCssTemplate: 'templates/scss_combined_maps-hd.template.mustache'
  }
  all {
    src: ["images/sprite-assets/all/*"],
    spriteName: "all"
  }
  home: {
    src: ["images/sprite-assets/home/*"],
    spriteName: "home",
    options: {
      cssOpts: {
        functions: false
      }
    }
  }
}
```

## Using the Output

After running grunt-spritesmith-hd, in your `destCSS` directory you will find an unprefixed SCSS file — that is the one you should import into your own SCSS/Sass.

For example, a typical HD sprite with the `spriteName` "everything" will output `_everything-hd.scss` and `_everything.scss` into `destCSS`. You need to `@import "path/to/everything"`.

(If you look inside `_everything.scss`, you'll see that already imports `_everything-hd.scss`, so you don't have to worry about it.)