polymer 1.0.0.beta.4 → 1.0.0.beta.5

data/History.md

@@ -25,6 +25,17 @@ v1.0.0 / HEAD (Unreleased)
   also available as an alternative to the old "sprite-name-pos()"
   mixins.
 
+* Sprites can now be included "inline" in your Sass files by setting the
+  sprite path to :data\_uri in your .polymer file. This further reduces
+  the number of HTTP requests required at the expense of slightly
+  greater data transfer.
+
+  Polymer adds the data URI to the Sass file by using a selector (such
+  as ".my\_sprite\_data"), and then uses Sass' @extend feature so that
+  the data is only added to the CSS file once. Your own Sass files do
+  not need to be modified to make use of this feature; the @polymer
+  mixin suffices.
+
 * The "polymer-pos" Sass mixin, which sets only the background position
   of a source, without including the background-image property, has been
   renamed to "polymer-position".

data/README.md

@@ -132,6 +132,13 @@ With the latest versions of the Haml library, you may use SCSS instead:
 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)][polymer-5] for instructions.
+
+
 ### CSS Stylesheets
 
 ... are not yet implemented. Hold tight; these should be around before

data/lib/polymer/dsl.rb

@@ -114,7 +114,7 @@ module Polymer
           raise Polymer::DslError,
             "Sprite '#{source} => #{sprite}' has both a :name path segment " \
             "and a :name option; please use only one."
-        elsif sprite !~ /:name/
+        elsif sprite != :data_uri and sprite !~ /:name/
           raise Polymer::MissingName,
             "Sprite '#{source} => #{sprite}' requires a :name segment in " \
             "the sprite path."
@@ -138,7 +138,7 @@ module Polymer
       project_config = @config.to_h
 
       Project.new(@root, @sprites.map do |definition|
-        definition = _create_sprite(definition, project_config)
+        _create_sprite(definition, project_config)
       end, project_config)
     end
 
@@ -178,7 +178,9 @@ module Polymer
     #   existing sprite.
     #
     def _define_sprite(sources, sprite, options)
-      sources, sprite = @root + sources, @root + sprite
+      sources = @root + sources
+      sprite  = @root + sprite unless sprite == :data_uri
+
       name = options[:name] || sprite.basename(sprite.extname).to_s
 
       if @sprites.detect { |definition| definition[:name] == name }
@@ -193,7 +195,7 @@ module Polymer
       @sprites << options.merge(
         :name      => name,
         :sources   => Pathname.glob(sources),
-        :save_path => @root + sprite
+        :save_path => sprite
       )
     end
 
@@ -216,7 +218,8 @@ module Polymer
         sprite_opts[:name] = entry.basename.to_s # Use directory as the name
 
         source_path = "#{leading}#{sprite_opts[:name]}#{trailing}"
-        sprite_path = sprite.gsub(/:name/, sprite_opts[:name])
+        sprite_path = (sprite == :data_uri) ?
+          :data_uri : sprite.gsub(/:name/, sprite_opts[:name])
 
         _define_sprite(source_path, sprite_path, sprite_opts)
       end
@@ -232,16 +235,23 @@ module Polymer
     # @return [Polymer::Sprite]
     #
     def _create_sprite(definition, project_config)
-      url = definition.fetch(:url, project_config[:url]).dup
-      url.gsub!(/:name/, definition[:name])
-      url.gsub!(/:filename/, definition[:save_path].basename.to_s)
+      if definition[:save_path] == :data_uri and not project_config[:sass]
+        raise DslError, "The `#{definition[:name]}' sprite wants to use a " \
+                        "data URI, but you have disabled Sass"
+      end
+
+      unless definition[:save_path] == :data_uri
+        url = definition.fetch(:url, project_config[:url]).dup
+        url.gsub!(/:name/, definition[:name])
+        url.gsub!(/:filename/, definition[:save_path].basename.to_s)
+      end
 
       Polymer::Sprite.new \
         definition[:name],
         definition[:sources],
         definition[:save_path],
         definition.fetch(:padding, project_config[:padding]),
-        url
+        url || ''
     end
 
     # Provides the DSL for the global configuration options.

data/lib/polymer/man/polymer-bond.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER\-BOND" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
+.TH "POLYMER\-BOND" "1" "October 2010" "POLYMER 1.0.0.BETA.5" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\-bond\fR \- Create sprite images defined in your \.polymer file

data/lib/polymer/man/polymer-bond.1.txt

@@ -63,4 +63,4 @@ SEE ALSO
 
 
 
