options.templateFile

Type: String

Default value: none

A string value that points to a file using normal grunt rules. A file's content is used to generate a sprite's CSS file. It should be a regular template understood by Underscore's template() or Lo-Dash's template() (the latter is used to compile it).

Depending on a value of options.fragment a template can have two processing modes: when it is called on a per-image basis (the default), and the output of each fragment is collected in a CSS file, and when it is used to generate a CSS file using logic encoded in a template itself.

The alternative way (deprecated since 0.2.0) to supply a template is to use options.template. If both are specified at the same time, options.template supersedes options.templateFile.

An external template can embed arbitrary JavaScript, yet it cannot access variables, and functions defined elsewhere. In order to reduce this limitation, we can use options.templateParams, which allows to pass an arbitrary object as a parameter.

See options.fragment, options.template, and options.templateParams for more details.

Template variables

Fragment mode

When options.fragment is true (the default), a template is used to create individual CSS class entries corresponding to original source images in a sprite. A template is instantiated repeatedly for every image.

When it is instantiated following variables are available:

name -- a fully-qualified (absolute) name of an original image.
shortName -- a relative name of an original image as it was generated by grunt.
className -- a CSS class name generated from a short name by replacing dots and file separators with underscores with a prefix (see options.classPrefix).
extension -- an image file extension starting with a dot, or an empty string, if no extension.
x -- a horizontal position of the image in a sprite in pixels.
y -- a vertical position of the image in a sprite in pixels.
w -- a width of the image in a sprite in pixels.
h -- a height of the image in a sprite in pixels.
url -- a relative or absolute path of a generated sprite. See options.absolute for details.
size -- an object with two properties:
- w -- a width of the generated sprite in pixels.
- h -- a height of the generated sprite in pixels.
params -- an arbitrary parameter object passed from grunt. See options.tempateParams for details.

Sometimes we need derived values not presented in the above table. Do not forget that template() accepts arbitrary JavaScript expressions, so it is possible to calculate what we need using the provided basic information.

See examples below.

Sprite mode

When options.fragment is false, a template is used to create the whole CSS file for a sprite. All possible logic should be coded in a template itself. This mode provides an ultimate control over generating a CSS, or LESS, or SASS, or Stylus, or any other type of text file, custom-tailored for our unique project.

When it is instantiated following variables are available:

images -- an array of individual objects described in details in the previous section. Its elements are used to instantiate a template when in the fragment mode. This array is usually used to generate individual CSS classes for every image.
url -- a relative or absolute path of a generated sprite. See options.absolute for details.
size -- an object with two properties:
- w -- a width of the generated sprite in pixels.
- h -- a height of the generated sprite in pixels.
params -- an arbitrary parameter object passed from grunt. See options.tempateParams for details.

url, size, and params properties are the same objects in both sprite and fragment modes. All items of images have these properties duplicated for convenience.

See examples below.

Default

When no template is specified, the following default template is used in the fragment mode:

.<%= className %> { background: url(<%= url %>) -<%= x %>px -<%= y %>px no-repeat; width: <%= w %>px;  height: <%= h %>px; }

The actual value is one line, and it has a newline symbol at the end.

The same information split on several lines for your convenience:

.<%= className %> {
  background: url(<%= url %>) -<%= x %>px -<%= y %>px no-repeat;
  width: <%= w %>px;
  height: <%= h %>px;
}

Examples

Example #1: the default

A fragment of CSS file generated with the default template:

.sprite_x16_address_16 {background: url(sprite1.png) -1568px -144px no-repeat; width: 16px; height: 16px;}
.sprite_x16_block_16 {background: url(sprite1.png) -1584px -144px no-repeat; width: 16px; height: 16px;}
...

Example #2: debugging

A custom template used for debugging can be specified like that:

grunt.initConfig({
  tight_sprite: {
    sprite2: {
      options: {
        hide: iconPath,
        templateFile: "./sprite2.tmpl"
      },
      src:  [iconPath + "*/**/*.{png,jpg,jpeg,gif}"],
      dest: iconPath + "sprite2.png"
    }
  }
});

sprite2.tmpl file:

.<%= className %> {
  /* image: <%= name %> */
  /* short: <%= shortName %> */
  background-position: -<%= x %>px -<%= y %>px;
  width: <%= w %>px;
  height: <%= h %>px;
}

It will produce a following fragment:

.sprite_x16_address_16 {
  /* image: /home/project/images/icons/16x16/address.png */
  /* short: 16x16/address.png */
  background-position: -1568px -144px;
  width: 16px;
  height: 16px;
}

.sprite_x16_block_16 {
  /* image: /home/project/images/icons/16x16/block.png */
  /* short: 16x16/block.png */
  background-position: -1584px -144px;
  width: 16px;
  height: 16px;
}
/* ... */

Example #3: the fragment mode

grunt.initConfig({
  tight_sprite: {
    sprite3: {
      options: {
        hide: iconPath,
        fragment: true, // the default
        templateFile: "./sprite3.tmpl"
      },
      src:  [iconPath + "*/**/*.{png,jpg,jpeg,gif}"],
      dest: iconPath + "sprite3.png"
    }
  }
});

sprite3.tmpl file:

.<%= className %> {background-position: -<%= x %>px -<%= y %>px; width: <%= w %>px; height: <%= h %>px;}

It produces an output similar to this:

.sprite_x16_address_16 {background-position: -1776px -144px; width: 16px; height: 16px;}
.sprite_x16_block_16 {background-position: -1760px -144px; width: 16px; height: 16px;}
.sprite_x16_bookmark_16 {background-position: -1792px -144px; width: 16px; height: 16px;}
/* ... */

Example #4: the sprite mode

To trigger this mode you should set options.fragment to false.

This example demonstrates how to use expressions to half off all pixel values, and how to iterate over all images.

grunt.initConfig({
  tight_sprite: {
    sprite4: {
      options: {
        hide: iconPath,
        fragment: false,
        templateFile: "./sprite4.tmpl"
      },
      src:  [iconPath + "*/**/*.{png,jpg,jpeg,gif}"],
      dest: iconPath + "sprite4.png"
    }
  }
});

sprite4.tmpl file:

.sprite {
  background-image: url(<%= url %>);
  background-repeat: no-repeat;
  background-size: <%= size.w / 2 %>px <%= size.h / 2 %>px;
}

<% images.forEach(function(image){ %>
.<%= image.className %> {
  background-position: -<%= image.x / 2 %>px -<%= image.y / 2 %>px;
  width:  <%= image.w / 2 %>px;
  height: <%= image.h / 2 %>px;
}
<% }); %>