This package is forked from grunt-spritesmith and makes the following changes:
A folder of icons processed by
!Fork iconfork-iconfork-icon !+ !GitHub icongithub-icongithub-icon !+ !Twitter icontwitter-icontwitter-icon !=
generates a spritesheet:
!Spritesheetspritesheetspritesheet
and CSS variables (available in CSS, JSON, SASS, SCSSSASS, LESS, Stylus):
Run the
Results are a spritesheet and CSS:
!Spritesheetspritesheetspritesheet
For best packing, use
If you are worried about sprites being visible within other sprites, use
If you are using a repeating background,
The
If you are running into issues, consult the FAQ section.
Key differences:
spritesmith has been tested against
Key differences:
Instructions on how to install Cairocairo are provided in the node-canvas wikinode-canvas-wiki.
Additionally, you will need to install node-gyp for the C++ bindings.
Key differences:
For the best results, install from the site rather than through a package manager (e.g.
spritesmith has been developed and tested against
If you are using Image Magickimage-magick, you must specify it in
Forknoun-fork-icon designed by P.J. Onorionori from The Noun Project
Plus+ and Equals= icons were built using the Ubuntu Light typefaceubuntu-light.
!Support via Gittipgittip-badgegittip
Licensed under the MIT license.
- uses the Grunt 0.4 standard
this.options
andthis.files
instead of rawthis.data
. This is adventageous for using this task together with grunt-newer. - adds the options
mapSrcToName
andmapDestImageToUrl
.mapDestImageToUrl
replaces theimgPath
option.
A folder of icons processed by
grunt-spritely
:!Fork iconfork-iconfork-icon !+ !GitHub icongithub-icongithub-icon !+ !Twitter icontwitter-icontwitter-icon !=
generates a spritesheet:
!Spritesheetspritesheetspritesheet
and CSS variables (available in CSS, JSON, SASS, SCSSSASS, LESS, Stylus):
$fork_offset_x = 0px;
$fork_offset_y = 0px;
$fork_width = 32px;
$fork_height = 32px;
...
$github_offset_x = -32px;
$github_offset_y = 0px;
$github_width = 32px;
$github_height = 32px;
...
Cross-platform support
grunt-spritely
is supported and tested on Windows, Linux, and Mac OSX.Getting Started
grunt-spritely
can be installed via npm: npm install grunt-spritely
Before proceeding, verify you have satisfied your preferred engine's requirementsrequirements. ####
Then, add and configure it to your grunt file (grunt.js
or Gruntfile.js
depending on your version):module.exports = function (grunt) {
// Configure grunt
grunt.initConfig({
spritely: {
all: {
src: 'path/to/your/sprites/*.png',
destImg: 'destination/of/spritesheet.png',
destCSS: 'destination/of/sprites.css'
}
}
});
// Load in `grunt-spritely`
grunt.loadNpmTasks('grunt-spritely');
Run the
grunt sprite
task:$ grunt sprite
Running "sprite:all" (sprite) task
Files "spritesheet.png", "sprites.styl" created.
Done, without errors.
Results are a spritesheet and CSS:
!Spritesheetspritesheetspritesheet
.icon-fork {
background-image: url(spritesheet.png);
background-position: 0px 0px;
width: 32px;
height: 32px;
}
...
Usage
grunt-spritely
is a grunt multitaskmultitask. It is configured on a per-task basis using the following template:grunt.initConfig({
spritely: {
all: {
// Sprite files to read in
src: ['public/images/sprites/*.png'],
// Location of the image to output
dest: 'public/images/sprite.png',
options: {
// Stylus with variables under sprite names
destCSS: 'public/css/sprite_positions.styl',
// OPTIONAL: Transform the input image file name to the identifier used for the sprite.
mapSrcToName: 2,
// OPTIONAL: Transform the output image file into a URL
mapDestImageToUrl: 2,
// OPTIONAL: Specify algorithm (top-down, left-right, diagonal [\ format],
// alt-diagonal [/ format], binary-tree [best packing])
// Visual representations can be found below
algorithm: 'alt-diagonal',
// OPTIONAL: Specify padding between images
padding: 2,
// OPTIONAL: Specify engine (auto, phantomjs, canvas, gm)
engine: 'canvas',
// OPTIONAL: Specify CSS format (inferred from destCSS extension by default)
// (stylus, scss, sass, less, json, jsonArray, css)
cssFormat: 'json',
// OPTIONAL: Specify a Mustache template to use for destCSS; mutually exclusive to cssFormat
cssTemplate: 'public/css/sprite_positions.styl.mustache',
// OPTIONAL: Map variable of each sprite
cssVarMap: function (sprite) {
// `sprite` has `name`, `image` (full path), `x`, `y`
// `width`, `height`, `total_width`, `total_height`
// EXAMPLE: Prefix all sprite names with 'sprite-'
sprite.name = 'sprite-' + sprite.name;
},
// OPTIONAL: Specify settings for engine
engineOpts: {
imagemagick: true
},
// OPTIONAL: Specify img options
imgOpts: {
// Format of the image (inferred from destImg's extension by default) (jpg, png)
format: 'png',
// Quality of image (gm only)
quality: 90
},
// OPTIONAL: Specify css options
cssOpts: {
// Some templates allow for skipping of function declarations
functions: false,
// CSS template allows for overriding of CSS selectors
cssClass: function (item) {
return '.sprite-' + item.name;
}
}
}
}
}
});
Specifying files
Files may be specified using several different grunt-standard formats described here: http://gruntjs.com/configuring-tasks#files. For example:New configuration examples
One sheet
spritely: {
all: {
options: {
destCSS: 'destination/of/sprites.css'
},
src: 'path/to/your/sprites/*.png',
dest: 'destination/of/spritesheet.png'
}
}
Multiple sheets
spritely: {
all: {
options: {
destCSS: 'destination/of/sprites.css'
},
files: [
{
src: 'path/to/your/sprites/core/*@1x.png',
dest: 'destination/of/core@1x.png',
},
{
src: 'path/to/your/sprites/core/*@2.png',
dest: 'destination/of/core@2x.png',
},
{
src: 'path/to/your/sprites/detail-page/*@1x.png',
dest: 'destination/of/detail-page@1x.png',
},
{
src: 'path/to/your/sprites/detail-page/*@2x.png',
dest: 'destination/of/detail-page@2x.png',
}
]
}
}
Algorithms
| top-down (default) | left-right | diagonal | alt-diagonal | binary-tree | | ------------------------- | ----------------------------- | ------------------------- | --------------------------------- | ------------------------------- | | !top-downtop-down | !left-rightleft-right | !diagonaldiagonal | !alt-diagonalalt-diagonal | !binary-treebinary-tree |For best packing, use
binary-tree
which uses a solution to the rectangle packing problempacking-problem.If you are worried about sprites being visible within other sprites, use
alt-diagonal
.If you are using a repeating background,
top-down
or left-right
depending on your occasion.The
diagonal
algorithm exists for you if you need it.Requirements
For cross-platform accessibility, spritesmithspritesmith has and supports multiple sprite engines. However, each of these current engines has a different set of external dependencies.If you are running into issues, consult the FAQ section.
phantomjs
Thephantomjs
engine relies on having phantomjs installed on your machine. Visit the phantomjs websitephantomjs for installation instructions.Key differences:
phantomjs
is the most accessible engine.spritesmith has been tested against
phantomjs@1.9.0
.canvas
Thecanvas
engine uses node-canvas which has a dependency on Cairocairo.Key differences:
canvas
has the best performance (useful for over 100 sprites). However, it is UNIX
only.Instructions on how to install Cairocairo are provided in the node-canvas wikinode-canvas-wiki.
Additionally, you will need to install node-gyp for the C++ bindings.
sudo npm install -g node-gyp
gm (Graphics Magick / Image Magick)
Thegm
engine depends on Graphics Magickgraphics-magick or Image Magickimage-magick.Key differences:
gm
has the most options for export via imgOpts
.For the best results, install from the site rather than through a package manager (e.g.
apt-get
). This avoids potential transparency issues which have been reported.spritesmith has been developed and tested against
1.3.17
.If you are using Image Magickimage-magick, you must specify it in
engineOpts
{
'engineOpts': {
'imagemagick': true
}
}
FAQs
I am seeing errors during installation.
Ifnpm
exits normally, everything should work. These errors are being caused by npm
attempting to install the various spritesmith
engines.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 vianpm test
.Algorithms
Algorithms are maintained via twolfson/layout. If you would like to add one, please submit it via a pull request.Engines and image options
Engines and image options are maintained via Ensighten/spritesmith. If you would like to add one, please submit it via a pull request.CSS formats
CSS formats are maintained via twolfson/json2css. If you would like to add one, please submit it via a pull request.Attribution
GitHubgithub-icon and Twittertwitter-icon icons were taken from Alex Peattie's JustVector Social Iconsjustvector.Forknoun-fork-icon designed by P.J. Onorionori from The Noun Project
Plus+ and Equals= icons were built using the Ubuntu Light typefaceubuntu-light.
Donating
Support this project and others by twolfsongittip via gittip.!Support via Gittipgittip-badgegittip
License
Copyright (c) 2012-2013 EnsightenLicensed under the MIT license.