-POLYMER 1.0.0.BETA.4		September 2010		       POLYMER-BOND(1)
+POLYMER 1.0.0.BETA.5		 October 2010		       POLYMER-BOND(1)

data/lib/polymer/man/polymer-init.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER\-INIT" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
+.TH "POLYMER\-INIT" "1" "October 2010" "POLYMER 1.0.0.BETA.5" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\-init\fR \- Create a new Polymer project in the current directory

data/lib/polymer/man/polymer-init.1.txt

@@ -39,4 +39,4 @@ OPTIONS
 
 
 
-POLYMER 1.0.0.BETA.4		September 2010		       POLYMER-INIT(1)
+POLYMER 1.0.0.BETA.5		 October 2010		       POLYMER-INIT(1)

data/lib/polymer/man/polymer-optimise.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER\-OPTIMISE" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
+.TH "POLYMER\-OPTIMISE" "1" "October 2010" "POLYMER 1.0.0.BETA.5" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\-optimise\fR \- Optimise PNG images

data/lib/polymer/man/polymer-optimise.1.txt

@@ -27,4 +27,4 @@ DESCRIPTION
 
 
 
-POLYMER 1.0.0.BETA.4		September 2010		   POLYMER-OPTIMISE(1)
+POLYMER 1.0.0.BETA.5		 October 2010		   POLYMER-OPTIMISE(1)

data/lib/polymer/man/polymer-position.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER\-POSITION" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
+.TH "POLYMER\-POSITION" "1" "October 2010" "POLYMER 1.0.0.BETA.5" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\-position\fR \- Information about your sprite sources

data/lib/polymer/man/polymer-position.1.txt

@@ -39,4 +39,4 @@ DESCRIPTION
 
 
 
-POLYMER 1.0.0.BETA.4		September 2010		   POLYMER-POSITION(1)
+POLYMER 1.0.0.BETA.5		 October 2010		   POLYMER-POSITION(1)

data/lib/polymer/man/polymer.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
+.TH "POLYMER" "1" "October 2010" "POLYMER 1.0.0.BETA.5" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\fR \- Image spriting for web applications

data/lib/polymer/man/polymer.1.txt

@@ -57,4 +57,4 @@ SEE ALSO
 
 
 
-POLYMER 1.0.0.BETA.4		September 2010			    POLYMER(1)
+POLYMER 1.0.0.BETA.5		 October 2010			    POLYMER(1)

data/lib/polymer/man/polymer.5

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "\.POLYMER" "5" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
+.TH "\.POLYMER" "5" "October 2010" "POLYMER 1.0.0.BETA.5" "Polymer Manual"
 .
 .SH "NAME"
 \fB\.polymer\fR \- a format for describing image sprites and their sources
@@ -110,6 +110,19 @@ sources/
 \&\.\.\. 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

data/lib/polymer/man/polymer.5.txt

@@ -122,6 +122,17 @@ DEFINING SPRITES
        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"
@@ -145,4 +156,4 @@ SEE ALSO
 
 
 
-POLYMER 1.0.0.BETA.4		September 2010			   .POLYMER(5)
+POLYMER 1.0.0.BETA.5		 October 2010			   .POLYMER(5)

data/lib/polymer/project.rb

@@ -43,6 +43,13 @@ module Polymer
     #
     attr_reader :sprites
 
+    # Returns a subset of +sprites+ containing sprites which are to be written
+    # as a data URI in a Sass file.
+    #
+    # @return [Array<Polymer::Sprite>]
+    #
+    attr_reader :data_uri_sprites
+
     # Creates a new Project.
     #
     # Note that +new+ does not validation of the given paths or options; it
@@ -72,6 +79,14 @@ module Polymer
       @sass      = extract_path :sass,  options
       @css       = extract_path :css,   options
       @cachefile = extract_path :cache, options
+
+      # Sprites which are to be saved as a data URI need to have a save
+      # path explicitly set.
+      @data_uri_sprites = @sprites.select do |sprite|
+        if sprite.save_path == :data_uri
+          sprite.save_path = tmpdir.join("#{sprite.name.to_s}.png")
+        end
+      end
     end
 
     # Returns the sprite whose name is +name+.
@@ -80,7 +95,7 @@ module Polymer
     #   The name of the sprite to be retrieved.
     #
     # @return [Polymer::Sprite] The sprite.
-    # @return [nil]           If no such sprite exists.
+    # @return [nil]             If no such sprite exists.
     #
     def sprite(name)
       sprites.detect { |sprite| sprite.name == name }
