README
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-templates
exports the function templater
as 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 definedata.sprites
- sprites
Object[]
- Array of objects with coordinate data about each sprite on the spritesheetObject
- 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
- For reference,
- 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}});
- This will typically be used in
- width
- spritesheet_info
Object
- Optional container for metadata aboutspritesheet
and its representation- name
String
- Prefix to use for all spritesheet variables- For example,
icons
will generate$icons-width
/$icons-image
/etc in a SCSS template - By default, this is
spritesheet
(e.g.$spritesheet-width
,$spritesheet-image
)
- For example,
- name
- Additional parameters for
retina
templates are documented in the Retina parameters section
- items
- options
Object
- Optional settings- spritesheetName
String
- Deprecated alternative forspritesheet_info.name
- format
String
- Format to generate output in- We accept any format inside of the Templates section
- Custom formats can be added via the custom methods
- By default, we will use the
css
format
- We accept any format inside of the Templates section
- formatOpts
Mixed
- Options to pass through to the formatter
- spritesheetName
Returns:
- retVal
String
- Result from specified formatter
Retina parameters
retina
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}]
).
- 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
- Properties are retina equivalent of
- retina_spritesheet
Object
- Information about retina spritesheet- Properties are retina equivalent of
data.spritesheet
- Properties are retina equivalent of
- retina_spritesheet_info
Object
- Optional container for metadata aboutretina_spritesheet
and its representation- name
String
- Prefix to use for all retina spritesheet variables- For example,
retina-icons
will 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
)
- For example,
- name
- retina_groups
Object[]
- Array of objects that maps to normal and retina spritesObject
- 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 fromdata.sprites
/data.retina_sprites
- name
- retina_groups_info
Object
- Optional container for metadata aboutretina_groups
and its representation- name
String
- Name to use forretina_groups
variable- For example,
icon-groups
will generate$icons-groups
in a SCSS template - By default, this is
retina-groups
(e.g.$retina-groups
)
- For example,
- name
- retina_sprites
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 section for convenience.
css
Ouput CSS variables as CSS rules.
Options:
- cssSelector
Function
- Override mapping for CSS selectorcssSelector
should have signaturefunction (sprite) { return 'selector'; }
- By default this will return
'.icon-' + sprite.name
- It will receive
sprite
with all parameters designed for template
Handlebars blocks:
css
is 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 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
}
}
}
less
Output CSS variables as LESS variables.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['dasherize']
which yields adash-case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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 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 SASS variables.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['dasherize']
which yields adash-case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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 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 SCSS variables.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['dasherize']
which yields adash-case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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 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 SCSS maps variables.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['underscored']
which yields asnake_case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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 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 Stylus variables.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['underscored']
which yields asnake_case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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 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_sprites
are 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 selectorcssSelector
should have signaturefunction (retinaGroup) { return 'selector'; }
- By default this will return
'.icon-' + retinaGroup.name
- It will receive
retinaGroup
with all parameters designed forretina_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_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 LESS variables.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['dasherize']
which yields adash-case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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_retina
Output retina CSS variables as SASS variables and mixins.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['dasherize']
which yields adash-case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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_retina
Output retina CSS variables as SCSS variables and mixins.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['dasherize']
which yields adash-case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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_retina
Output retina CSS variables as SCSS maps variables.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['underscored']
which yields asnake_case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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_retina
Output retina CSS variables as Stylus variables and mixins.
Options:
- functions
Boolean
- Flag to include mixins or not- By default this is
true
(mixins will be included)
- By default this is
- variableNameTransforms
String[]
- Array ofunderscore.string
methods to run on variable names- For example,
['camelize']
would transformicon-home-x
toiconHomeX
- By default, this is
['underscored']
which yields asnake_case
name underscore.string
: http://epeli.github.io/underscore.string/#api- We use
chain
which allows fortoUpperCase
andtoLowerCase
- http://epeli.github.io/underscore.string/#s-string-gt-chain
- We use
- For example,
Handlebars 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
Custom templates can be added dynamically via templater.addTemplate
and templater.addHandlebarsTemplate
.
Template data
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.
- data
Object
- Data available to template- items
Object[]
- Deprecated alias fordata.sprites
- sprites
Object[]
- Array of objects with coordinate data about each sprite on the spritesheetObject
- 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 encodedimage
- offset_x
Number
- Negative value ofx
. Useful tobackground-position
- offset_y
Number
- Negative value ofy
. Useful tobackground-position
- px
Object
- Container for numeric values includingpx
- x
String
-x
suffixed withpx
- y
String
-y
suffixed withpx
- width
String
-width
suffixed withpx
- height
String
-height
suffixed withpx
- total_width
String
-total_width
suffixed withpx
- total_height
String
-total_height
suffixed withpx
- offset_x
String
-offset_x
suffixed withpx
- offset_y
String
-offset_y
suffixed withpx
- x
- For reference,
- spritesheet
Object
- Information about spritesheet- name
String
- Deprecated alias forspritesheet_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}});
- This will typically be used in
- escaped_image
String
- URL encodedimage
- px
Object
container for numeric values includingpx
- width
String
-width
suffixed withpx
- height
String
-height
suffixed withpx
- width
- name
- spritesheet_name
String
- Deprecated alias forspritesheet_info.name
- spritesheet_info
Object
- Container for information aboutspritesheet
and its representation- name
String
- Name forspritesheet
- name
- options
Mixed
- Options to passed through viaoptions.formatOpts
- If we have retina parameters were passed in, then we prepare additional retina properties as well
- More info can be found on these parameters in Retina template data
- items
Handlebars template data
We provide an extra set of data for handlebars
templates 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-name
string (e.g.icon-home-name
) - name_x
String
- Transformed combination of sprite name and-x
string (e.g.icon-home-x
) - name_y
String
- Transformed combination of sprite name and-y
string (e.g.icon-home-y
) - name_offset_x
String
- Transformed combination of sprite name and-offset-x
string (e.g.icon-home-offset-x
) - name_offset_y
String
- Transformed combination of sprite name and-offset-y
string (e.g.icon-home-offset-y
) - name_width
String
- Transformed combination of sprite name and-width
string (e.g.icon-home-width
) - name_height
String
- Transformed combination of sprite name and-height
string (e.g.icon-home-height
) - name_total_width
String
- Transformed combination of sprite name and-total-width
string (e.g.icon-home-total-width
) - name_total_height
String
- Transformed combination of sprite name and-total-height
string (e.g.icon-home-total-height
) - name_image
String
- Transformed combination of sprite name and-image
string (e.g.icon-home-image
) - name_sprites
String
- Transformed combination of sprite name and-sprites
string (e.g.icon-home-sprites
) - name_group
String
- Transformed combination of sprite name and-group
string (e.g.icon-home-group
) - name_group_name
String
- Transformed combination of sprite name and-group-name
string (e.g.icon-home-group-name
) - name_normal
String
- Transformed combination of sprite name and-normal
string (e.g.icon-home-normal
) - name_retina
String
- Transformed combination of sprite name and-retina
string (e.g.icon-home-retina
) - bare_name
String
- Transformed word forname
- bare_x
String
- Transformed word forx
- bare_y
String
- Transformed word fory
- bare_offset_x
String
- Transformed word foroffset-x
- bare_offset_y
String
- Transformed word foroffset-y
- bare_width
String
- Transformed word forwidth
- bare_height
String
- Transformed word forheight
- bare_total_width
String
- Transformed word fortotal-width
- bare_total_height
String
- Transformed word fortotal-height
- bare_image
String
- Transformed word forimage
- bare_sprites
String
- Transformed word forsprites
- bare_group
String
- Transformed word forgroup
- bare_group_name
String
- Transformed word forgroup-name
- bare_normal
String
- Transformed word fornormal
- bare_retina
String
- Transformed word forretina
- Each of these strings will be transformed via
- data.spritesheet.strings
Object
- Deprecated container for spritesheet-relevant variable/string names- Contents will match the same as
data.spritesheet_info.strings
- Contents will match the same as
- 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-name
string (e.g.icon-home-name
) - name_x
String
- Transformed combination of spritesheet name and-x
string (e.g.icon-home-x
) - name_y
String
- Transformed combination of spritesheet name and-y
string (e.g.icon-home-y
) - name_offset_x
String
- Transformed combination of spritesheet name and-offset-x
string (e.g.icon-home-offset-x
) - name_offset_y
String
- Transformed combination of spritesheet name and-offset-y
string (e.g.icon-home-offset-y
) - name_width
String
- Transformed combination of spritesheet name and-width
string (e.g.icon-home-width
) - name_height
String
- Transformed combination of spritesheet name and-height
string (e.g.icon-home-height
) - name_total_width
String
- Transformed combination of spritesheet name and-total-width
string (e.g.icon-home-total-width
) - name_total_height
String
- Transformed combination of spritesheet name and-total-height
string (e.g.icon-home-total-height
) - name_image
String
- Transformed combination of spritesheet name and-image
string (e.g.icon-home-image
) - name_sprites
String
- Transformed combination of spritesheet name and-sprites
string (e.g.icon-home-sprites
) - name_group
String
- Transformed combination of spritesheet name and-group
string (e.g.icon-home-group
) - name_group_name
String
- Transformed combination of spritesheet name and-group-name
string (e.g.icon-home-group-name
) - name_normal
String
- Transformed combination of spritesheet and-normal
string (e.g.icon-home-normal
) - name_retina
String
- Transformed combination of spritesheet and-retina
string (e.g.icon-home-retina
) - bare_name
String
- Transformed word forname
- bare_x
String
- Transformed word forx
- bare_y
String
- Transformed word fory
- bare_offset_x
String
- Transformed word foroffset-x
- bare_offset_y
String
- Transformed word foroffset-y
- bare_width
String
- Transformed word forwidth
- bare_height
String
- Transformed word forheight
- bare_total_width
String
- Transformed word fortotal-width
- bare_total_height
String
- Transformed word fortotal-height
- bare_image
String
- Transformed word forimage
- bare_sprites
String
- Transformed word forsprites
- bare_group
String
- Transformed word forgroup
- bare_group_name
String
- Transformed word forgroup-name
- bare_normal
String
- Transformed word fornormal
- bare_retina
String
- Transformed word forretina
- Each of these strings will be transformed via
- data.strings
Object
- Container for generic strings- Each of these strings will be transformed via
variableNameTransforms
- bare_name
String
- Transformed word forname
- bare_x
String
- Transformed word forx
- bare_y
String
- Transformed word fory
- bare_offset_x
String
- Transformed word foroffset-x
- bare_offset_y
String
- Transformed word foroffset-y
- bare_width
String
- Transformed word forwidth
- bare_height
String
- Transformed word forheight
- bare_total_width
String
- Transformed word fortotal-width
- bare_total_height
String
- Transformed word fortotal-height
- bare_image
String
- Transformed word forimage
- bare_sprites
String
- Transformed word forsprites
- bare_group
String
- Transformed word forgroup
- bare_group_name
String
- Transformed word forgroup-name
- bare_normal
String
- Transformed word fornormal
- bare_retina
String
- Transformed word forretina
- Each of these strings will be transformed via
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
)
- Properties are retina equivalent of
- 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.name
asname
is deprecated
- We do not provide
- Properties are retina equivalent of
- retina_spritesheet_info
Object
- Optional container for metadata aboutretina_spritesheet
and its representation- Properties are retina equivalent of
data.spritesheet_info
(e.g.name
)
- Properties are retina equivalent of
- retina_groups
Object[]
- Array of objects that maps to normal and retina spritesObject
- Container for data about sprite mapping- name
String
- Name to refer to mapping by - index
Number
- Index of corresponding normal/retina sprites fromdata.sprites
/data.retina_sprites
- normal
Object
- Normal sprite fromdata.sprites
that corresponds to our mapping- This has all the same properties as
data.sprites[*]
(e.g.name
,x
,offset_y
,px
)
- This has all the same properties as
- retina
Object
- Retina sprite fromdata.retina_sprites
that corresponds to our mapping- This has all the same properties as
data.retina_sprites[*]
(e.g.name
,x
,offset_y
,px
)
- This has all the same properties as
- name
- retina_groups_info
Object
- Optional container for metadata aboutretina_groups
and its representation- name
String
- Name forretina_groups
- name
- retina_sprites
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
)
- Each of these strings will be transformed via
- 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
)
- Each of these strings will be transformed via
- 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-name
string (e.g.icon-home-name
) - name_x
String
- Transformed combination of retina group name and-x
string (e.g.icon-home-x
) - name_y
String
- Transformed combination of retina group name and-y
string (e.g.icon-home-y
) - name_offset_x
String
- Transformed combination of retina group name and-offset-x
string (e.g.icon-home-offset-x
) - name_offset_y
String
- Transformed combination of retina group name and-offset-y
string (e.g.icon-home-offset-y
) - name_width
String
- Transformed combination of retina group name and-width
string (e.g.icon-home-width
) - name_height
String
- Transformed combination of retina group name and-height
string (e.g.icon-home-height
) - name_total_width
String
- Transformed combination of retina group name and-total-width
string (e.g.icon-home-total-width
) - name_total_height
String
- Transformed combination of retina group name and-total-height
string (e.g.icon-home-total-height
) - name_image
String
- Transformed combination of retina group name and-image
string (e.g.icon-home-image
) - name_sprites
String
- Transformed combination of retina group name and-sprites
string (e.g.icon-home-sprites
) - name_group
String
- Transformed combination of retina group name and-group
string (e.g.icon-home-group
) - name_group_name
String
- Transformed combination of retina group name and-group-name
string (e.g.icon-home-group-name
) - name_normal
String
- Transformed combination of retina group name and-normal
string (e.g.icon-home-normal
) - name_retina
String
- Transformed combination of retina group name and-retina
string (e.g.icon-home-retina
) - bare_name
String
- Transformed word forname
- bare_x
String
- Transformed word forx
- bare_y
String
- Transformed word fory
- bare_offset_x
String
- Transformed word foroffset-x
- bare_offset_y
String
- Transformed word foroffset-y
- bare_width
String
- Transformed word forwidth
- bare_height
String
- Transformed word forheight
- bare_total_width
String
- Transformed word fortotal-width
- bare_total_height
String
- Transformed word fortotal-height
- bare_image
String
- Transformed word forimage
- bare_sprites
String
- Transformed word forsprites
- bare_group
String
- Transformed word forgroup
- bare_group_name
String
- Transformed word forgroup-name
- bare_normal
String
- Transformed word fornormal
- bare_retina
String
- Transformed word forretina
- Each of these strings will be transformed via
- 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-name
string (e.g.icon-home-name
) - name_x
String
- Transformed combination of retina groups name and-x
string (e.g.icon-home-x
) - name_y
String
- Transformed combination of retina groups name and-y
string (e.g.icon-home-y
) - name_offset_x
String
- Transformed combination of retina groups name and-offset-x
string (e.g.icon-home-offset-x
) - name_offset_y
String
- Transformed combination of retina groups name and-offset-y
string (e.g.icon-home-offset-y
) - name_width
String
- Transformed combination of retina groups name and-width
string (e.g.icon-home-width
) - name_height
String
- Transformed combination of retina groups name and-height
string (e.g.icon-home-height
) - name_total_width
String
- Transformed combination of retina groups name and-total-width
string (e.g.icon-home-total-width
) - name_total_height
String
- Transformed combination of retina groups name and-total-height
string (e.g.icon-home-total-height
) - name_image
String
- Transformed combination of retina groups name and-image
string (e.g.icon-home-image
) - name_sprites
String
- Transformed combination of retina groups name and-sprites
string (e.g.icon-home-sprites
) - name_group
String
- Transformed combination of retina groups name and-group
string (e.g.icon-home-group
) - name_group_name
String
- Transformed combination of retina groups name and-group-name
string (e.g.icon-home-group-name
) - name_normal
String
- Transformed combination of retina groups name and-normal
string (e.g.icon-home-normal
) - name_retina
String
- Transformed combination of retina groups name and-retina
string (e.g.icon-home-retina
) - bare_name
String
- Transformed word forname
- bare_x
String
- Transformed word forx
- bare_y
String
- Transformed word fory
- bare_offset_x
String
- Transformed word foroffset-x
- bare_offset_y
String
- Transformed word foroffset-y
- bare_width
String
- Transformed word forwidth
- bare_height
String
- Transformed word forheight
- bare_total_width
String
- Transformed word fortotal-width
- bare_total_height
String
- Transformed word fortotal-height
- bare_image
String
- Transformed word forimage
- bare_sprites
String
- Transformed word forsprites
- bare_group
String
- Transformed word forgroup
- bare_group_name
String
- Transformed word forgroup-name
- bare_normal
String
- Transformed word fornormal
- bare_retina
String
- Transformed word forretina
- Each of these strings will be transformed via
templater.addTemplate(name, fn)
Method to define a custom template under the format of name
.
- name
String
- Key to store template under for reference viaoptions.format
- fn
Function
- Template function- Should have signature of
function (data)
and return aString
output
- Should have signature of
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-layouts
conventions (e.g. {{#extend "scss"}}
). An example can be found in the Examples section.
- name
String
- Key to store template under for reference viaoptions.format
- tmplStr
String
- Handlebars template to use for formatting- This will receive
data
as itsdata
(e.g.{{sprites}}
isdata.sprites
)
- This will receive
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 lint
and test via npm test
.
Donating
Support this project and others by twolfson via 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.