Grunt task for creating multiple image spritesheets with custom processing callbacks
npm install grunt-spritefilesgrunt-spritefiles
=================
Grunt library for using spritesmith, a spritesheet and CSS pre-processor utility.
Synopsis
--------
Spritesmith accepts a list of images, stiches them together, and returns that image along with a coordinate map of where each image is located and its dimensions.
Grunt is a node.js based CLI build tool.
json2css converts the output from Spritesmith and generates variables and helper functions for hooking into inside of your CSS pre-processor.
When you combine all three of these, you get a grunt plugin that makes maintaining sprites a breeze.
Getting Started
---------------
Install this grunt plugin next to your project's grunt.js gruntfile with: npm install grunt-spritefiles
Then add this line to your project's grunt.js gruntfile:
``javascript`
grunt.loadNpmTasks('grunt-spritefiles');
Requirements
------------
Spritesmith supports multiple sprite engines however all of the current engines require external software to be installed. See spritesmith for instructions.
Why Use This Task
-----------------
You need to generate multiple sprite images and run custom processing over the results. If this isn't true, you probably want a simpler, more maintained plugin like grunt-spritesmith, the basis for this plugin. That being said, this plugin works and I'm happy to receive patches if it doesn't.
This module was written for a large, complex, existing product that needed to programatically generate sprite-creation tasks and run custom processing for sprites without changing old workflow. It uses the typical grunt src/dest/files attributes to generate multiple sprites per task. The spritesmith results are passed to a function to allow any customised processing.
Usage
-----
`js
// Load package if using extra functions from it
var sprite = require('./src/grunt-spritefiles.js');
// Provide a custom processing function
var customSprites = function(grunt, that, sprite, result) {
// grunt: Grunt object, as available to task
// that: this object from task
// sprite: grunt files object for sprite
// result: spritesmith result object
grunt.verbose.writeflags(sprite, 'Files');
grunt.verbose.writeflags(result.coordinates, 'Sprite coordinates');
};
grunt.initConfig({
'sprite': {
'all': {
// Uses standard grunt src/dest/files attributes for building sprite image
'files': [
{ dest: 'images/sprite.png', src: ['images/sprites/*.png'] },
{ dest: 'images/sprite.png', src: ['images/sprites/*.png'],
// Processor function to run for each sprite
processor: sprite.cssFile( // write CSS file (matches grunt-spritesmith)
'css/sprite.json', // css file location
{
// OPTIONAL: Specify CSS format (inferred from file's extension by default)
// (stylus, scss, sass, less, json)
'cssFormat': 'json',
// OPTIONAL: Manual override for imgPath specified in CSS
'imgPath': '../sprite.png'
})
},
'options': {
// OPTIONAL: Specify algorithm (top-down, left-right, diagonal [\ format],
// alt-diagonal [/ format], binary-tree [best packing])
'algorithm': 'alt-diagonal',
// OPTIONAL: Specify engine (auto, canvas, gm)
'engine': 'canvas',
// OPTIONAL: Specify img options
'imgOpts': {
// Format of the image (inferred from destImg' extension by default) (jpg, png)
'format': 'png',
// Quality of image (gm only)
'quality': 90
}
}
]
},
'all': {
dest: 'images/custom.png',
src: ['images/*.gif'],
processor: customSprites
}
}
});
`
Contributing
------------
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via grunt and test via npm test`.
License
-------
Copyright (c) 2012 Ensighten
Copyright (c) 2013 Recognia Inc
Licensed under the MIT license.