https://github.com/assetgraph/assetgraph-sprite
AssetGraph plugin for creating sprites from background images
https://github.com/assetgraph/assetgraph-sprite
Last synced: about 1 year ago
JSON representation
AssetGraph plugin for creating sprites from background images
- Host: GitHub
- URL: https://github.com/assetgraph/assetgraph-sprite
- Owner: assetgraph
- License: bsd-3-clause
- Created: 2011-06-23T09:30:42.000Z (almost 15 years ago)
- Default Branch: master
- Last Pushed: 2025-03-08T22:42:19.000Z (about 1 year ago)
- Last Synced: 2025-03-17T04:39:13.264Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 525 KB
- Stars: 36
- Watchers: 6
- Forks: 6
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-wpo - Assetgraph-sprite - Assetgraph transform for auto-generating sprites based on the CSS dependency graph. (Generators / Meetups)
- fucking-awesome-wpo - Assetgraph-sprite - Assetgraph transform for auto-generating sprites based on the CSS dependency graph. (Generators / Meetups)
- awesome-wpo-dup - Assetgraph-sprite - Assetgraph transform for auto generating sprites based on the CSS dependency graph. (Sprite Generators)
- awesome-wpo-chinese - Assetgraph-sprite - Assetgraph transform for auto generating sprites based on the CSS dependency graph. (Sprite Generators)
README
# AssetGraph-sprite
[](https://gitter.im/assetgraph/assetgraph-sprite?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](http://badge.fury.io/js/assetgraph-sprite)
[](https://travis-ci.org/assetgraph/assetgraph-sprite)
[](https://coveralls.io/r/assetgraph/assetgraph-sprite)
[](https://david-dm.org/assetgraph/assetgraph-sprite)
A plugin (or "transform") for AssetGraph that
optimizes CSS background images by creating sprite images. The
spriting is guided by GET parameters and a set of custom CSS
properties with a `-sprite-` prefix.
You can tell AssetGraph-sprite that you want to sprite a given CSS
background image by adding a `sprite` parameter to its query string:
```css
.classone {
background-image: url(images/thething.png?sprite=mySpriteGroup);
}
.classtwo {
background-image: url(images/theotherthing.png?sprite=mySpriteGroup);
}
```
This is valid CSS and will also work fine on its own in "development
mode" without a compilation step, so you don't need to rebuild your
project all the time, except when you want to test the spriting
itself. After being run through the AssetGraph-sprite transform it
will look something like this (`123` is the id of the generated sprite
asset and could be any number):
```css
.classone {
background-image: url(123png);
background-position: 0 0;
}
.classtwo {
background-image: url(123png);
background-position: -34px 0;
}
```
Some additional parameters are supported:
#### `padding=,,,`
Adds "keepaway space" around the image in the sprite. Sometimes
useful if the background image is applied to an element that takes
up a bigger area than the background image. Supports regular CSS
padding syntax, including the shorthand variants with 1, 2, or 3
values. The only supported unit is `px`. Defaults to `0 0 0 0`. Not
supported by the `jim-scott` packer (see the docs for
`-sprite-packer` below).
#### `spriteNoGroup`
Tells AssetGraph-sprite that you want this selector to contain a
`background-image` property pointing at the sprite image, even
if the sprite group has a "group selector" configured (see below).
## Configuring a sprite
If you can guarantee that the HTML elements that need to have the
background image applied are also matched by another selector, you can
save some more bytes by telling AssetGraph-sprite that it only needs
to add the `background-image` property pointing at the sprite to that
selector using the `-sprite-selector-for-group` property:
```css
.foo {
-sprite-selector-for-group: mySpriteGroup;
}
.classone {
background-image: url(images/thething.png?sprite=mySpriteGroup);
}
.classtwo {
background-image: url(images/theotherthing.png?sprite=mySpriteGroup);
}
```
... which compiles to:
```css
.foo {
background-image: url(123png);
}
.classone {
background-position: 0 0;
}
.classtwo {
background-position: -34px 0;
}
```
AssetGraph-sprite tries to preserve as much of the original CSS as
possible, including existing `background` or `background-image`
properties in the group selector and the priority (`!important`
status), for example:
```css
.foo {
-sprite-selector-for-group: mySpriteGroup;
background: red !important;
}
.classone {
background: blue url(images/thething.png?sprite=mySpriteGroup) !important;
}
```
Compiles to:
```css
.foo {
background: red url(123png) !important;
}
.classone {
background: blue !important;
background-position: 0 0;
}
```
You can tweak the generated sprite images by putting additional
`-sprite`-prefixed configuration properties into the "group
selector", for example:
```css
.foo {
-sprite-selector-for-group: mySpriteGroup;
-sprite-packer: horizontal;
-sprite-background-color: #a767ac;
}
```
These options are currently supported:
#### `-sprite-packer: horizontal|vertical|jim-scott|try-all`
Selects the packing algorithm for the sprite. The `horizontal` and
`vertical` variants naively lay out the images one after the other.
This works well when you have a bunch of images with the same height
or width. The `jim-scott` packer is a little fancier, it's an
implementation of a floor planning
algorithm originally invented by Jim Scott for packing
lightmaps. The Jim Scott packer doesn't support the
`-sprite-padding` property on the individual images. If you don't
specify `-sprite-packer`, the default is `try-all`, which runs all
the algorithms and chooses the packing that produces the smallest
sprite image (area-wise).
#### `-sprite-location: url(...)`
Specifies the desired location of the sprite. This is useful in
combination with the `processImages` transform if you want to
postprocess the generated sprite image:
```css
.foo {
-sprite-selector-for-group: mySpriteGroup;
-sprite-location: url(mySprite.png?pngquant=128);
}
.classone {
background-position: 0 0;
}
```
Compiles to:
```css
.foo {
background: red url(mySprite.png?pngquant=128) !important;
}
.classone {
background-position: 0 0;
}
```
#### `-sprite-image-format: png|jpg`
The format of the generated sprite. More will be added when node-canvas gains
support for more image formats.
#### `-sprite-background-color: red|yellow|#123123|transparent|...`
Specifies the background color for the generated sprite image,
supports any color syntax understood by node-canvas, which is the
entire CSS3
Color Module, as far as I can tell. Defaults to `transparent`.
## Installation
```
$ npm install assetgraph-sprite
```
## Usage
Since AssetGraph-sprite is intended to be used as part of an AssetGraph
workflow, first you'll need to have AssetGraph installed to use it properly:
```
$ npm install assetgraph
```
Here's a stripped-down example that loads all CSS files in a
directory, loads all the images linked to by `background` and
`background-image` properties, sprites them according to the
`-sprite-...` instructions, then writes the resulting CSS and
all the images to a different directory:
```javascript
var AssetGraph = require('assetgraph');
new AssetGraph({ root: 'path/to/css/files' })
.loadAssets('*.css')
.populate({ followRelations: { type: 'CssImage' } })
.queue(require('assetgraph-sprite')())
.writeAssetsToDisc({ url: /^file:/ }, 'file:///my/output/dir')
.run(function (err) {
if (err) throw err;
// All done!
});
```
For a more elaborate example of how AssetGraph-sprite can fit in a
workflow, see the buildProduction script in AssetGraph-builder
## Releases
[Changelog](https://github.com/assetgraph/assetgraph-sprite/blob/master/CHANGELOG.md)
## License
AssetGraph-sprite is licensed under a standard 3-clause BSD license --
see the `LICENSE`-file for details.