@@ -103,6 +118,17 @@ module Polymer
       @cache ||= Polymer::Cache.new(@cachefile)
     end
 
+    # Returns a path to a temporary directory which may be used by this
+    # project.
+    #
+    # The temporary directory will be created if it does not already exist.
+    #
+    # @return [Pathname] Path to the temporary directory.
+    #
+    def tmpdir
+      @tmpdir ||= Pathname.new(Dir.mktmpdir).tap { |p| p.mkpath }
+    end
+
     private # ================================================================
 
     # Extracts a path, typically specified in the DSL, and converts it to

data/lib/polymer/sass_generator.rb

@@ -27,6 +27,12 @@ module Polymer
         save_to = project.sass + '_polymer.sass'
       end
 
+      data_uris = project.data_uri_sprites.inject({}) do |memo, sprite|
+        data = [sprite.save_path.read].pack('m').strip
+        memo[sprite.name] = "data:image/png;base64,#{data}"
+        memo
+      end
+
       File.open(save_to, 'w') do |file|
         file.puts ERB.new(File.read(TEMPLATE), nil, '<>').result(binding)
       end

data/lib/polymer/sprite.rb

@@ -2,7 +2,8 @@ module Polymer
   # Represents a collection of images which will be used to make a sprite.
   #
   class Sprite
-    attr_reader :name, :save_path, :url, :padding, :sources
+    attr_reader   :name, :url, :padding, :sources
+    attr_accessor :save_path
 
     # Creates a new Sprite instance.
     #
@@ -10,8 +11,10 @@ module Polymer
     #   The name of the sprite.
     # @param [Array<Pathname>] sources
     #   An array of Pathname instances to be used as sources.
-    # @param [Pathname] save_path
-    #   The location at which the sprite should be saved.
+    # @param [Pathname, Symbol] save_path
+    #   The location at which the sprite should be saved. When being used with
+    #   a Project, this may instead be :data_uri; adding the sprite to the
+    #   project will set the correct path.
     # @param [Integer] padding
     #   The amount of transparent space, in pixels, to be inserted between
     #   each source image.

data/lib/polymer/templates/sass_mixins.erb

@@ -2,6 +2,11 @@
 // command provided by the polymer gem. Don't edit this file directly;
 // change the polymer.rb configuration file, then re-run 'polymer'.
 
+<% project.data_uri_sprites.each do |sprite| %>
+.<%= sprite.name %>_data
+  background: url(<%= data_uris[sprite.name] %>) 0 0 no-repeat
+<% end %>
+
 @mixin polymer($source, $x-offset: 0px, $y-offset: 0px)
 <% project.sprites.each_with_index do |sprite, sprite_index| %>
 <% sprite.sources.each_with_index do |source, source_index| %>
@@ -10,10 +15,15 @@
 <% else %>
   @else if $source == "<%= sprite.name %>/<%= source.name %>"
 <% end %>
+<% if project.data_uri_sprites.include?(sprite) %>
+    @extend .<%= sprite.name %>_data
+    @include polymer-position($source, $x-offset, $y-offset)
+<% else %>
     $y-offset: $y-offset - <%= sprite.position_of(source) %>px
     background: url(<%= sprite.url %>) $x-offset $y-offset no-repeat
 <% end %>
 <% end %>
+<% end %>
 
 @mixin polymer-position($source, $x-offset: 0px, $y-offset: 0px)
 <% project.sprites.each_with_index do |sprite, sprite_index| %>

data/lib/polymer/version.rb

@@ -1,4 +1,4 @@
 module Polymer
   # The current version of the Polymer library.
-  VERSION = '1.0.0.beta.4'.freeze
+  VERSION = '1.0.0.beta.5'.freeze
 end

data/polymer.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   # rake task. It it completely safe to edit them, but using the rake task
   # is easier.
   s.name              = 'polymer'
-  s.version           = '1.0.0.beta.4'
-  s.date              = '2010-09-29'
+  s.version           = '1.0.0.beta.5'
+  s.date              = '2010-10-31'
   s.rubyforge_project = 'polymer'
 
   # You may safely edit the section below.

metadata

@@ -7,8 +7,8 @@ version: !ruby/object:Gem::Version
   - 0
   - 0
   - beta
-  - 4
-  version: 1.0.0.beta.4
+  - 5
+  version: 1.0.0.beta.5
 platform: ruby
 authors: 
 - Anthony Williams
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-29 00:00:00 +01:00
+date: 2010-10-31 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency