spritesheet-templates

Convert spritesheet data into CSS or CSS pre-processor data

spritesheet-templates

Convert spritesheet data into CSS or CSS pre-processor data

spritesheet-templates, formerly json2css, was built as part of spritesmith, a tool that converts images into spritesheets and CSS variables.

Getting Started

Install the module with: npm install spritesheet-templates

// Compilation
var templater = require('spritesheet-templates');
templater({
  sprites: [{
    name: 'github', x: 0, y: 0, width: 10, height: 20
  }, {
    name: 'twitter', x: 10, y: 20, width: 20, height: 30
  }, {
    name: 'rss', x: 30, y: 50, width: 50, height: 50
  }],
  spritesheet: {
    width: 80, height: 100, image: 'url/path/to/spritesheet.png'
  }
}, {format: 'stylus'}); /*
// Result stylus
$github_x = 0px;
$github_y = 0px;
...
$github = 0px 0px 0px 0px 10px 20px 80px 100px 'url/path/to/spritesheet.png' 'github';
...
$twitter = 10px 20px -10px -20px 20px 30px 80px 100px 'url/path/to/spritesheet.png' 'twitter';
...
$rss = 30px 50px -30px -50px 50px 50px 80px 100px 'url/path/to/spritesheet.png' 'rss';
...
spriteWidth($sprite) {
  width: $sprite[0];
}
...
sprite($sprite) {
  spriteImage($sprite)
  spritePosition($sprite)
  spriteWidth($sprite)
  spriteHeight($sprite)
}

// Inside of your Stylus
.github-logo {
  sprite($github);
}
*/

Documentation

spritesheet-templatesexports the function templateras its module.exports.

templater(data, options)

Converter for spritesheet/sprite info into spritesheet

  • data Object- Container for data for template
    • items Object[]- Deprecated alternative key to define data.sprites
    • sprites Object[]- Array of objects with coordinate data about each sprite on the spritesheet
        • Object- Container for sprite coordinate data
          • For reference, *symbolizes any index (e.g. data.sprites[0])
          • name String- Name to use for the image
          • x Number- Horizontal coordinate of top-left corner of image
          • y Number- Vertical coordinate of top-left corner of image
          • width Number- Horizontal length of image in pixels
          • height Number- Vertical length of image in pixels
    • spritesheet Object- Information about spritesheet
      • width Number- Horizontal length of image in pixels
      • height Number- Vertical length of image in pixels
      • image String- URL to use for spritesheet
        • This will typically be used in background-image
        • For example, background-image: url({{spritesheet.image}});
    • spritesheet_info Object- Optional container for metadata about spritesheetand its representation
      • name String- Prefix to use for all spritesheet variables
        • For example, iconswill generate $icons-width/$icons-image/etc in a SCSS template
        • By default, this is spritesheet(e.g. $spritesheet-width, $spritesheet-image)
    • Additional parameters for retinatemplates are documented in the Retina parameters section
  • options Object- Optional settings
    • spritesheetName String- Deprecated alternative for spritesheet_info.name
    • format String- Format to generate output in
    • formatOpts Mixed- Options to pass through to the formatter

Returns:

  • retVal String- Result from specified formatter

Retina parameters

retinatemplates require additional parameters data.retina_sprites, data.retina_spritesheetand data.retina_groupsto be passed in.

For the variables to be useful, the retina spritesheet should be a 2x scale image of the original spritesheet. Similarly, retina sprites should be positioned in the same layout and order as their normal counterparts (e.g. [{x: 0, y: 0}, {x: 20, y: 20}]should correspond to [{x: 0, y: 0}, {x: 40, y: 40}]).

  • data Object- Same container as defined above
    • retina_sprites Object[]- Array of objects with coordinate data about each retina sprite for the retina spritesheet
      • Properties are retina equivalent of data.sprites
      • These should be in the same order as their normal complements
    • retina_spritesheet Object- Information about retina spritesheet
      • Properties are retina equivalent of data.spritesheet
    • retina_spritesheet_info Object- Optional container for metadata about retina_spritesheetand its representation
      • name String- Prefix to use for all retina spritesheet variables
        • For example, retina-iconswill generate $retina-icons-width/$retina-icons-image/etc in a SCSS template
        • By default, this is retina-spritesheet(e.g. $retina-spritesheet-width, $retina-spritesheet-image)
    • retina_groups Object[]- Array of objects that maps to normal and retina sprites
        • Object- Container for data about sprite mapping
          • name String- Name to refer to mapping by
            • This is typically used for CSS selectors and variable names
          • index Number- Index to look up corresponding normal/retina sprites from data.sprites/data.retina_sprites
    • retina_groups_info Object- Optional container for metadata about retina_groupsand its representation
      • name String- Name to use for retina_groupsvariable
        • For example, icon-groupswill generate $icons-groupsin a SCSS template
        • By default, this is retina-groups(e.g. $retina-groups)

Templates

Below are our template options for options.format.

