mimosa-sprite
Overview
This is a module that will generate CSS sprites and corresponding stylesheets for your Mimosa project.
For an example Mimosa app that uses this module, checkout the MimosaSpriteExample project.
For more information regarding Mimosa, see http://mimosa.io.
Note: v0.5.0
of mimosa-sprite requires 2.2.17
of Mimosa.
Usage
Add 'sprite'
to your list of modules. That's all! Mimosa will install the module for you when you start up.
This module depends on node-sprite-generator which in turn requires that you have either Cairo or Image/GraphicsMagick installed. So, for example, is you are using brew
, you should execute brew install GraphicsMagick
and brew install ImageMagick
prior to using this module. See the node-sprite-generator installation docs for details.
Once this module has been added to your project, just execute mimosa sprite
to generate your sprites. This module comes with some default config (see below) and if your project matches that config, you won't have any other work to do.
Functionality
This module will generate sprite images and Stylus/SASS/LESS/CSS artifacts for those sprites.
Sprites will be generated for each folder in the sprite.inDir
. So, if sprite.inDir
points to images/sprite
(the default), and inside images/sprite
there are 3 folders named foo
, bar
and baz
, then 3 sprite .png
s will be created called foo.png
, bar.png
and baz.png
. Those images will be placed in the sprite.outDir
, which is by default images
.
For each sprite created, this module will place a stylesheet asset (either SASS, LESS, Stylus or CSS depending on config, Stylus by default), in the sprite.stylesheetOutDir
.
If you are building many sprites, and those sprites have a set of images in common, you can place the common images in the sprite.commonDir
, by default images/sprite/common
. This special folder will not create a sprite of its own, but any images inside this folder will be included in all sprites.
node-sprite-generator offers up a large set of configuration options. sprite.options
can be used to override and set those options. sprite.options
can be an object or a function. If it is an object, the values in the object will overwrite the config mimosa-sprite creates for each sprite. If sprite.options
is a function, it will be called with the generated config giving you the opportunity to modify it. This provides a programmatic means to update or override the configuration.
Default Config
sprite: inDir: "images/sprite" outDir: "images" commonDir: "common" stylesheetOutDir: "stylesheets/sprite" options: stylesheet:"stylus"
inDir
: a string. The folder inside which are the images to be sprited. Every folder at the root of this folder will generate a single sprite. This path is relative towatch.sourceDir
, which defaults toassets
outDir
: Where to place generated sprites relative towatch.sourceDir
Placing the output images outside the sprite directory makes it easy to exclude the sprite directory from being copied towatch.compiledDir
.commonDir
: Folder inside which are images to be included in every sprite. This is a string path relative toinDir
.stylesheetOutDir
: Where to place the output stylesheets. Path is relative towatch.sourceDir
options
, an object or function. Pass-through options for node-sprite-generator, the tool this module uses under the hood to do the heavy lifting. mimosa-sprite provides the values for that tool'ssrc
,spritePath
andstylesheetPath
based on theinDir
folder's structure. Other config options can be placed in thisoptions
object. For more control,options
can be a function that takes the inferred config generated by mimosa-sprite. If you are generating 10 sprites, the options function will be called 10 times for each sprite, giving you the chance to make specific modifications to the node-sprite-generator config.options.stylesheet
: A string, the type of stylesheet to output. Valid values: stylus, less, sass, scss, css.
Example Config
sprite:
options:
layout: 'horizontal'
stylesheet: 'sass'
sprite.options.layout
is a pass-through to node-sprite-generator's layout config. This is one example of providing config through to node-sprite-generator.sprite.options.stylesheet
tells node-sprite-generator to outputsass
code.