.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.ad l
.
.TH "\.POLYMER" "5" "February 2011" "POLYMER 1.0.0.BETA.7" "Polymer Manual"
.
.SH "NAME"
\fB\.polymer\fR \- a format for describing image sprites and their sources
.
.SH "DESCRIPTION"
A \fB\.polymer\fR file describes the image sprites used in a Polymer project, and the source images which are used to create those sprites\.
.
.P
Placing a \fB\.polymer\fR 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 \fB\.polymer\fR file should be in the same directory as your \fBRakefile\fR\.
.
.P
On systems where files beginning with a "\." are tricky to work with (e\.g\. Windows), you may instead use \fBpolymer\.rb\fR instead of \fB\.polymer\fR\.
.
.P
A \fB\.polymer\fR can be generated by running \fBpolymer init\fR\.
.
.SH "SYNTAX"
The \fB\.polymer\fR 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 \fB\.polymer\fR syntax is very simple, and fairly self\-explanatory (the irony of saying that, then writing a man page, is not lost on me\.\.\.)\.
.
.SH "GLOBAL SETTINGS"
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\.
.
.TP
\fBconfig\.sass\fR "\fIstring\fR" or \fIfalse\fR
The path, relative to the \fB\.polymer\fR file, at which you want the Sass mixin file to be written\. You may also set this to \fIfalse\fR in order to disable generation of Sass files\. Default: "public/stylesheets/sass"
.
.TP
\fBconfig\.css\fR "\fIstring\fR" or \fIfalse\fR
The path, relative to the \fB\.polymer\fR file, at which you want the CSS file to be written\. You may also set this to \fIfalse\fR in order to disable generation of CSS files\. Default: false
.
.TP
\fBconfig\.url\fR "\fIstring\fR"
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 \fBurl\fR option accepts a ":filename" segment which Polymer will change to each sprite\'s filename (including the extension)\. Default: "/images/:filename"
.
.TP
\fBconfig\.padding\fR \fInumber\fR
Polymer 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 \fBpadding\fR 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\.
.
.TP
\fBconfig\.cache\fR "\fIstring\fR" or \fIfalse\fR
Since 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 \fIfalse\fR if you want to disable the cache entirely (not recommended)\.
.
.SH "DEFINING SPRITES"
Sprites are defined using the \fIsprite\fR keyword (which is also aliased as \fIsprites\fR)\. The simplest way of defining a sprite is:
.
.IP "" 4
.
.nf

sprite "path/to/sources/*" => "path/to/sprite\.png"
.
.fi
.
.IP "" 0
.
.P
Both of the paths in the above example are relative to the \fB\.polymer\fR 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"\.
.
.P
If your source directory contains non\-images, you may need to be more specific:
.
.IP "" 4
.
.nf

sprite "path/to/sources/*\.{png,gif,jpg}" => "path/to/sprite\.png"
.
.fi
.
.IP "" 0
.
.P
Sprite definitions may contain a \fB:name\fR segment which Polymer will use to match any sub\-directory:
.
.IP "" 4
.
.nf

sprites "sources/:name/*" => "sprites/:name\.png"
.
.fi
.
.IP "" 0
.
.P
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\.\.\.
.
.IP "" 4
.
.nf

sources/
  one/
    book\.png
    calculator\.png
  two/
    magnet\.png
    television\.png
.
.fi
.
.IP "" 0
.
.P
\&\.\.\. Polymer will create two sprites in the "sprites/" directory: one\.png will contain "book" and "calculator", while two\.png will contain "magnet" and "television"\.
.
.P
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\.
.
.IP "" 4
.
.nf

sprites "sources/:name/*" => :data_uri
.
.fi
.
.IP "" 0
.
.P
There may be cases where you need to customise an individual sprite and you don\'t want to change the global setting; \fBsprite\fR allows you to specify any of the global settings with the exception of "sass" and "css" like so:
.
.IP "" 4
.
.nf

sprite "path/to/sources/*" => "path/to/sprite\.png",
  :padding => 50, :url => "/elsewhere/:filename"
.
.fi
.
.IP "" 0
.
.P
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\.
.
.P
You may use \fBsprite\fR as many times as you need\.
.
.SH "SEE ALSO"
polymer(1), polymer\-init(1)