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 .pngs 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 to watch.sourceDir, which defaults to assets
• outDir: Where to place generated sprites relative to watch.sourceDir Placing the output images outside the sprite directory makes it easy to exclude the sprite directory from being copied to watch.compiledDir.
• commonDir: Folder inside which are images to be included in every sprite. This is a string path relative to inDir.
• stylesheetOutDir: Where to place the output stylesheets. Path is relative to watch.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's src, spritePath and stylesheetPath based on the inDir folder's structure. Other config options can be placed in this options 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 output sass code.