Combine multiple images into CSS Sprites using advanced layouts from CSS::SpriteMaker Perl module.
The requirements of this plugin are:
-
Grunt
>=0.4.0
-
Perl 5 installed and compiled with -fPIC and -Duseshrplib. Normally, linux distribution's system perl works.
-
CSS::SpriteMaker module
0.10+
installed from CPAN (cpan install CSS::SpriteMaker
). You should be able to runperldoc CSS::SpriteMaker
.
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:
npm install grunt-css-spritemaker --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-css-spritemaker');
In your project's Gruntfile, add a section named css_spritemaker
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
css_spritemaker: {
options: {
// Task-specific options go here.
},
your_target: {
options: {
// Target-specific options go here.
},
// Target-specific settings follow here ...
}
}
});
Type: Boolean
Default value: false
If true, the path to dest will be created
Type: Object
Default value: undefined
An object used for CSS (or LESS) spritesheet file. If specified, a .css/.less spritesheet will be also generated, therefore the targetCssPath attribute is required.
Other options for generateCss
are:
-
renameSpriteImagePath
: an alternative name that points to the image sprite. This can be useful if the spritesheet is to be moved elsewhere with other tasks that stem from grunt-css-spritemaker. -
cssClassPrefix
: a prefix to be added to each css class name
In summary, this is the kind of object expected:
generateCss: {
// required
targetCssPath : "tmp/sprite.css",
// optional
renameSpriteImagePath : "somewhere/over/the/rainbow.png"
// optional
cssClassPrefix: "icon-"
}
Type: Object
Default value: undefined
Used to specify options related to image generation. At the moment you can specify layouts in this section. For example this is a structure like:
generateImage: {
layout: {
'name' : 'FixedDimension',
'options' : {
n : '2' // see CSS::SpriteMaker Docs!
}
}
}
In this example, the default options are used to generate the sprite image. All the images in src will be combined into a single image into tmp/sprite.png.
grunt.initConfig({
css_spritemaker: {
options : {
createTargetPaths: true,
},
src: 'test/fixtures/nsti/',
dest: 'tmp/sprite.png'
},
});
In this example, src is an array of files and directories.
grunt.initConfig({
css_spritemaker: {
options : {
createTargetPaths: false,
},
src: [
'images/bullet-orange.png',
'images/iconsdir/' // a directory, ends with '/'
],
dest: 'tmp/withSourceImages.png',
},
});
In this example, a Packed layout is used to compose the images.
grunt.initConfig({
css_spritemaker: {
options : {
createTargetPaths: false,
generateImage: {
layoutName: 'Packed'
}
},
src: 'test/fixtures/nsti',
dest: 'tmp/withPackedLayout.png'
},
});
The layouts available depend on the version of CSS::SpriteMaker you have currently installed. You can have a look at http://search.cpan.org/~darksmo/CSS-SpriteMaker/ for a list of available layouts. At the moment, the following layouts are available:
-
DirectoryBased
-
FixedDimension
-
Packed
Some layouts have options. To specify options you need to use the following 'extended' form, using the layout
key instead of layoutName
:
grunt.initConfig({
css_spritemaker: {
options : {
createTargetPaths: true,
generateImage: {
layout: {
'name' : 'FixedDimension',
'options' : {
n : '2' // see CSS::SpriteMaker Docs!
}
}
}
},
src: 'test/fixtures/nsti/',
dest: 'tmp/withExtendedLayoutDefinition.png'
},
});
You can consult CSS::SpriteMaker documentation to know about the options for the various layouts. For example, you can get the documentation of the FixedDimention layout by running perldoc CSS::SpriteMaker::Layout::FixedDimension
.
In this example, the resulting sprite image (tmp/withCompositeLayout.png) is made up of two parts, which are in turn lay out through a 'glue' layout.
Note the dest argument is the same across the various parts of the sprite.
grunt.initConfig({
css_spritemaker: {
options : {
createTargetPaths: true,
generateCss: {
// required
targetCssPath : "tmp/sprite.css",
},
generateImage: {
//
// The 'glue' layout goes here
//
layout: {
'name' : 'FixedDimension',
'options' : {
n : '2'
}
}
}
},
files: [
//
// Parts of this sprite follow
//
{ src: [
'test/fixtures/nsti/homepage-bullet-orange.png',
'test/fixtures/nsti/cancel-feature.png'
],
dest: 'tmp/withCompositeLayout.png', // NOTE: is the same in the next file definition
options: {
layoutName: 'Packed' // compact layout spec
}
},
{ src: ['test/fixtures/nsti'],
dest: 'tmp/withCompositeLayout.png', // See NOTE above
//
// options specific to one part follow
//
options: {
// 'extended' layout spec
layout : {
'name' : 'DirectoryBased'
},
includeInCss : 0,
removeSourcePadding : 1, // first remove padding from source images
addExtraPadding: 5 // then add extra 5px padding
}
}
]
},
});
As you can see each part can be independently specified. Two options can be specified for each part:
-
includeInCss: if set to false, the resulting
sprite.css
stylesheet will not include the images from the layout part in which the option is specified; -
removeSourcePadding: if set to false, won't touch the padding in source images. Otherwise each image in the part will have the surrounding padding (transparent color) removed.
-
addExtraPadding: amount of pixel of padding to add to each image.
Sometimes you don't want to wait for the layout to be computed and just need a css without the sprite image. This css will be including images using a url attribute. Rules will look like:
.icon-zoom- { url('test/fixtures/nsti/zoom--.png'); width: 32px; height: 32px; }
To generate a fake css just specify fakeCss = true
among the options:
grunt.initConfig({
css_spritemaker: {
options : {
generateCss: {
fakeCss: true, // activate fake css mode
targetCssPath : "tmp/fakeCss.css", // required
cssClassPrefix: 'icon-' // optional
}
},
// where to find the source images (also sourceImages is fine here)
src: 'test/fixtures/nsti/'
// NOTE: in fake css mode, no image or layout related parameter must be specified!
},
});
IMPORTANT NOTE: turning fakeCss on will not generate any sprite image, and ignore any options related to image sprite generation. grunt-css-spritemaker will warn about this.
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
-
0.2.2 - Sun Jun 12 11:11:31 CEST 2016
- update peerDependencies to be compatible with grunt 1.0
-
0.2.1 - Fri May 30 12:06:49 CEST 2014
- allow addExtraPadding option introduced in CSS::SpriteMaker v0.14
-
0.2.0 - Mon May 19 11:17:57 CEST 2014
- IMPORTANT: change of interface. Now css_spritemaker complies with grunt standard interface.
-
0.1.0 - Wed May 14 01:58:44 CEST 2014
- First release
-
0.1.1 - Wed May 14 11:30:28 CEST 2014
- Update dependencies
-
0.1.2 - Thu May 15 00:01:24 CEST 2014
- added fakeCss option to generate fake CSS spritesheets (requires CSS::SpriteMaker 0.10+)