As it’s explained at the quickstart page the default behaviour of glue is to handle one unique sprite folder. If you need to generate several sprites for a project, you can use the --project option to handle multiple folders with only one command.
The suggested setup is to create a new folder for every sprite, and add inside all the images you need for each one. glue will create a new sprite for every folder:
images
├── actions
│ ├── add.png
│ └── remove.png
├── borders
│ ├── top_left.png
│ └── top_right.png
└── icons
├── comment.png
├── new.png
└── rss.png
$ glue source output --project
Note
This was the default behaviour prior to the version 0.2, after 2.0 is not.
Usually designers add some unnecessary transparent space around the images because it is easier for them to work with a larger canvas. glue can optimize our sprite by croping all the unnecessary transparent spaces that the original images could have.
$ glue source output --crop
less is a dynamic stylesheet language that extends CSS with dynamic behaviors. glue can also create .less files adding the --less option. This files contain exactly the same CSS code. This option only changes the file format.
$ glue source output --less
By default glue adds to the PNG file name the relative url between the CSS and the PNG file. If for any reason you need to change this behaviour, you can use url=<your-static-url-to-the-png-file> and glue will replace its suggested one with your url.
$ glue source output --url=http://static.example.com/
If you want to add the same padding around all images you can use the --padding option:
$ glue source output --padding=10
$ glue source output --padding=10 20
$ glue source output --padding=10 20 30 40
While you are developing a site it could be quite frustrating running Glue once and another every time you change a source image or a filename. --watch will allow you to keep Glue running in the background and it’ll rebuild the sprite every time it detects changes on the source directory.
$ glue source output --watch
Note
New in version 0.2.5
Usually both CSS and PNG files reside on different folders, e.g. css and img. If you want to choose an individual folder for each type of file you can use the --img=<dir> --css=<dir> options together to customize where the output files will be created.
$ glue source --img=images/compiled --css=css/compiled
Using the --html option, Glue will also generate a test html per sprite using all the available CSS classes. This option is only useful for testing purposes. Glue generate the html file in the same directory as the CSS file.
$ glue source --html
Note
New in version 0.2.5
The criteria that glue uses to order the images before adding them to the canvas can be tunned. By default the algorithm is square, but in some situations using another ordering like vertical or horizontal could be useful depending on the kind of images you are spriting.
$ glue source output --algorithm=[square|vertical|hortizontal|diagonal|vertical-right|horizontal-bottom]
Before processing the images using the algorithm glue orders the images. The default ordering is maxside but you can configure it using the --ordering option.
$ glue source output --ordering=[maxside|width|height|area]
You can reverse how any of the available algorithms works prepending a -.
$ glue source output --ordering=[-maxside|-width|-height|-area]
If you want to spread the images around the sprite but you don’t want to count this space as image width/height (as happens using –padding`), you can use the --margin option followed by the margin you want to add:
$ glue source output --margin=20
Note
New in version 0.2.5
By default glue adds the namespace sprite to all the generated CSS class names. If you want to use your own namespace you can override the default one using the --namespace option.
$ glue source output --namespace=my-namespace
By using the flag png8 the output image format will be png8 instead of png32.
$ glue source output --png8
Note
New in version 0.1.9
glue by default uses the end of each filename to discover if you want to add some padding to that image. If for any reason you want to disable this behavior (e.g. legacy purposes), you can use the --ignore-filename-paddings option to disable it.
$ glue source output --ignore-filename-paddings
glue by default uses - as separator for the CSS class names. If you want to customize this behaviour you can use --separator to specify your own one:
$ glue source output --separator=_
If you want to use camelCase instead of a separator, choose camelcase as separator.
$ glue source output --separator=camelcase
If you want to customize the output CSS you can use this option to tune the global section of the output CSS. This template is going to be only added once per sprite. Usually you’ll not need to change this template.
$ glue source output --global-template=<template>
For example if you want to add quotes around the sprite image:
$ glue source output --global-template="%(all_classes)s{background-image:url('%(sprite_url)s');background-repeat:no-repeat}"
Note
New in version 0.2.1
If you want to customize the output CSS, you can use this option to tune the output CSS generated for each image. This template is going to be added once per image present in the sprite. Usually you’ll change this template if you want to remove the block size from the output CSS or make any other fine tune.
$ glue source output --each-template=<template>
For example if you want to remove the block size from the output CSS (old --no-size option):
$ glue source output --each-template="%(class_name)s{background-position:%(x)s %(y)s;}"
Note
New in version 0.2.1
OptiPNG is a PNG optimizer that recompresses image files to a smaller size, without losing any information.
OptiPNG is not a glue requirement but is hardly recommended to optimize the output PNG files to make them as small as possible.
If you have optipng installed on your computer you can use the --optipng option to automatically optimize all the sprites that glue generates. If you don’t know how to install it, read the optipng page.
$ glue source output --optipng
If optipng is not in your computer PATH, you can choose the optipng path using this option.
$ glue source output --optipng --optipngpath=<dir>
If you decide to add an expires header to your static resources (and if you haven’t already you really should), you need to worry about cache busting these resources every time you change one of them.
Cache busting is a technique that prevents a browser from reusing a resource that was already downloaded and cached. Cache in general is good, but in some situations could be annoying if it’s duration is too long and we want to update a resource now.
This technique adds a flag to every url that links an external resource (PNG in this case). This flag usually is the last modified time or the hash of the file.
glue can use this technique to automatically add the hash of the PNG file to the CSS url, so as soon as the file change (add/remove an image) the hash will be different and the browser will re-download the image.
$ glue source output --cachebuster
Original css:
.sprite-icons-zoom{ background:url('sprites/icons/icons.png'); top:0; left:0; no-repeat;}
.sprite-icons-wrench_orange{ background:url('sprites/icons/icons.png'); top:0; left:-16; no-repeat;}
...
After –cachebuster:
.sprite-icons-zoom{ background:url('sprites/icons/icons.png=p3c54d'); top:0; left:0; no-repeat;}
.sprite-icons-wrench_orange{ background:url('sprites/icons/icons.png?p3c54d'); top:0; left:-16; no-repeat;}
...
This option has the same purpose than --cachebuster but insted of using the hash of the PNG as a queryarg it uses it as part of the filename.
$ glue source output --cachebuster-filename
Original css:
.sprite-icons-zoom{ background:url('sprites/icons/icons.png'); top:0; left:0; no-repeat;}
.sprite-icons-wrench_orange{ background:url('sprites/icons/icons.png'); top:0; left:-16; no-repeat;}
...
After –cachebuster:
.sprite-icons-zoom{ background:url('sprites/icons/icons_p3c54d.png'); top:0; left:0; no-repeat;}
.sprite-icons-wrench_orange{ background:url('sprites/icons/icons_p3c54d.png'); top:0; left:-16; no-repeat;}
...