fx-spritesheet-templates
Advanced tools
Convert spritesheet data into CSS or CSS pre-processor data
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.
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);
}
*/
spritesheet-templates is exports the funciton templater as its module.exports.
templater(data, options)Converter for spritesheet/sprite info into spritesheet
Object - Container for data for template
Object[] - Deprecated alternative key to define data.spritesObject[] - Array of objects with coordinate data about each sprite on the spritesheet
Object - Container for sprite coordinate data
* symbolizes any index (e.g. data.sprites[0])String - Name to use for the imageNumber - Horizontal coordinate of top-left corner of imageNumber - Vertical coordinate of top-left corner of imageNumber - Horizontal length of image in pixelsNumber - Vertical length of image in pixelsObject - Information about spritesheet
Number - Horizontal length of image in pixelsNumber - Vertical length of image in pixelsString - URL to use for spritesheet
background-imagebackground-image: url({{spritesheet.image}});Object - Optional container for metadata about spritesheet and its representation
String - Prefix to use for all spritesheet variables
icons will generate $icons-width/$icons-image/etc in a SCSS templatespritesheet (e.g. $spritesheet-width, $spritesheet-image)retina templates are documented in the Retina parameters sectionObject - Optional settings
String - Deprecated alternative for spritesheet_info.nameString - Format to generate output in
css formatMixed - Options to pass through to the formatterReturns:
String - Result from specified formatterretina templates require additional parameters data.retina_sprites, data.retina_spritesheet and data.retina_groups to 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}]).
Object - Same container as defined above
Object[] - Array of objects with coordinate data about each retina sprite for the retina spritesheet
data.spritesObject - Information about retina spritesheet
data.spritesheetObject - Optional container for metadata about retina_spritesheet and its representation
String - Prefix to use for all retina spritesheet variables
retina-icons will generate $retina-icons-width/$retina-icons-image/etc in a SCSS templateretina-spritesheet (e.g. $retina-spritesheet-width, $retina-spritesheet-image)Object[] - Array of objects that maps to normal and retina sprites
Object - Container for data about sprite mapping
String - Name to refer to mapping by
Number - Index to look up corresponding normal/retina sprites from data.sprites/data.retina_spritesObject - Optional container for metadata about retina_groups and its representation
String - Name to use for retina_groups variable
icon-groups will generate $icons-groups in a SCSS templateretina-groups (e.g. $retina-groups)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 section for convenience.
cssOuput CSS variables as CSS rules.
Options:
Function - Override mapping for CSS selector
cssSelector should have signature function (sprite) { return 'selector'; }'.icon-' + sprite.namesprite with all parameters designed for templateHandlebars blocks:
css is a Handlebars based template. We allow for overriding the following sections:
{{#content "sprites-comment"}} - Comment before CSS rules{{#content "sprites"}} - CSS rulesExample:
.icon-sprite1 {
background-image: url(nested/dir/spritesheet.png);
background-position: 0px 0px;
width: 10px;
height: 20px;
}
.icon-sprite2 {
/* ... */
jsonOutput 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_arrayOutput 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_textureOutput 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 basename of a given image. spritesmith provides 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_image nor spriteframe is used, then sprite.name will be used.
For integration in grunt-spritesmith/gulp.spritesmith, please see their cssVarMap documentation.
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
}
}
}
lessOutput CSS variables as LESS variables.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['dasherize'] which yields a dash-case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
less is 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 variablesExample:
@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';
// ...
sassOutput CSS variables as SASS variables.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['dasherize'] which yields a dash-case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
sass is 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 variablesExample:
$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'
// ...
scssOutput CSS variables as SCSS variables.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['dasherize'] which yields a dash-case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
scss is 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 variablesExample:
$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_mapsOutput CSS variables as SCSS maps variables.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['underscored'] which yields a snake_case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
scss_maps is 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 variablesExample:
$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: (
// ...
stylusOutput CSS variables as Stylus variables.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['underscored'] which yields a snake_case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
stylus is 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 variablesExample:
$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';
// ...
These are a subset of templates that support retina spritesheets. These require retina parameters like retina_sprites are provided in order to work properly.
css_retinaOuput CSS variables as CSS rules with media query and additional rules for retina support.
Options:
Function - Override mapping for CSS selector
cssSelector should have signature function (retinaGroup) { return 'selector'; }'.icon-' + retinaGroup.nameretinaGroup with all parameters designed for retina_groups[*] in templates (e.g. name, normal, retina)Handlebars blocks:
We extend from the css template and 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_retinaOutput 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_retinaOutput 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_retinaOutput retina CSS variables as LESS variables.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['dasherize'] which yields a dash-case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
We extend from the less template and 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_retinaOutput retina CSS variables as SASS variables and mixins.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['dasherize'] which yields a dash-case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
We extend from the sass template and 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_retinaOutput retina CSS variables as SCSS variables and mixins.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['dasherize'] which yields a dash-case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
We extend from the scss template and 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_retinaOutput retina CSS variables as SCSS maps variables.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['underscored'] which yields a snake_case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
We extend from the scss_maps template and 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_retinaOutput retina CSS variables as Stylus variables and mixins.
Options:
Boolean - Flag to include mixins or not
true (mixins will be included)String[] - Array of underscore.string methods to run on variable names
['camelize'] would transform icon-home-x to iconHomeX['underscored'] which yields a snake_case nameunderscore.string: http://epeli.github.io/underscore.string/#api
chain which allows for toUpperCase and toLowerCaseHandlebars blocks:
We extend from the stylus template and 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 templates can be added dynamically via templater.addTemplate and templater.addHandlebarsTemplate.
The parameters passed into your template are known as data. These are a cloned copy of the data originally passed in. We add some normalized properties for your convenience.
Object - Data available to template
Object[] - Deprecated alias for data.spritesObject[] - Array of objects with coordinate data about each sprite on the spritesheet
Object - Container for sprite coordinate data
* symbolizes any index (e.g. data.sprites[0])String - Name to use for the imageNumber - Horizontal coordinate of top-left corner of imageNumber - Vertical coordinate of top-left corner of imageNumber - Horizontal length of image in pixelsNumber - Vertical length of image in pixelsNumber - Width of entire spritesheetNumber - Height of entire spritesheetString - URL path to spritesheetString - URL encoded imageNumber - Negative value of x. Useful to background-positionNumber - Negative value of y. Useful to background-positionObject - Container for numeric values including px
String - x suffixed with pxString - y suffixed with pxString - width suffixed with pxString - height suffixed with pxString - total_width suffixed with pxString - total_height suffixed with pxString - offset_x suffixed with pxString - offset_y suffixed with pxObject - Information about spritesheet
String - Deprecated alias for spritesheet_info.nameNumber - Horizontal length of image in pixelsNumber - Vertical length of image in pixelsString - URL to use for spritesheet
background-imagebackground-image: url({{spritesheet.image}});String - URL encoded imageObject container for numeric values including px
String - width suffixed with pxString - height suffixed with pxString - Deprecated alias for spritesheet_info.nameObject - Container for information about spritesheet and its representation
String - Name for spritesheetMixed - Options to passed through via options.formatOptsWe provide an extra set of data for handlebars templates for variable/string names.
Object - Container for sprite-relevant variable/string names
variableNameTransformsString - Transformed name of sprite (e.g. icon-home)String - Transformed combination of sprite name and -name string (e.g. icon-home-name)String - Transformed combination of sprite name and -x string (e.g. icon-home-x)String - Transformed combination of sprite name and -y string (e.g. icon-home-y)String - Transformed combination of sprite name and -offset-x string (e.g. icon-home-offset-x)String - Transformed combination of sprite name and -offset-y string (e.g. icon-home-offset-y)String - Transformed combination of sprite name and -width string (e.g. icon-home-width)String - Transformed combination of sprite name and -height string (e.g. icon-home-height)String - Transformed combination of sprite name and -total-width string (e.g. icon-home-total-width)String - Transformed combination of sprite name and -total-height string (e.g. icon-home-total-height)String - Transformed combination of sprite name and -image string (e.g. icon-home-image)String - Transformed combination of sprite name and -sprites string (e.g. icon-home-sprites)String - Transformed combination of sprite name and -group string (e.g. icon-home-group)String - Transformed combination of sprite name and -group-name string (e.g. icon-home-group-name)String - Transformed combination of sprite name and -normal string (e.g. icon-home-normal)String - Transformed combination of sprite name and -retina string (e.g. icon-home-retina)String - Transformed word for nameString - Transformed word for xString - Transformed word for yString - Transformed word for offset-xString - Transformed word for offset-yString - Transformed word for widthString - Transformed word for heightString - Transformed word for total-widthString - Transformed word for total-heightString - Transformed word for imageString - Transformed word for spritesString - Transformed word for groupString - Transformed word for group-nameString - Transformed word for normalString - Transformed word for retinaObject - Deprecated container for spritesheet-relevant variable/string names
data.spritesheet_info.stringsObject - Container for spritesheet-relevant variable/string names
variableNameTransformsString - Transformed name of spritesheet (e.g. icon-home)String - Transformed combination of spritesheet name and -name string (e.g. icon-home-name)String - Transformed combination of spritesheet name and -x string (e.g. icon-home-x)String - Transformed combination of spritesheet name and -y string (e.g. icon-home-y)String - Transformed combination of spritesheet name and -offset-x string (e.g. icon-home-offset-x)String - Transformed combination of spritesheet name and -offset-y string (e.g. icon-home-offset-y)String - Transformed combination of spritesheet name and -width string (e.g. icon-home-width)String - Transformed combination of spritesheet name and -height string (e.g. icon-home-height)String - Transformed combination of spritesheet name and -total-width string (e.g. icon-home-total-width)String - Transformed combination of spritesheet name and -total-height string (e.g. icon-home-total-height)String - Transformed combination of spritesheet name and -image string (e.g. icon-home-image)String - Transformed combination of spritesheet name and -sprites string (e.g. icon-home-sprites)String - Transformed combination of spritesheet name and -group string (e.g. icon-home-group)String - Transformed combination of spritesheet name and -group-name string (e.g. icon-home-group-name)String - Transformed combination of spritesheet and -normal string (e.g. icon-home-normal)String - Transformed combination of spritesheet and -retina string (e.g. icon-home-retina)String - Transformed word for nameString - Transformed word for xString - Transformed word for yString - Transformed word for offset-xString - Transformed word for offset-yString - Transformed word for widthString - Transformed word for heightString - Transformed word for total-widthString - Transformed word for total-heightString - Transformed word for imageString - Transformed word for spritesString - Transformed word for groupString - Transformed word for group-nameString - Transformed word for normalString - Transformed word for retinaObject - Container for generic strings
variableNameTransformsString - Transformed word for nameString - Transformed word for xString - Transformed word for yString - Transformed word for offset-xString - Transformed word for offset-yString - Transformed word for widthString - Transformed word for heightString - Transformed word for total-widthString - Transformed word for total-heightString - Transformed word for imageString - Transformed word for spritesString - Transformed word for groupString - Transformed word for group-nameString - Transformed word for normalString - Transformed word for retinaThese 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.
Object - Same container as defined above
Object[] - Array of objects with coordinate data about each retina sprite for the retina spritesheet
data.sprites (e.g. name, x, offset_y, px)Object - Information about retina spritesheet
data.spritesheet (e.g. width, image, px)
retina_spritesheet.name as name is deprecatedObject - Optional container for metadata about retina_spritesheet and its representation
data.spritesheet_info (e.g. name)Object[] - Array of objects that maps to normal and retina sprites
Object - Container for data about sprite mapping
String - Name to refer to mapping byNumber - Index of corresponding normal/retina sprites from data.sprites/data.retina_spritesObject - Normal sprite from data.sprites that corresponds to our mapping
data.sprites[*] (e.g. name, x, offset_y, px)Object - Retina sprite from data.retina_sprites that corresponds to our mapping
data.retina_sprites[*] (e.g. name, x, offset_y, px)Object - Optional container for metadata about retina_groups and its representation
String - Name for retina_groupsRetina specific properties will have the same corresponding new data for Handlebars templates
Object - Container for retina sprite-relevant variable/string names
variableNameTransformsdata.sprites[*].strings (e.g. name, name_name, bare_name)Object - Container for retina spritesheet-relevant variable/string names
variableNameTransformsdata.spritesheet_info.strings (e.g. name, name_sprites, bare_name)Object - Container for group-relevant variable/string names
variableNameTransformsString - Transformed name of retina group (e.g. icon-home)String - Transformed combination of retina group name and -name string (e.g. icon-home-name)String - Transformed combination of retina group name and -x string (e.g. icon-home-x)String - Transformed combination of retina group name and -y string (e.g. icon-home-y)String - Transformed combination of retina group name and -offset-x string (e.g. icon-home-offset-x)String - Transformed combination of retina group name and -offset-y string (e.g. icon-home-offset-y)String - Transformed combination of retina group name and -width string (e.g. icon-home-width)String - Transformed combination of retina group name and -height string (e.g. icon-home-height)String - Transformed combination of retina group name and -total-width string (e.g. icon-home-total-width)String - Transformed combination of retina group name and -total-height string (e.g. icon-home-total-height)String - Transformed combination of retina group name and -image string (e.g. icon-home-image)String - Transformed combination of retina group name and -sprites string (e.g. icon-home-sprites)String - Transformed combination of retina group name and -group string (e.g. icon-home-group)String - Transformed combination of retina group name and -group-name string (e.g. icon-home-group-name)String - Transformed combination of retina group name and -normal string (e.g. icon-home-normal)String - Transformed combination of retina group name and -retina string (e.g. icon-home-retina)String - Transformed word for nameString - Transformed word for xString - Transformed word for yString - Transformed word for offset-xString - Transformed word for offset-yString - Transformed word for widthString - Transformed word for heightString - Transformed word for total-widthString - Transformed word for total-heightString - Transformed word for imageString - Transformed word for spritesString - Transformed word for groupString - Transformed word for group-nameString - Transformed word for normalString - Transformed word for retinaObject - Container for retina groups relevant variable/string names
variableNameTransformsString - Transformed name of retina groups (e.g. icon-home)String - Transformed combination of retina groups name and -name string (e.g. icon-home-name)String - Transformed combination of retina groups name and -x string (e.g. icon-home-x)String - Transformed combination of retina groups name and -y string (e.g. icon-home-y)String - Transformed combination of retina groups name and -offset-x string (e.g. icon-home-offset-x)String - Transformed combination of retina groups name and -offset-y string (e.g. icon-home-offset-y)String - Transformed combination of retina groups name and -width string (e.g. icon-home-width)String - Transformed combination of retina groups name and -height string (e.g. icon-home-height)String - Transformed combination of retina groups name and -total-width string (e.g. icon-home-total-width)String - Transformed combination of retina groups name and -total-height string (e.g. icon-home-total-height)String - Transformed combination of retina groups name and -image string (e.g. icon-home-image)String - Transformed combination of retina groups name and -sprites string (e.g. icon-home-sprites)String - Transformed combination of retina groups name and -group string (e.g. icon-home-group)String - Transformed combination of retina groups name and -group-name string (e.g. icon-home-group-name)String - Transformed combination of retina groups name and -normal string (e.g. icon-home-normal)String - Transformed combination of retina groups name and -retina string (e.g. icon-home-retina)String - Transformed word for nameString - Transformed word for xString - Transformed word for yString - Transformed word for offset-xString - Transformed word for offset-yString - Transformed word for widthString - Transformed word for heightString - Transformed word for total-widthString - Transformed word for total-heightString - Transformed word for imageString - Transformed word for spritesString - Transformed word for groupString - Transformed word for group-nameString - Transformed word for normalString - Transformed word for retinatemplater.addTemplate(name, fn)Method to define a custom template under the format of name.
String - Key to store template under for reference via options.formatFunction - Template function
function (data) and return a String outputtemplater.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-layouts conventions (e.g. {{#extend "scss"}}). An example can be found in the Examples section.
String - Key to store template under for reference via options.formatString - Handlebars template to use for formatting
data as its data (e.g. {{sprites}} is data.sprites)templater.addMustacheTemplate(name, tmplStr)Deprecated alias for templater.addHandlebarsTemplate
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, );
*/
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, );
*/
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 lint and test via npm test.
Support this project and others by twolfson via gratipay.
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.
FAQs
Convert spritesheet data into CSS or CSS pre-processor data
We found that fx-spritesheet-templates demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.