.POLYMER(5)			Polymer Manual			   .POLYMER(5)



NAME
       .polymer - a format for describing image sprites and their sources

DESCRIPTION
       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.

SYNTAX
       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 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.

       config.sass "string" or false
	      The 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: "pub-
	      lic/stylesheets/sass"

       config.css "string" or false
	      The 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 "/", oth-
	      erwise 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 number
	      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 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 false
	      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 false if you want to disable the cache entirely
	      (not recommended).

DEFINING SPRITES
       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 struc-
       ture...



	   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 con-
       tain "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 spec-
       ify 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 "con-
       fig.", 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.

SEE ALSO
       polymer(1), polymer-init(1)



POLYMER 1.0.0.BETA.6		 November 2010			   .POLYMER(5)