Handlebars-based templates support inheritance via handlebars-layouts(e.g. {{#extend "css"}}). Inherited templates must copy/paste JSON front matter. An example can be found in the Examples section.

Retina templates have the same setup but are located in the Retina templates sectionfor convenience.

css

Ouput CSS variables as CSS rules.

Options:

  • cssSelector Function- Override mapping for CSS selector
    • cssSelectorshould have signature function (sprite) { return 'selector'; }
    • By default this will return '.icon-' + sprite.name
    • It will receive spritewith all parameters designed for template

Handlebars blocks:

cssis a Handlebars based template. We allow for overriding the following sections:

  • {{#content "sprites-comment"}}- Comment before CSS rules
  • {{#content "sprites"}}- CSS rules

Example:

.icon-sprite1 {
  background-image: url(nested/dir/spritesheet.png);
  background-position: 0px 0px;
  width: 10px;
  height: 20px;
}
.icon-sprite2 {
/* ... */

json

Output CSS variables in JSON format.

Example:

{
    "sprite1": {
        "x": 0,
        "y": 0,
        "width": 10,
        "height": 20,
        "total_width": 80,
        "total_height": 100,
        "image": "nested/dir/spritesheet.png",
        "offset_x": 0,
        "offset_y": 0,
        "px": {
            "x": "0px",
            "y": "0px",
            "offset_x": "0px",
            "offset_y": "0px",
            "height": "20px",
            "width": "10px",
            "total_height": "100px",
            "total_width": "80px"
        },
        "escaped_image": "nested/dir/spritesheet.png"
    },
    "sprite2": {
    // ...

json_array

Output CSS variables as an array of objects.

Example:

[
    {
        "name": "sprite1",
        "x": 0,
        "y": 0,
        "width": 10,
        "height": 20,
        "total_width": 80,
        "total_height": 100,
        "image": "nested/dir/spritesheet.png",
        "offset_x": 0,
        "offset_y": 0,
        "px": {
            "x": "0px",
            "y": "0px",
            "offset_x": "0px",
            "offset_y": "0px",
            "height": "20px",
            "width": "10px",
            "total_height": "100px",
            "total_width": "80px"
        },
        "escaped_image": "nested/dir/spritesheet.png"
    },
    {
        "name": "sprite2",
        // ...

json_texture

Output CSS variables as an object in format similar to that of TexturePacker. Useful for game frameworks, such as Phaser, Pixi.js, and others.

For consistency with TexturePacker, we will use the basenameof a given image. spritesmithprovides this via sprite.source_image. If you would like to provide a custom name, then please define sprite.frame_name:

// Input
{
  sprites: [{
    frame_name: 'hello', name: 'github', x: 0, y: 0, width: 10, height: 20
  }]
}

// Output
{
  frames: {
    hello: {x: 0, y: 0, w: 10, h: 20}
  }
}

If neither sprite.source_imagenor spriteframeis used, then sprite.namewill be used.

For integration in grunt-spritesmith/gulp.spritesmith, please see their cssVarMapdocumentation.

Example:

{
    "frames": {
        "mysprite.png": {
            "frame": {
                "x": 10,
                "y": 20,
                "w": 20,
                "h": 30
            }
        },
        // ...
    },
    "meta": {
        "app": "spritesheet-templates",
        // ...
        "image": "nested/dir/spritesheet.png",
        "scale": 1,
        "size": {
            "w": 80,
            "h": 100
        }
    }
}

less

Output CSS variables as LESSvariables.

Options:

Handlebars blocks:

lessis a Handlebars based template. We allow for overriding the following sections:

  • {{#content "sprites-comment"}}- Comment before LESS variable declarations
  • {{#content "sprites"}}- LESS variable declarations for sprites
  • {{#content "spritesheet"}}- LESS variable declarations for spritesheet
  • {{#content "sprite-functions-comment"}}- Comment before LESS functions for sprite variables
  • {{#content "sprite-functions"}}- LESS functions for sprite variables
  • {{#content "spritesheet-functions-comment"}}- Comment before LESS functions for spritesheet variables
  • {{#content "spritesheet-functions"}}- LESS functions for spritesheet variables

Example:

@sprite1-name: 'sprite1';
@sprite1-x: 0px;
@sprite1-y: 0px;
@sprite1-offset-x: 0px;
@sprite1-offset-y: 0px;
@sprite1-width: 10px;
@sprite1-height: 20px;
@sprite1-total-width: 80px;
@sprite1-total-height: 100px;
@sprite1-image: 'nested/dir/spritesheet.png';
@sprite1: 0px 0px 0px 0px 10px 20px 80px 100px 'nested/dir/spritesheet.png' 'sprite1';
@sprite2-name: 'sprite2';
// ...

sass

Output CSS variables as SASSvariables.

Options:

Handlebars blocks:

sassis a Handlebars based template. We allow for overriding the following sections:

  • {{#content "sprites-comment"}}- Comment before SASS variable declarations
  • {{#content "sprites"}}- SASS variable declarations for sprites
  • {{#content "spritesheet"}}- SASS variable declarations for spritesheet
  • {{#content "sprite-functions-comment"}}- Comment before SASS functions for sprite variables
  • {{#content "sprite-functions"}}- SASS functions for sprite variables
  • {{#content "spritesheet-functions-comment"}}- Comment before SASS functions for spritesheet variables
  • {{#content "spritesheet-functions"}}- SASS functions for spritesheet variables

Example:

$sprite1-name: 'sprite1'
$sprite1-x: 0px
$sprite1-y: 0px
$sprite1-offset-x: 0px
$sprite1-offset-y: 0px
$sprite1-width: 10px
$sprite1-height: 20px
$sprite1-total-width: 80px
$sprite1-total-height: 100px
$sprite1-image: 'nested/dir/spritesheet.png'
$sprite1: 0px 0px 0px 0px 10px 20px 80px 100px 'nested/dir/spritesheet.png' 'sprite1'
$sprite2-name: 'sprite2'
// ...

scss

Output CSS variables as SCSSvariables.

Options:

Handlebars blocks:

scssis a Handlebars based template. We allow for overriding the following sections:

  • {{#content "sprites-comment"}}- Comment before SCSS variable declarations
  • {{#content "sprites"}}- SCSS variable declarations for sprites
  • {{#content "spritesheet"}}- SCSS variable declarations for spritesheet
  • {{#content "sprite-functions-comment"}}- Comment before SCSS functions for sprite variables
  • {{#content "sprite-functions"}}- SCSS functions for sprite variables
  • {{#content "spritesheet-functions-comment"}}- Comment before SCSS functions for spritesheet variables
  • {{#content "spritesheet-functions"}}- SCSS functions for spritesheet variables

Example:

$sprite1-name: 'sprite1';
$sprite1-x: 0px;
$sprite1-y: 0px;
$sprite1-offset-x: 0px;
$sprite1-offset-y: 0px;
$sprite1-width: 10px;
$sprite1-height: 20px;
$sprite1-total-width: 80px;
$sprite1-total-height: 100px;
$sprite1-image: 'nested/dir/spritesheet.png';
$sprite1: 0px 0px 0px 0px 10px 20px 80px 100px 'nested/dir/spritesheet.png' 'sprite1';
$sprite2-name: 'sprite2';
// ...

scss_maps

Output CSS variables as SCSSmaps variables.

Options:

Handlebars blocks:

scss_mapsis a Handlebars based template. We allow for overriding the following sections:

  • {{#content "sprites-comment"}}- Comment before SCSS variable declarations
  • {{#content "sprites"}}- SCSS variable declarations for sprites
  • {{#content "spritesheet"}}- SCSS variable declaration for spritesheet
  • {{#content "sprite-functions-comment"}}- Comment before SCSS functions for sprite variables
  • {{#content "sprite-functions"}}- SCSS functions for sprite variables
  • {{#content "spritesheet-functions-comment"}}- Comment before SCSS functions for spritesheet variables
  • {{#content "spritesheet-functions"}}- SCSS functions for spritesheet variables

Example:

$sprite1: (
  name: 'sprite1',
  x: 0px,
  y: 0px,
  offset_x: 0px,
  offset_y: 0px,
  width: 10px,
  height: 20px,
  total_width: 80px,
  total_height: 100px,
  image: 'nested/dir/spritesheet.png'
);
$sprite2: (
// ...

stylus

Output CSS variables as Stylusvariables.

Options:

Handlebars blocks:

stylusis a Handlebars based template. We allow for overriding the following sections:

  • {{#content "sprites-comment"}}- Comment before Stylus variable declarations
  • {{#content "sprites"}}- Stylus variable declarations for sprites
  • {{#content "spritesheet"}}- Stylus variable declarations for spritesheet
  • {{#content "sprite-functions-comment"}}- Comment before Stylus functions for sprite variables
  • {{#content "sprite-functions"}}- Stylus functions for sprite variables
  • {{#content "spritesheet-functions-comment"}}- Comment before Stylus functions for spritesheet variables
  • {{#content "spritesheet-functions"}}- Stylus functions for spritesheet variables

Example:

$sprite1_name = 'sprite1';
$sprite1_x = 0px;
$sprite1_y = 0px;
$sprite1_offset_x = 0px;
$sprite1_offset_y = 0px;
$sprite1_width = 10px;
$sprite1_height = 20px;
$sprite1_total_width = 80px;
$sprite1_total_height = 100px;
$sprite1_image = 'nested/dir/spritesheet.png';
$sprite1 = 0px 0px 0px 0px 10px 20px 80px 100px 'nested/dir/spritesheet.png';
$sprite2_name = 'sprite2';
// ...

Retina templates

These are a subset of templates that support retina spritesheets. These require retina parameters like retina_spritesare provided in order to work properly.

css_retina

Ouput CSS variables as CSS rules with media query and additional rules for retina support.

Options:

  • cssSelector Function- Override mapping for CSS selector
    • cssSelectorshould have signature function (retinaGroup) { return 'selector'; }
    • By default this will return '.icon-' + retinaGroup.name
    • It will receive retinaGroupwith all parameters designed for retina_groups[*]in templates (e.g. name, normal, retina)

Handlebars blocks:

We extend from the csstemplateand have its blocks. There are no new sections for retina data.

Example:

.icon-sprite1 {
  background-image: url(nested/dir/spritesheet.png);
  background-position: 0px 0px;
  width: 10px;
  height: 20px;
}
/* ... */
@media (-webkit-min-device-pixel-ratio: 2),
       (min-resolution: 192dpi) {
  .icon-sprite1 {
    background-image: url(nested/dir/spritesheet@2x.png);
    background-size: 80px 100px;
  }
}

json_retina

Output retina CSS variables in JSON format.

Example:

{
    "sprite1": {
        "normal": {
            "x": 0,
            "y": 0,
            "width": 10,
            "height": 20,
            "image": "nested/dir/spritesheet.png",
            "escaped_image": "nested/dir/spritesheet.png",
            "total_width": 80,
            "total_height": 100,
            "offset_x": 0,
            "offset_y": 0,
            "px": {
                "x": "0px",
                "y": "0px",
                "offset_x": "0px",
                "offset_y": "0px",
                "height": "20px",
                "width": "10px",
                "total_height": "100px",
                "total_width": "80px"
            }
        },
        "retina": {
            "x": 0,
            "y": 0,
            // ...
    },
    "sprite2": {
    // ...

json_array_retina

Output retina CSS variables as an array of objects.

Example:

[
    {
        "name": "sprite1",
        "normal": {
            "x": 0,
            "y": 0,
            "width": 10,
            "height": 20,
            "total_width": 80,
            "total_height": 100,
            // ...
        },
        "retina": {
            "x": 0,
            "y": 0,
            "width": 20,
            "height": 40,
            "total_width": 160,
            "total_height": 200,
            // ...
        }
    },
    {
        "name": "sprite2",
        // ...

less_retina

Output retina CSS variables as LESSvariables.

Options:

Handlebars blocks:

We extend from the lesstemplateand have its blocks. There are no new sections for retina data.

Example:

@sprite1-name: 'sprite1';
@sprite1-x: 0px;
@sprite1-y: 0px;
@sprite1-offset-x: 0px;
@sprite1-offset-y: 0px;
@sprite1-total-width: 80px;
@sprite1-total-height: 100px;
// ...
@sprite2-2x-total-width: 160px;
@sprite2-2x-total-height: 200px;
@sprite2-2x-image: 'nested/dir/spritesheet@2x.png';
@sprite2-2x: 0px 0px 0px 0px 20px 40px 160px 200px 'nested/dir/spritesheet@2x.png' 'sprite2@2x';
// ...
@sprite3-group: 'sprite3' @sprite3 @sprite3-2x;
@retina-groups: @sprite1-group @sprite2-group @sprite3-group;
// ...

sass_retina

Output retina CSS variables as SASSvariables and mixins.

Options:

Handlebars blocks:

We extend from the sasstemplateand have its blocks. There are no new sections for retina data.

Example:

$sprite1-name: 'sprite1'
$sprite1-x: 0px
$sprite1-y: 0px
$sprite1-offset-x: 0px
$sprite1-total-width: 80px
$sprite1-total-height: 100px
// ...
$sprite2-2x-total-width: 160px
$sprite2-2x-total-height: 200px
$sprite2-2x-image: 'nested/dir/spritesheet@2x.png'
$sprite2-2x: (20px, 40px, -20px, -40px, 40px, 60px, 160px, 200px, 'nested/dir/spritesheet@2x.png', 'sprite2@2x', )
// ...
$sprite3-group: ('sprite3', $sprite3, $sprite3-2x, )
$retina-groups: ($sprite1-group, $sprite2-group, $sprite3-group, )
// ...

scss_retina

Output retina CSS variables as SCSSvariables and mixins.

Options:

Handlebars blocks:

We extend from the scsstemplateand have its blocks. There are no new sections for retina data.

Example:

$sprite1-name: 'sprite1';
$sprite1-x: 0px;
$sprite1-y: 0px;
$sprite1-offset-x: 0px;
$sprite1-total-width: 80px;
$sprite1-total-height: 100px;
// ...
$sprite2-2x-total-width: 160px;
$sprite2-2x-total-height: 200px;
$sprite2-2x-image: 'nested/dir/spritesheet@2x.png';
$sprite2-2x: (20px, 40px, -20px, -40px, 40px, 60px, 160px, 200px, 'nested/dir/spritesheet@2x.png', 'sprite2@2x', );
// ...
$sprite3-group: ('sprite3', $sprite3, $sprite3-2x, );
$retina-groups: ($sprite1-group, $sprite2-group, $sprite3-group, );
// ...

scss_maps_retina

Output retina CSS variables as SCSSmaps variables.

Options:

Handlebars blocks:

We extend from the scss_mapstemplateand have its blocks. There are no new sections for retina data.

Example:

$sprite1: (
  name: 'sprite1',
  x: 0px,
  y: 0px,
  offset_x: 0px,
  offset_y: 0px,
  total_width: 80px,
  total_height: 100px,
  // ...
);
$sprite2: (
  // ...
  total-width: 160px,
  total-height: 200px,
  image: 'nested/dir/spritesheet@2x.png'
);
// ...
$sprite3-group: (
  name: 'sprite3',
  normal: $sprite3,
  retina: $sprite3-2x
);
$retina-groups: ($sprite1-group, $sprite2-group, $sprite3-group, );
// ...

stylus_retina

Output retina CSS variables as Stylusvariables and mixins.

Options:

Handlebars blocks:

We extend from the stylustemplateand have its blocks. There are no new sections for retina data.

Example:

$sprite1_name = 'sprite1';
$sprite1_x = 0px;
$sprite1_y = 0px;
$sprite1_offset_x = 0px;
$sprite1_offset_y = 0px;
$sprite1_total_width = 80px;
$sprite1_total_height = 100px;
// ...
$sprite2_2x_total_width = 160px;
$sprite2_2x_total_height = 200px;
$sprite2_2x_image = 'nested/dir/spritesheet@2x.png';
$sprite2_2x = 20px 40px -20px -40px 40px 60px 160px 200px 'nested/dir/spritesheet@2x.png' 'sprite2@2x';
// ...
$sprite3_group = 'sprite3' $sprite3 $sprite3_2x;
$retina_groups = $sprite1_group $sprite2_group $sprite3_group;
// ...

Custom

Custom templates can be added dynamically via templater.addTemplateand templater.addHandlebarsTemplate.

Template data

The parameters passed into your template are known as data. These are a cloned copy of the dataoriginally passed in. We add some normalized properties for your convenience.

  • data Object- Data available to template
    • items Object[]- Deprecated alias for data.sprites
    • sprites Object[]- Array of objects with coordinate data about each sprite on the spritesheet
        • Object- Container for sprite coordinate data
          • For reference, *symbolizes any index (e.g. data.sprites[0])
          • name String- Name to use for the image
          • x Number- Horizontal coordinate of top-left corner of image
          • y Number- Vertical coordinate of top-left corner of image
          • width Number- Horizontal length of image in pixels
          • height Number- Vertical length of image in pixels
          • total_width Number- Width of entire spritesheet
          • total_height Number- Height of entire spritesheet
          • image String- URL path to spritesheet
          • escaped_image String- URL encoded image
          • offset_x Number- Negative value of x. Useful to background-position
          • offset_y Number- Negative value of y. Useful to background-position
          • px Object- Container for numeric values including px
            • x String- xsuffixed with px
            • y String- ysuffixed with px
            • width String- widthsuffixed with px
            • height String- heightsuffixed with px
            • total_width String- total_widthsuffixed with px
            • total_height String- total_heightsuffixed with px
            • offset_x String- offset_xsuffixed with px
            • offset_y String- offset_ysuffixed with px
    • spritesheet Object- Information about spritesheet
      • name String- Deprecated alias for spritesheet_info.name
      • width Number- Horizontal length of image in pixels
      • height Number- Vertical length of image in pixels
      • image String- URL to use for spritesheet
        • This will typically be used in background-image
        • For example, background-image: url({{spritesheet.image}});
      • escaped_image String- URL encoded image
      • px Objectcontainer for numeric values including px
        • width String- widthsuffixed with px
        • height String- heightsuffixed with px
    • spritesheet_name String- Deprecated alias for spritesheet_info.name
    • spritesheet_info Object- Container for information about spritesheetand its representation
      • name String- Name for spritesheet
    • options Mixed- Options to passed through via options.formatOpts
    • If we have retina parameters were passed in, then we prepare additional retina properties as well
Handlebars template data

We provide an extra set of data for handlebarstemplates for variable/string names.

  • data.sprites[*].strings Object- Container for sprite-relevant variable/string names
    • Each of these strings will be transformed via variableNameTransforms
    • name String- Transformed name of sprite (e.g. icon-home)
    • name_name String- Transformed combination of sprite name and -namestring (e.g. icon-home-name)
    • name_x String- Transformed combination of sprite name and -xstring (e.g. icon-home-x)
    • name_y String- Transformed combination of sprite name and -ystring (e.g. icon-home-y)
    • name_offset_x String- Transformed combination of sprite name and -offset-xstring (e.g. icon-home-offset-x)
    • name_offset_y String- Transformed combination of sprite name and -offset-ystring (e.g. icon-home-offset-y)
    • name_width String- Transformed combination of sprite name and -widthstring (e.g. icon-home-width)
    • name_height String- Transformed combination of sprite name and -heightstring (e.g. icon-home-height)
    • name_total_width String- Transformed combination of sprite name and -total-widthstring (e.g. icon-home-total-width)
    • name_total_height String- Transformed combination of sprite name and -total-heightstring (e.g. icon-home-total-height)
    • name_image String- Transformed combination of sprite name and -imagestring (e.g. icon-home-image)
    • name_sprites String- Transformed combination of sprite name and -spritesstring (e.g. icon-home-sprites)
    • name_group String- Transformed combination of sprite name and -groupstring (e.g. icon-home-group)
    • name_group_name String- Transformed combination of sprite name and -group-namestring (e.g. icon-home-group-name)
    • name_normal String- Transformed combination of sprite name and -normalstring (e.g. icon-home-normal)
    • name_retina String- Transformed combination of sprite name and -retinastring (e.g. icon-home-retina)
    • bare_name String- Transformed word for name
    • bare_x String- Transformed word for x
    • bare_y String- Transformed word for y
    • bare_offset_x String- Transformed word for offset-x
    • bare_offset_y String- Transformed word for offset-y
    • bare_width String- Transformed word for width
    • bare_height String- Transformed word for height
    • bare_total_width String- Transformed word for total-width
    • bare_total_height String- Transformed word for total-height
    • bare_image String- Transformed word for image
    • bare_sprites String- Transformed word for sprites
    • bare_group String- Transformed word for group
    • bare_group_name String- Transformed word for group-name
    • bare_normal String- Transformed word for normal
    • bare_retina String- Transformed word for retina
  • data.spritesheet.strings Object- Deprecated container for spritesheet-relevant variable/string names
    • Contents will match the same as data.spritesheet_info.strings
  • data.spritesheet_info.strings Object- Container for spritesheet-relevant variable/string names
    • Each of these strings will be transformed via variableNameTransforms
    • name String- Transformed name of spritesheet (e.g. icon-home)
    • name_name String- Transformed combination of spritesheet name and -namestring (e.g. icon-home-name)
    • name_x String- Transformed combination of spritesheet name and -xstring (e.g. icon-home-x)
    • name_y String- Transformed combination of spritesheet name and -ystring (e.g. icon-home-y)
    • name_offset_x String- Transformed combination of spritesheet name and -offset-xstring (e.g. icon-home-offset-x)
    • name_offset_y String- Transformed combination of spritesheet name and -offset-ystring (e.g. icon-home-offset-y)
    • name_width String- Transformed combination of spritesheet name and -widthstring (e.g. icon-home-width)
    • name_height String- Transformed combination of spritesheet name and -heightstring (e.g. icon-home-height)
    • name_total_width String- Transformed combination of spritesheet name and -total-widthstring (e.g. icon-home-total-width)
    • name_total_height String- Transformed combination of spritesheet name and -total-heightstring (e.g. icon-home-total-height)
    • name_image String- Transformed combination of spritesheet name and -imagestring (e.g. icon-home-image)
    • name_sprites String- Transformed combination of spritesheet name and -spritesstring (e.g. icon-home-sprites)
    • name_group String- Transformed combination of spritesheet name and -groupstring (e.g. icon-home-group)
    • name_group_name String- Transformed combination of spritesheet name and -group-namestring (e.g. icon-home-group-name)
    • name_normal String- Transformed combination of spritesheet and -normalstring (e.g. icon-home-normal)
    • name_retina String- Transformed combination of spritesheet and -retinastring (e.g. icon-home-retina)
    • bare_name String- Transformed word for name
    • bare_x String- Transformed word for x
    • bare_y String- Transformed word for y
    • bare_offset_x String- Transformed word for offset-x
    • bare_offset_y String- Transformed word for offset-y
    • bare_width String- Transformed word for width
    • bare_height String- Transformed word for height
    • bare_total_width String- Transformed word for total-width
    • bare_total_height String- Transformed word for total-height
    • bare_image String- Transformed word for image
    • bare_sprites String- Transformed word for sprites
    • bare_group String- Transformed word for group
    • bare_group_name String- Transformed word for group-name
    • bare_normal String- Transformed word for normal
    • bare_retina String- Transformed word for retina
  • data.strings Object- Container for generic strings
    • Each of these strings will be transformed via variableNameTransforms
    • bare_name String- Transformed word for name
    • bare_x String- Transformed word for x
    • bare_y String- Transformed word for y
    • bare_offset_x String- Transformed word for offset-x
    • bare_offset_y String- Transformed word for offset-y
    • bare_width String- Transformed word for width
    • bare_height String- Transformed word for height
    • bare_total_width String- Transformed word for total-width
    • bare_total_height String- Transformed word for total-height
    • bare_image String- Transformed word for image
    • bare_sprites String- Transformed word for sprites
    • bare_group String- Transformed word for group
    • bare_group_name String- Transformed word for group-name
    • bare_normal String- Transformed word for normal
    • bare_retina String- Transformed word for retina
Retina template data

These are additional properties of the template data when retina parameters have been passed in (e.g. retina_sprites, retina_groups). As with the normal data, it is cloned copy of the original data with additional properties for convenience.

  • data Object- Same container as defined above
    • retina_sprites Object[]- Array of objects with coordinate data about each retina sprite for the retina spritesheet
      • Properties are retina equivalent of data.sprites(e.g. name, x, offset_y, px)
    • retina_spritesheet Object- Information about retina spritesheet
      • Properties are retina equivalent of data.spritesheet(e.g. width, image, px)
        • We do not provide retina_spritesheet.nameas nameis deprecated
    • retina_spritesheet_info Object- Optional container for metadata about retina_spritesheetand its representation
      • Properties are retina equivalent of data.spritesheet_info(e.g. name)
    • retina_groups Object[]- Array of objects that maps to normal and retina sprites
        • Object- Container for data about sprite mapping
          • name String- Name to refer to mapping by
          • index Number- Index of corresponding normal/retina sprites from data.sprites/data.retina_sprites
          • normal Object- Normal sprite from data.spritesthat corresponds to our mapping
            • This has all the same properties as data.sprites[*](e.g. name, x, offset_y, px)
          • retina Object- Retina sprite from data.retina_spritesthat corresponds to our mapping
            • This has all the same properties as data.retina_sprites[*](e.g. name, x, offset_y, px)
    • retina_groups_info Object- Optional container for metadata about retina_groupsand its representation
      • name String- Name for retina_groups
Retina Handlebars template data

Retina specific properties will have the same corresponding new data for Handlebars templates

  • data.retina_sprites[*].strings Object- Container for retina sprite-relevant variable/string names
    • Each of these strings will be transformed via variableNameTransforms
    • Properties are retina equivalent of data.sprites[*].strings(e.g. name, name_name, bare_name)
  • data.retina_spritesheet_info.strings Object- Container for retina spritesheet-relevant variable/string names
    • Each of these strings will be transformed via variableNameTransforms
    • Properties are retina equivalent of data.spritesheet_info.strings(e.g. name, name_sprites, bare_name)
  • data.retina_groups[*].strings Object- Container for group-relevant variable/string names
    • Each of these strings will be transformed via variableNameTransforms
    • name String- Transformed name of retina group (e.g. icon-home)
    • name_name String- Transformed combination of retina group name and -namestring (e.g. icon-home-name)
    • name_x String- Transformed combination of retina group name and -xstring (e.g. icon-home-x)
    • name_y String- Transformed combination of retina group name and -ystring (e.g. icon-home-y)
    • name_offset_x String- Transformed combination of retina group name and -offset-xstring (e.g. icon-home-offset-x)
    • name_offset_y String- Transformed combination of retina group name and -offset-ystring (e.g. icon-home-offset-y)
    • name_width String- Transformed combination of retina group name and -widthstring (e.g. icon-home-width)
    • name_height String- Transformed combination of retina group name and -heightstring (e.g. icon-home-height)
    • name_total_width String- Transformed combination of retina group name and -total-widthstring (e.g. icon-home-total-width)
    • name_total_height String- Transformed combination of retina group name and -total-heightstring (e.g. icon-home-total-height)
    • name_image String- Transformed combination of retina group name and -imagestring (e.g. icon-home-image)
    • name_sprites String- Transformed combination of retina group name and -spritesstring (e.g. icon-home-sprites)
    • name_group String- Transformed combination of retina group name and -groupstring (e.g. icon-home-group)
    • name_group_name String- Transformed combination of retina group name and -group-namestring (e.g. icon-home-group-name)
    • name_normal String- Transformed combination of retina group name and -normalstring (e.g. icon-home-normal)
    • name_retina String- Transformed combination of retina group name and -retinastring (e.g. icon-home-retina)
    • bare_name String- Transformed word for name
    • bare_x String- Transformed word for x
    • bare_y String- Transformed word for y
    • bare_offset_x String- Transformed word for offset-x
    • bare_offset_y String- Transformed word for offset-y
    • bare_width String- Transformed word for width
    • bare_height String- Transformed word for height
    • bare_total_width String- Transformed word for total-width
    • bare_total_height String- Transformed word for total-height
    • bare_image String- Transformed word for image
    • bare_sprites String- Transformed word for sprites
    • bare_group String- Transformed word for group
    • bare_group_name String- Transformed word for group-name
    • bare_normal String- Transformed word for normal
    • bare_retina String- Transformed word for retina
  • data.retina_groups_info.strings Object- Container for retina groups relevant variable/string names
    • Each of these strings will be transformed via variableNameTransforms
    • name String- Transformed name of retina groups (e.g. icon-home)
    • name_name String- Transformed combination of retina groups name and -namestring (e.g. icon-home-name)
    • name_x String- Transformed combination of retina groups name and -xstring (e.g. icon-home-x)
    • name_y String- Transformed combination of retina groups name and -ystring (e.g. icon-home-y)
    • name_offset_x String- Transformed combination of retina groups name and -offset-xstring (e.g. icon-home-offset-x)
    • name_offset_y String- Transformed combination of retina groups name and -offset-ystring (e.g. icon-home-offset-y)
    • name_width String- Transformed combination of retina groups name and -widthstring (e.g. icon-home-width)
    • name_height String- Transformed combination of retina groups name and -heightstring (e.g. icon-home-height)
    • name_total_width String- Transformed combination of retina groups name and -total-widthstring (e.g. icon-home-total-width)
    • name_total_height String- Transformed combination of retina groups name and -total-heightstring (e.g. icon-home-total-height)
    • name_image String- Transformed combination of retina groups name and -imagestring (e.g. icon-home-image)
    • name_sprites String- Transformed combination of retina groups name and -spritesstring (e.g. icon-home-sprites)
    • name_group String- Transformed combination of retina groups name and -groupstring (e.g. icon-home-group)
    • name_group_name String- Transformed combination of retina groups name and -group-namestring (e.g. icon-home-group-name)
    • name_normal String- Transformed combination of retina groups name and -normalstring (e.g. icon-home-normal)
    • name_retina String- Transformed combination of retina groups name and -retinastring (e.g. icon-home-retina)
    • bare_name String- Transformed word for name
    • bare_x String- Transformed word for x
    • bare_y String- Transformed word for y
    • bare_offset_x String- Transformed word for offset-x
    • bare_offset_y String- Transformed word for offset-y
    • bare_width String- Transformed word for width
    • bare_height String- Transformed word for height
    • bare_total_width String- Transformed word for total-width
    • bare_total_height String- Transformed word for total-height
    • bare_image String- Transformed word for image
    • bare_sprites String- Transformed word for sprites
    • bare_group String- Transformed word for group
    • bare_group_name String- Transformed word for group-name
    • bare_normal String- Transformed word for normal
    • bare_retina String- Transformed word for retina
templater.addTemplate(name, fn)

Method to define a custom template under the format of name.

  • name String- Key to store template under for reference via options.format
  • fn Function- Template function
    • Should have signature of function (data)and return a Stringoutput
templater.addHandlebarsTemplate(name, tmplStr)

Method to define a custom handlebars template under the format of name.

As noted in the Templates section, these can inherit from existing templates via handlebars-layoutsconventions (e.g. {{#extend "scss"}}). An example can be found in the Examples section.

  • name String- Key to store template under for reference via options.format
  • tmplStr String- Handlebars template to use for formatting
    • This will receive dataas its data(e.g. {{sprites}}is data.sprites)
templater.addMustacheTemplate(name, tmplStr)

Deprecated alias for templater.addHandlebarsTemplate

Examples

Retina configuration

In this example, we will process a template with retina data.

var templater = require('spritesheet-templates');
templater({
  sprites: [{
    name: 'github', x: 0, y: 0, width: 10, height: 20
  }, {
    name: 'twitter', x: 10, y: 20, width: 20, height: 30
  }, {
    name: 'rss', x: 30, y: 50, width: 50, height: 50
  }],
  // Note that the retina sprites are in the same order as `sprites`
  retina_sprites: [{
    name: 'github@2x', x: 0, y: 0, width: 20, height: 40
  }, {
    name: 'twitter@2x', x: 20, y: 40, width: 40, height: 60
  }, {
    name: 'rss@2x', x: 60, y: 100, width: 100, height: 100
  }],
  spritesheet: {
    width: 80, height: 100, image: 'url/path/to/spritesheet.png'
  },
  retina_spritesheet: {
    width: 160, height: 200, image: 'url/path/to/spritesheet@2x.png'
  },
  retina_groups: [{
    name: 'github', index: 0
  }, {
    name: 'twitter', index: 1
  }, {
    name: 'rss', index: 2
  }]
}, {format: 'scss_retina'}); /*
$github-name: 'github';
$github-x: 0px;
...
$twitter-2x-name: 'twitter@2x';
$twitter-2x-x: 20px;
...
$rss-group-name: 'rss';
$rss-group: ('rss', $rss, $rss-2x, );
$retina-groups: ($github-group, $twitter-group, $rss-group, );
*/

Inheriting from a template

In this example, we will extend the SCSS template to output a minimal set of template data.

It should be noted that we must include the JSON front matter from the original template we are inheriting from to preserve default casing and options.

scss-minimal.handlebars:

{
  // Default options
  'functions': true,
  'variableNameTransforms': ['dasherize']
}

{{#extend "scss"}}
{{#content "sprites"}}
{{#each sprites}}
${{strings.name}}: ({{px.x}}, {{px.y}}, {{px.offset_x}}, {{px.offset_y}}, {{px.width}}, {{px.height}}, {{px.total_width}}, {{px.total_height}}, '{{{escaped_image}}}', '{{name}}', );
{{/each}}
{{/content}}
{{#content "spritesheet"}}
${{spritesheet_info.strings.name_sprites}}: ({{#each sprites}}${{strings.name}}, {{/each}});
${{spritesheet_info.strings.name}}: ({{spritesheet.px.width}}, {{spritesheet.px.height}}, '{{{spritesheet.escaped_image}}}', ${{spritesheet_info.strings.name_sprites}}, );
{{/content}}
{{/extend}}

index.js:

// Load in our dependencies
var fs = require('fs');
var templater = require('spritesheet-templates');

// Register our new template
var scssMinimalHandlebars = fs.readFileSync('scss-minimal.handlebars', 'utf8');
templater.addHandlebarsTemplate('scss-minimal', scssMinimalHandlebars);

// Run our templater
templater({
  sprites: [{
    name: 'github', x: 0, y: 0, width: 10, height: 20
  }, {
    name: 'twitter', x: 10, y: 20, width: 20, height: 30
  }, {
    name: 'rss', x: 30, y: 50, width: 50, height: 50
  }],
  spritesheet: {
    width: 80, height: 100, image: 'url/path/to/spritesheet.png'
  }
}, {format: 'scss-minimal'}); /*
$github: (0px, 0px, 0px, 0px, 10px, 20px, 80px, 100px, 'url/path/to/spritesheet.png', 'github', );
$twitter: (10px, 20px, -10px, -20px, 20px, 30px, 80px, 100px, 'url/path/to/spritesheet.png', 'twitter', );
$rss: (30px, 50px, -30px, -50px, 50px, 50px, 80px, 100px, 'url/path/to/spritesheet.png', 'rss', );
$spritesheet-sprites: ($github, $twitter, $rss, );
$spritesheet: (80px, 100px, 'url/path/to/spritesheet.png', $spritesheet-sprites, );
*/

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 npm run lintand test via npm test.

Donating

Support this project and others by twolfsonvia donations.

http://twolfson.com/support-me

Unlicense

As of Sep 08 2013, Todd Wolfson has released this repository and its contents to the public domain.

It has been released under the UNLICENSE.

Prior to Sep 08 2013, this repository and its contents were licensed under the MIT license.

HomePage

https://github.com/twolfson/spritesheet-templates

Repository

https://github.com/twolfson/spritesheet-templates


上一篇:eight-track-normalize-multipart
下一篇:JS数据结构与算法_栈&队列

相关推荐

  • x-templates

    simple dom based templating of JSON and DOM trees using css selectors Build Status(https://travisci...

    4 个月前
  • uri-templates

    URI Templates (RFC6570) including desubstitution uritemplates URI Templates (RFC6570(http://tools...

    1 年前
  • the-templates

    Templates for theprojects thetemplates ========== Build Statusbdtravisshieldurlbdtravisurl np...

    20 天前
  • templates.js

    An ultralight and super fast templating framework Build Status(https://travisci.org/psychobunny/...

    9 个月前
  • templates

    System for creating and managing template collections, and rendering templates with any node.js temp...

    2 年前
  • swig-templates

    A simple, powerful, and extendable templating engine for node.js and browsers, similar to Django, Ji...

    2 年前
  • swig-email-templates

    Node.js module for rendering emails with swig templates and emailfriendly inline CSS swigemailtemp...

    9 个月前
  • sg-templates

    Templates for SUGOS sgtemplates ========== Build Statusbdtravisshieldurlbdtravisurl npm Versi...

    2 个月前
  • react-templates

    Light weight templates for react write html get valid react code NPM versionnpmimagenpmurl build s...

    7 个月前
  • raptor-templates

    Raptor Templates Raptor Templates ================ Raptor Templates is an extensible, streaming, a...

    8 个月前

官方社区

扫码加入 JavaScript 社区