grunt-spritesmith-hd

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

Requirements

grunt-spritesmith — allows for a variety of spriting engines (check out its requirements).

grunt-spritesmith-hd, though, is more restricted. It uses GraphicsMagick for Node 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.)

Installation

This plugin requires Grunt ~0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a 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. 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, so you can pass the same options to multiple targets.

$3

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.

$3

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.

#### algorithmOpts
See details in grunt-spritesmith's documentation.

#### 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.

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

Specify settings for your engine. See details in grunt-spritesmith's documentation.

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

Specify image processing options. See details in grunt-spritesmith's documentation.

#### 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

$3


`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'
}
}
}
}
`

$3

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.)