spritesheet-templates
Advanced tools
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 Stylus templatespritesheet (e.g. $spritesheet-width, $spritesheet-image)Object - 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 formatterBelow 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.
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",
// ...
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';
// ...
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 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 spritesObject - 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 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 spritesObject - 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 spritestemplater.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 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
The npm package spritesheet-templates receives a total of 39,643 weekly downloads. As such, spritesheet-templates popularity was classified as popular.
We found that 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.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.