sprite-factory 1.3.0 → 1.4.1

data/README.md

@@ -1,5 +1,5 @@
-Sprite Factory
-==============
+Sprite Factory (v1.4.1)
+=======================
 
 The sprite factory is a ruby library that can be used to generate
 [CSS sprites](http://www.alistapart.com/articles/sprites). It combines
@@ -14,6 +14,7 @@ The library provides:
  * support for any stylesheet syntax, including [CSS](http://www.w3.org/Style/CSS/) and [Sass](http://sass-lang.com/).
  * support for any image library, including [RMagick](http://rmagick.rubyforge.org/) and [ChunkyPNG](https://github.com/wvanbergen/chunky_png).
  * support for pngcrush'n the generated image file
+ * compatible with Rails 3.1 asset pipeline
 
 
 Installation
@@ -73,19 +74,20 @@ to keep the markup semantic it is common to use an `img` tag with a dummy `src=s
 Customization
 =============
 
-Much of the behavior can be customized by overriding the following options:
-
- - `:output`   - specify output location for generated files
- - `:layout`   - specify layout algorithm (horizontal, vertical or packed)
- - `:style`    - specify output style (css or sass)
- - `:library`  - specify image library to use (rmagick or chunkypng)
- - `:selector` - specify custom css selector (see below)
- - `:csspath`  - specify custom path for css image url (see below)
- - `:padding`  - add padding to each sprite
- - `:width`    - fix width of each sprite to a specific size
- - `:height`   - fix height of each sprite to a specific size
- - `:pngcrush` - pngcrush the generated output image (if pngcrush is available)
- - `:nocss`    - suppress generation of output css file (`run!` returns css content as a string instead)
+Much of the behavior can be customized by overriding the following options: 
+
+ - `:layout`       - specify layout algorithm (horizontal, vertical or packed)
+ - `:style`        - specify stylesheet syntax (css, scss or sass)
+ - `:library`      - specify image library to use (rmagick or chunkypng)
+ - `:selector`     - specify custom css selector (see below)
+ - `:csspath`      - specify custom path for css image url (see below)
+ - `:output_image` - specify output location for generated image (default: <input folder>.png)
+ - `:output_style` - specify output location for generated stylesheet (default: <input folder>.<style>)
+ - `:pngcrush`     - pngcrush the generated output image (if pngcrush is available)
+ - `:padding`      - add padding to each sprite
+ - `:width`        - fix width of each sprite to a specific size
+ - `:height`       - fix height of each sprite to a specific size
+ - `:nocss`        - suppress generation of output style file (`run!` returns css content as a string instead)
 
 Options can be passed as command line arguments to the `sf` script:
 
@@ -155,7 +157,17 @@ For most CDN's, you can prepend a simple string to the image name:
 
     # generates:  url(http://s3.amazonaws.com/icons.png)
 
-For more control, you can provide a lambda function and generate your own paths:
+For more control, a simple token replacement can be performed using the $IMAGE token. For example, to embed ERB
+into the generated style file and let Rails generate the paths you can use:
+
+    SpriteFactory.run('images/icons',
+                      :csspath => "<%= image_path('$IMAGE') %>")
+
+    # generates:  url(<%= image_path('icons.png') %>)
+
+>> _this assumes Rails will post-process the css file with ERB (e.g. using sprockets in the Rails 3.1 asset pipeline)_
+
+For full control, you can provide a lambda function and generate your own paths:
 
     SpriteFactory.run('images/icons',
                        :csspath => lambda{|image| image_path(image)})
@@ -192,10 +204,56 @@ value is a hash of image metadata that includes the following:
 
 (*NOTE*: the image coords can differ form the css sprite coords when padding or fixed width/height options are specified)
 
+Using sprite-factory with the Rails 3.1 asset pipeline
+======================================================
+
+The sprite-factory gem (>= v1.4.0) plays nice with the upcoming Rails 3.1 asset pipeline with a few simple steps:
+
+Add the sprite-factory to your Gemfile, including your chosen image library dependency:
+
+    group :assets do
+      gem 'sprite-factory', '>= 1.4.0'
+      gem 'chunky_png'
+    end
+
+Store your images in Rails 3.1 `app/assets/images` sub-folders, e.g
+
+    app/assets/images/avatars/*.png
+    app/assets/images/icons/*.png
+    ...
+
+Create a Rake task for regenerating your sprites, e.g. in `lib/tasks/assets.rake`
+
+    require 'sprite_factory'
+
+    namespace :assets do
+      desc 'recreate sprite images and css'
+      task :resprite => :environment do 
+        SpriteFactory.library = :chunkypng                   # use chunkypng as underlying image library
+        SpriteFactory.csspath = "<%= asset_path '$IMAGE' %>" # embed ERB into css file to be evaluated by asset pipeline
+        SpriteFactory.run!('app/assets/images/avatars', :output_style => 'app/assets/stylesheets/avatars.css.erb')
+        SpriteFactory.run!('app/assets/images/icons',   :output_style => 'app/assets/stylesheets/icons.css.erb')
+        # ... etc ...
+      end
+    end
+
+Run the rake task
+
+    bundle exec rake assets:resprite
+
+Generates
+
+ * sprite images in `app/assets/images`
+ * sprite styles in `app/assets/stylesheets` - automatically picked up by the asset pipeline and included in your generated application.css
+
+You can find out more here:
+
+ * [Sprite Factory 1.4.1 and the Rails Asset Pipeline](http://codeincomplete.com/posts/2011/8/6/sprite_factory_1_4_1/)
+
 Extending the Library
 =====================
 
-The sprite factory library can also be extended in a number of other ways.
+The sprite factory library can be extended in a number of other ways.
 
  * provide a custom layout algorithm in the `SpriteFactory::Layout` module.
  * provide a custom style generator in the `SpriteFactory::Style` module.

data/RELEASE_NOTES.md

@@ -1,4 +1,14 @@
 
+August 5th 2011 - v1.4.1
+------------------------
+ * added support for `:style => :scss` to generate .scss file (even though content will be almost exactly same as .css style)
+ * deprecated `:output` option and replaced it with 2 new explicit `:output_image` and `:output_style` options
+ * updated RELEASE NOTES to include setup for use with Rails 3.1 asset pipeline
+
+Auguest 5th 2011 - v1.4.0
+-------------------------
+ * (not available)
+
 July 9th 2011 - v1.3.0
 ----------------------
 

data/bin/sf

@@ -19,21 +19,23 @@ op.on("-v", "--version") do
   exit
 end
 
-output_help   = "specify output location, without any extension"
-layout_help   = "specify layout orientation   ( horizontal, vertical, packed )"
-style_help    = "specify output style format  ( css, sass )"
-library_help  = "specify image library to use ( rmagic, chunkypng )"
-selector_help = "specify custom selector to use for each css rule ( default: 'img.' )"
-csspath_help  = "specify custom path to use for css image urls ( default: output file's basename )"
-pngcrush_help = "use pngcrush to optimize generated image"
-
-op.on("--output   [PATH]",        output_help)   {|value| options[:output]   = value }
-op.on("--layout   [ORIENTATION]", layout_help)   {|value| options[:layout]   = value }
-op.on("--style    [STYLE]",       style_help)    {|value| options[:style]    = value }
-op.on("--library  [LIBRARY]",     library_help)  {|value| options[:library]  = value }
-op.on("--selector [SELECTOR]",    selector_help) {|value| options[:selector] = value }
-op.on("--csspath  [CSSPATH]",     csspath_help)  {|value| options[:csspath]  = value }
-op.on("--pngcrush",               pngcrush_help) {|value| options[:pngcrush] = value }
+layout_help       = "specify layout orientation   ( horizontal, vertical, packed )"
+style_help        = "specify stylesheet syntax  ( css, scss, sass )"
+library_help      = "specify image library to use ( rmagic, chunkypng )"
+selector_help     = "specify custom selector to use for each css rule ( default: 'img.' )"
+csspath_help      = "specify custom path to use for css image urls ( default: output image basename )"
+output_image_help = "specify output location for generated image ( default: <input folder>.png )"
+output_style_help = "specify output location for generated stylesheet ( default: <input folder>.<style>)"
+pngcrush_help     = "use pngcrush to optimize generated image"
+
+op.on("--layout       [ORIENTATION]", layout_help)       {|value| options[:layout]       = value }
+op.on("--style        [STYLE]",       style_help)        {|value| options[:style]        = value }
+op.on("--library      [LIBRARY]",     library_help)      {|value| options[:library]      = value }
+op.on("--selector     [SELECTOR]",    selector_help)     {|value| options[:selector]     = value }
+op.on("--csspath      [CSSPATH]",     csspath_help)      {|value| options[:csspath]      = value }
+op.on("--output-image [PATH]",        output_image_help) {|value| options[:output_image] = value }
+op.on("--output-style [PATH]",        output_style_help) {|value| options[:output_style] = value }
+op.on("--pngcrush",                   pngcrush_help)     {|value| options[:pngcrush]     = value }
 
 begin
   op.parse!(ARGV)

data/lib/sprite_factory.rb

@@ -2,7 +2,7 @@ module SpriteFactory
   
   #----------------------------------------------------------------------------
 
-  VERSION     = "1.3.0"
+  VERSION     = "1.4.1"
   SUMMARY     = "Automatic CSS sprite generator"
   DESCRIPTION = "Combines individual images from a directory into a single sprite image file and creates an appropriate CSS stylesheet"
   LIB         = File.dirname(__FILE__)

data/lib/sprite_factory/runner.rb

@@ -30,8 +30,10 @@ module SpriteFactory
       raise RuntimeError, "unknown library #{library_name}"   if !Library.respond_to?(library_name)
 
       raise RuntimeError, "input must be a single directory"  if input.nil?  || input.to_s.empty? || !File.directory?(input)
-      raise RuntimeError, "no output file specified"          if output.nil? || output.to_s.empty?
       raise RuntimeError, "no image files found"              if image_files.empty?
+      raise RuntimeError, "no output file specified"          if output.to_s.empty?
+      raise RuntimeError, "no output image file specified"    if output_image_file.to_s.empty?
+      raise RuntimeError, "no output style file specified"    if output_style_file.to_s.empty?
 
       raise RuntimeError, "set :width for fixed width, or :hpadding for horizontal padding, but not both." if width  && !hpadding.zero?
       raise RuntimeError, "set :height for fixed height, or :vpadding for vertical padding, but not both." if height && !vpadding.zero?
@@ -64,10 +66,6 @@ module SpriteFactory
   
     private
 
-    def output
-      config[:output] || input
-    end
-
     def selector
       config[:selector]
     end
@@ -100,16 +98,20 @@ module SpriteFactory
       config[:height]
     end
 
+    def output
+      config[:output] || input
+    end
+
     def output_image_file
-      "#{output}.png" if output
+      config[:output_image] || "#{output}.png"
     end
 
     def output_style_file
-      "#{output}.#{style_name}" if output and style_name
+      config[:output_style] || "#{output}.#{style_name}"
     end
 
     def nocss?
-      config[:nocss] # set true if you dont want an output css file generated (e.g. you will take the #run! output and store it yourself)
+      config[:nocss] # set true if you dont want an output style file generated (e.g. you will take the #run! output and store it yourself)
     end
 
     def custom_style_file
@@ -128,7 +130,7 @@ module SpriteFactory
           File.join(custom, base)    # allow custom path with simple prepend
         end
       else
-        base                         # otherwise, just default to basename of the output image
+        base                         # otherwise, just default to basename of the output image file
       end
     end
 

data/lib/sprite_factory/style.rb

@@ -17,6 +17,20 @@ module SpriteFactory
 
     #----------------------------------------------------------------------------
 
+    def self.scss(selector, name, attributes)
+      css(selector, name, attributes) # scss is a superset of css, but we dont actually need any of the extra bits, so just defer to the css generator instead
+    end
+
+    def self.scss_style(attributes)
+      css_style(attributes)
+    end
+
+    def self.scss_comment(comment)
+      css_comment(attributes)
+    end
+
+    #----------------------------------------------------------------------------
+
     def self.sass(selector, name, attributes)
       "#{selector}#{name}\n" + sass_style(attributes)
     end

data/sprite_factory.gemspec

@@ -19,10 +19,9 @@ Gem::Specification.new do |s|
   s.has_rdoc         = false
   s.extra_rdoc_files = ["README.md"]
   s.rdoc_options     = ["--charset=UTF-8"]
-  
-  s.files         = `git ls-files `.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
+  s.files            = `git ls-files `.split("\n")
+  s.test_files       = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables      = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths    = ["lib"]
 
 end

data/test/runner_test.rb

@@ -39,6 +39,16 @@ module SpriteFactory
         assert_equal(:css,                    r.style_name)
         assert_equal(:rmagick,                r.library_name)
 
+        r = Runner.new(REGULAR_PATH, :output_image => "foo.png", :output_style => "bar.css.sass.erb")
+        assert_equal(REGULAR_PATH,            r.input)
+        assert_equal(REGULAR_PATH,            r.output)
+        assert_equal("foo.png",               r.output_image_file)
+        assert_equal("bar.css.sass.erb",      r.output_style_file)
+        assert_equal(REGULAR,                 r.image_files)
+        assert_equal(:horizontal,             r.layout_name)
+        assert_equal(:css,                    r.style_name)
+        assert_equal(:rmagick,                r.library_name)
+
         r = Runner.new(REGULAR_PATH, :layout => :vertical, :library => :chunkypng, :style => :sass)
         assert_equal(REGULAR_PATH,            r.input)
         assert_equal(REGULAR_PATH,            r.output)

data/test/style_test.rb

@@ -19,6 +19,14 @@ module SpriteFactory
 
     #--------------------------------------------------------------------------
 
+    def test_scss
+      expected = "img.foo { width: 30px; height: 40px; background: url(path/to/image.png) -10px -20px no-repeat; }"
+      actual   = Style.scss("img.", "foo", TEST_ATTRIBUTES)
+      assert_equal(expected, actual)
+    end
+
+    #--------------------------------------------------------------------------
+
     def test_sass
       expected = "img.foo\n  width: 30px\n  height: 40px\n  background: url(path/to/image.png) -10px -20px no-repeat\n"
       actual   = Style.sass("img.", "foo", TEST_ATTRIBUTES)

metadata

@@ -1,58 +1,48 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: sprite-factory
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 1
-  - 3
-  - 0
-  version: 1.3.0
+version: !ruby/object:Gem::Version
+  version: 1.4.1
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Jake Gordon
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-07-09 00:00:00 -07:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-08-06 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rmagick
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &12869300 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: chunky_png
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *12869300
+- !ruby/object:Gem::Dependency
+  name: chunky_png
+  requirement: &12901920 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id002
-description: Combines individual images from a directory into a single sprite image file and creates an appropriate CSS stylesheet
-email: 
+  prerelease: false
+  version_requirements: *12901920
+description: Combines individual images from a directory into a single sprite image
+  file and creates an appropriate CSS stylesheet
+email:
 - jake@codeincomplete.com
-executables: 
+executables:
 - sf
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.md
-files: 
+files:
 - .gitignore
 - LICENSE
 - README.md
@@ -134,37 +124,29 @@ files:
 - test/runner_test.rb
 - test/style_test.rb
 - test/test_case.rb
-has_rdoc: true
 homepage: https://github.com/jakesgordon/sprite-factory
 licenses: []
-
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --charset=UTF-8
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.7
 signing_key: 
 specification_version: 3
 summary: Automatic CSS sprite generator
 test_files: []
-