POLYMER

Polymer is a tool for creating sprite images which combine many smaller sources into a single larger image. Spriting allows you to reduce the number of HTTP requests required to load a web page, and as such can result in reduced load times.

Polymer also creates the necessary CSS to position the sprite within an HTML element so that only the desired source appears. Those writing their website or application in Ruby can make use of Polymer's Sass builder which creates a Sass mixin, further simplifying the use of your sprites.

In order to reduce the amount of data transferred to clients loading your pages, Polymer optimises the sprites it generates using PNGOUT, OptiPNG, and PNGCrush.

The recommended way to install Polymer is with Rubygems:

$ [sudo] gem install polymer

Polymer uses ChunkyPNG to read source files, and write the final sprites; as a pure-Ruby library it is much easier to install than RMagick, while not being so much slower as to pose a problem (optimisation with PNGOut takes far longer than creating the sprite).

If you wish to install Polymer from source:

$ git clone http://github.com/antw/polymer.git && cd polymer
$ gem build polymer.gemspec
$ [sudo] gem install --local polymer-VERSION.gem

(Where "VERSION" is the current version of Polymer). If you do not have Git installed, the latest versions can be downloaded instead.

In order for Polymer to create sprites from your source images, it must first create a "project" -- this is a .polymer file which is placed into your project's root directory. This file comes with some sensible defaults which should suffice for most cases. This file is generated by running polymer init.

1. Run polymer init to create a ".polymer" file in the current directory. Prior to running the command, you may want to glance at the polymer-init(1) manpage to get an overview of the supported options. polymer init also places some example source images into your project.

2. Run polymer bon): this is the main task which converts the source images into the final sprites. If you have PNGOUT, OptiPNG, or PNGCrush installed, Polymer will also optimise the generates sprites to reduce them to the smallest possible filesize.

3. Run polymer bond again. Nothing happens! Polymer maintains a cache of your sprite images so that it only generates them again if any of the sources have changed; pretty handy since optimising large sprites can take some time. See polymer(5) to learn how to disable this.

Having created some example sprites in "Getting Started", you can now add completely new sprites by adding new directories alongside "one" and "two", alter existing sprites by adding, changing, or removing source images, then once again running polymer bond.

If this isn't sufficiently flexible, see polymer(5) to learn how to define your own sprites in the ".polymer" file.

Out-of-the-box, Polymer generates a Sass stylesheet containing a mixin. This stylesheet is created at the path given to "config.sass" in ".polymer".

This mixin can be used thusly: (in this case, "main" is the name of the sprite, "home" and "products" are the names of source images sans-extension).

Assuming directory structure:

public/images/sprites/
  messages/
    new.png
    reply.png

Your Sass stylesheet like:

  @import polymer.sass

  .buttons
    a#compose, a#reply
      +polymer("messages/new")
    a#reply
      +polymer-pos("messages/reply")

Which creates:

.buttons a#compose, .buttons a#reply {
  background: url(/path/to/sprite.ext) 0 0 no-repeat; }

.buttons a#products {
  background-position: 0 -40px; }

With the latest versions of the Haml library, you may use SCSS instead:

  @import("polymer.sass")

  .buttons {
    a#compose, a#reply {
      @include polymer("messages/new") }
    a#reply {
      @include polymer-pos("messages/reply") } }

You can disable creation of the Sass mixin file by setting config.sass false in the ".polymer" file.

Sass users can make use of data URIs; the sprite contents will, instead of being written to disk, be inlined into your CSS files. This reduces the number of HTTP requests required to load your pages, but results in slightly more data having to be transferred to your users. See polymer(5) for instructions.

... are not yet implemented. Hold tight; these should be around before Polymer hits v1.0.

... needs to be written up.

A Bundler Gemfile is provided to simplify installing Polymer's dependencies. Running bundle install will install everything needed to contribute. Bundler is not used in the Polymer library itself.

• Fork the project, taking care not to get any in your eyes.

• Make your feature addition or bug fix.

• Add tests for it. This is especially important not only because it helps ensure that I don't unintentionally break it in a future version, but also since it appeases Epidity, God of Potatoes, who has been known to shower rancid cucumbers upon those who fail to test.

• Commit, but please do not mess with the Rakefile or history. If you want to have your own version, that is fine, but bump the version in a commit by itself so that I can ignore it when I pull.

• Send me a pull request. Bonus points for topic branches (although "everything is made up, and the points don't matter...").

Polymer specs are run against:

• Ruby (MRI) 1.8.7 p302,
• Ruby (YARV) 1.9.1 p378,
• Ruby (YARV) 1.9.2 p0.

Polymer comes complete with some manpages which document the various commands:

• polymer(1) -- polymer help
• polymer(5) -- polymer help .polymer
• polymer-init(1) -- polymer help init
• polymer-bond(1) -- polymer help bond
• polymer-optimise(1) -- polymer help optimise
• polymer-position(1) -- polymer help position

If you've encountered a bug, or Polymer isn't behaving as you expect, please file an issue report.

Source : http://github.com/antw/polymer

Author : Anthony Williams

Copyright : 2009-2010

License : BSD License

Polymer © 2009-2010 by Anthony Williams. Polymer is free software, released under the BSD license. Please see the LICENSE file for more information.

The sample sources in lib/polymer/templates/sources are courtesy of Yusuke Kamiyamane, whose extraordinary generosity in releasing three-thousand royalty-free icons cannot be stated enough.