.polymer - a format for describing image sprites and their sources
A .polymer file describes the image sprites used in a Polymer project,
and the source images which are used to create those sprites.
Placing a .polymer file in the root directory of your project will
allow the Polymer application to automate generation and optimisation of
your sprite images. In a Ruby project the .polymer file should be in
the same directory as your Rakefile.
On systems where files beginning with a "." are tricky to work with
(e.g. Windows), you may instead use polymer.rb instead of .polymer.
A .polymer can be generated by running polymer init.
The .polymer file is, at it's heart, a Ruby file and thus any valid
Ruby code may be used in it. This may seem intimidating to those who
have never used Ruby, but the .polymer syntax is very simple, and
fairly self-explanatory (the irony of saying that, then writing a man
page, is not lost on me...).
Global options are prefixed with "config." and followed by the value you wish to set. These settings are OPTIONAL, and Polymer will use it's own defaults if you choose not to define them.
config.sass "string" or falseThe path, relative to the .polymer file, at which you want the Sass
mixin file to be written. You may also set this to false in order
to disable generation of Sass files. Default:
"public/stylesheets/sass"
config.css "string" or falseThe path, relative to the .polymer file, at which you want the CSS
file to be written. You may also set this to false in order to
disable generation of CSS files. Default: false
config.url "string"In order for stylesheets to link to the generated sprites, they must
be able to create a URL for each sprite. Typically this URL should
be relative to the web root and prefixed with a "/", otherwise
browsers will interpret the URL as being relative to the stylesheet.
The url option accepts a ":filename" segment which Polymer will
change to each sprite's filename (including the extension).
Default: "/images/:filename"
config.padding numberPolymer stacks each source image on top of one another, with
transparent padding being used to ensure that one source does not
bleed into another when used as the background for an HTML element.
The padding option sets the number of pixels to be used to
separate each source, and may be set to 0 if no padding is desired.
Default: 20.
config.cache "string" or falseSince optimising sprites can take some time, Polymer maintains a cache of each sprite, only generating and optimising those which have changed. This cache is typically stored in your project root as ".polymer-cache". You may specify an alternate path here, or provide false if you want to disable the cache entirely (not recommended).
Sprites are defined using the sprite keyword (which is also aliased as sprites). The simplest way of defining a sprite is:
sprite "path/to/sources/*" => "path/to/sprite.png"
Both of the paths in the above example are relative to the .polymer
file. In this case, we are telling Polymer to take source files from the
"path/to/sources" directory, and composite them together in a sprite to
be saved at "path/to/sprite.png".
If your source directory contains non-images, you may need to be more specific:
sprite "path/to/sources/*.{png,gif,jpg}" => "path/to/sprite.png"
Sprite definitions may contain a :name segment which Polymer will use
to match any sub-directory:
sprites "sources/:name/*" => "sprites/:name.png"
In this case, Polymer will look inside the "sources/" directory for sub-directories. The contents of each sub-directory will be used to create individual sprites where the final sprite name is the same as the directory name. For example, given the following directory structure...
sources/
one/
book.png
calculator.png
two/
magnet.png
television.png
... Polymer will create two sprites in the "sprites/" directory: one.png will contain "book" and "calculator", while two.png will contain "magnet" and "television".
You may instead prefer to set the save path to :data_uri; Polymer will place the sprite contents into your CSS file. This reduces the number of HTTP requests requires to load your pages at the expense of slightly greater data transfer.
sprites "sources/:name/*" => :data_uri
There may be cases where you need to customise an individual sprite and
you don't want to change the global setting; sprite allows you to
specify any of the global settings with the exception of "sass" and
"css" like so:
sprite "path/to/sources/*" => "path/to/sprite.png",
:padding => 50, :url => "/elsewhere/:filename"
Each configuration option is prefixed with a colon rather than "config.", is separated from the value with " => ", and all but the final option should be followed with a comma.
You may use sprite as many times as you need.