0
@@ -1,7 +1,7 @@
0
 Gem::Specification.new do |s|
0
   s.name = "has_image"
0
-  s.version = "0.2.3"
0
-  s.date = "2008-10-09"
0
+  s.version = "0.3.0"
0
+  s.date = "2008-10-22"
0
   s.add_dependency('mini_magick', '>= 1.2.3')
0
   s.rubyforge_project = 'has-image'  
0
   s.summary = "Lets you attach images with thumbnails to active record models."
0
@@ -27,8 +27,8 @@ Gem::Specification.new do |s|
0
     "test_rails/fixtures/bad_image.jpg",
0
     "test_rails/fixtures/image.jpg",
0
     "test_rails/fixtures/image.png",
0
-    "test_rails/pic.rb",
0
     "test_rails/pic_test.rb",
0
+    "test_rails/complex_pic_test.rb",
0
     "test_rails/schema.rb",
0
     "test_rails/test_helper.rb",
0
     "test/processor_test.rb",

0
@@ -1,8 +1,8 @@
0
 def imagemagick_installed?
0
   `which identify`
0
-   $?.success?
0
+  $?.success?
0
 end
0
 
0
 require 'has_image'
0
 
0
-abort 'ImageMagick not found in PATH. Is it installed?' unless imagemagick_installed?
0
+abort 'ImageMagick not found in PATH. Is it installed?' unless imagemagick_installed?
0
\ No newline at end of file

0
@@ -9,9 +9,9 @@ module HasImage
0
   class FileTooBigError < StorageError ; end
0
   class FileTooSmallError < StorageError ; end
0
   class InvalidGeometryError < ProcessorError ; end
0
-  
0
+
0
   class << self
0
-    
0
+
0
     def included(base) # :nodoc:
0
       base.extend(ClassMethods)
0
     end
0
@@ -68,61 +68,104 @@ module HasImage
0
         :image_too_big_message => "The image is too big."
0
       }
0
     end
0
-    
0
+
0
   end
0
 
0
   module ClassMethods
0
+    # == Using HasImage
0
+    #
0
     # To use HasImage with a Rails model, all you have to do is add a column
0
-    # named "has_image_file." For configuration defaults, you might want to take
0
-    # a look at the default options specified in HasImage#default_options_for.
0
-    # The different setting options are described below.
0
-    # 
0
-    # Options:
0
-    # *  +:resize_to+ - Dimensions to resize to. This should be an aImageMagick {geometry string}[http://www.imagemagick.org/script/command-line-options.php#resize]. Fixed sizes are recommended.
0
-    # *  +:thumbnails</tt> - A hash of thumbnail names and dimensions. The dimensions should be ImageMagick {geometry strings}[http://www.imagemagick.org/script/command-line-options.php#resize]. Fixed sized are recommended.
0
-    # *  +:auto_generate_thumbnails+ - Flag to indicate whether to automatically generate thumbnails when the image_data changes (e.g. on create). If you set this to false, your application code needs to take care of generating Thumbnails, e.g. using +#generate_thumbnail+
0
-    # *  +:delete+ - Flag to indicate if the images should be delete from the storage (e.g. the Filesystem) when the record is destroyed
0
-    # *  +:min_size</tt> - Minimum file size allowed. It's recommended that you set this size in kilobytes.
0
-    # *  +:max_size</tt> - Maximum file size allowed. It's recommended that you set this size in megabytes.
0
-    # *  +:base_path</tt> - Where to install the images. You should probably leave this alone, except for tests.
0
-    # *  +:path_prefix</tt> - Where to install the images, relative to basepath. You should probably leave this alone.
0
-    # *  +:convert_to</tt> - An ImageMagick format to convert images to. Recommended formats: JPEG, PNG, GIF.
0
-    # *  +:output_quality</tt> - Image output quality passed to ImageMagick.
0
-    # *  +:invalid_image_message</tt> - The message that will be shown when the image data can't be processed.
0
-    # *  +:image_too_small_message</tt> - The message that will be shown when the image file is too small. You should ideally set this to something that tells the user what the minimum is.
0
-    # *  +:image_too_big_message</tt> - The message that will be shown when the image file is too big. You should ideally set this to something that tells the user what the maximum is.
0
+    # named "has_image_file." For configuration defaults, you might want to
0
+    # take a look at the default options specified in
0
+    # HasImage#default_options_for. The different setting options are
0
+    # described below.
0
+    #    
0
+    # === Options
0
+    #
0
+    # *  <tt>:resize_to</tt> - Dimensions to resize to. This should be an ImageMagick {geometry string}[http://www.imagemagick.org/script/command-line-options.php#resize]. Fixed sizes are recommended.
0
+    # *  <tt>:thumbnails</tt> - A hash of thumbnail names and dimensions. The dimensions should be ImageMagick {geometry strings}[http://www.imagemagick.org/script/command-line-options.php#resize]. Fixed sized are recommended.
0
+    # *  <tt>:auto_generate_thumbnails</tt> - Flag to indicate whether to automatically generate thumbnails when the image_data changes (e.g. on create). If you set this to false, your application code needs to take care of generating thumbnails, e.g. using +#generate_thumbnail+
0
+    # *  <tt>:delete</tt> - Flag to indicate if the images should be deleted from the storage (e.g. the filesystem) when the record is destroyed.
0
+    # *  <tt>:min_size</tt> - Minimum file size allowed. It's recommended that you set this size in kilobytes.
0
+    # *  <tt>:max_size</tt> - Maximum file size allowed. It's recommended that you set this size in megabytes.
0
+    # *  <tt>:base_path</tt> - Where to install the images.
0
+    # *  <tt>:path_prefix</tt> - Where to install the images, relative to basepath.
0
+    # *  <tt>:convert_to</tt> - An ImageMagick format to convert images to.
0
+    # *  <tt>:output_quality</tt> - Image output quality passed to ImageMagick.
0
+    # *  <tt>:invalid_image_message</tt> - The message that will be shown when the image data can't be processed.
0
+    # *  <tt>:image_too_small_message</tt> - The message that will be shown when the image file is too small. You should ideally set this to something that tells the user what the minimum is.
0
+    # *  <tt>:image_too_big_message</tt> - The message that will be shown when the image file is too big. You should ideally set this to something that tells the user what the maximum is.
0
+    #
0
+    # === Basic Examples
0
     #
0
-    # Examples:
0
     #   has_image # uses all default options
0
     #   has_image :resize_to "800x800", :thumbnails => {:square => "150x150"}
0
     #   has_image :resize_to "100x150", :max_size => 500.kilobytes
0
-    #   has_image :invalid_image_message => "No se puede procesar la imagen."
0
+    #
0
+    # === Some slightly more advanced examples
0
+    #
0
+    # ==== Localizing HasImage
0
+    #
0
+    #  has_image :invalid_image_message => "No se puede procesar la imagen."
0
+    #
0
+    # ==== Using has_image with Capistrano
0
+    #
0
+    # When deploying using Capistrano, you will likely want to keep images
0
+    # under a "system" directory so that newly deployed versions have access
0
+    # to them:
0
+    #
0
+    #   has_image :resize_to => "150x150",
0
+    #     :thumbnails => {
0
+    #       :square => "75x75",
0
+    #     },
0
+    #     :base_path => File.join(Rails.root, 'public', 'system')
0
+    #
0
+    # ==== Testing with HasImage:
0
+    #
0
+    # If you want your tests to actually run the image processing, you should
0
+    # make sure your tests write the image files somewhere outside your public
0
+    # directory. Add something like this to your config/environments/test.rb:
0
+    #
0
+    #   config.after_initialize do
0
+    #     MyClass.has_image_options[:base_path] = File.join(RAILS_ROOT, "tmp") 
0
+    #   end
0
+    #
0
+    # If you want to stub out calls to has_image so that your tests don't do
0
+    # the (slow) image processing, here's an example using Test::Unit and
0
+    # Mocha:
0
+    #
0
+    #   def setup
0
+    #     Photo.any_instance.stubs(:image_data=).returns(true)
0
+    #     Photo.any_instance.stubs(:install_images).returns(true)
0
+    #     Photo.any_instance.stubs(:image_data_valid?).returns(true)
0
+    #   end
0
+    #
0
     def has_image(options = {})
0
       options.assert_valid_keys(HasImage.default_options_for(self).keys)
0
       options = HasImage.default_options_for(self).merge(options)
0
       class_inheritable_accessor :has_image_options
0
       write_inheritable_attribute(:has_image_options, options)
0
-      
0
+
0
       after_create :install_images
0
       after_save :update_images
0
       after_destroy :remove_images
0
-      
0
+
0
       validate_on_create :image_data_valid?
0
-      
0
+
0
       include ModelInstanceMethods
0
       extend  ModelClassMethods
0
-    
0
+
0
     end
0
-    
0
+
0
   end
0
 
0
   module ModelInstanceMethods
0
-    
0
+
0
     # Does the object have an image?
0
     def has_image?
0
       !send(has_image_options[:column]).blank?
0
     end
0
-    
0
+
0
     # Sets the uploaded image data. Image data can be an instance of Tempfile,
0
     # or an instance of any class than inherits from IO.
0
     # aliased as uploaded_data= for compatibility with attachment_fu
0
@@ -137,7 +180,7 @@ module HasImage
0
       nil
0
     end
0
     alias_method :uploaded_data, :image_data
0
-    
0
+
0
     # Is the image data a file that ImageMagick can process, and is it within
0
     # the allowed minimum and maximum sizes?
0
     def image_data_valid?
0
@@ -150,7 +193,7 @@ module HasImage
0
         errors.add_to_base(self.class.has_image_options[:invalid_image_message])
0
       end
0
     end
0
-    
0
+
0
     # Gets the "web path" for the image, or optionally, its thumbnail.
0
     # Aliased as +public_filename+ for compatibility with attachment-Fu
0
     def public_path(thumbnail = nil)
0
@@ -163,29 +206,29 @@ module HasImage
0
     def absolute_path(thumbnail = nil)
0
       storage.filesystem_path_for(self, thumbnail)
0
     end
0
-    
0
+
0
     # Regenerates the thumbails from the main image.
0
     def regenerate_thumbnails!
0
       storage.generate_thumbnails(has_image_id, send(has_image_options[:column]))
0
     end
0
     alias_method :regenerate_thumbnails, :regenerate_thumbnails! #Backwards compat
0
-    
0
+
0
     def generate_thumbnail!(thumb_name)
0
       storage.generate_thumbnail(has_image_id, send(has_image_options[:column]), thumb_name)
0
     end
0
-    
0
+
0
     def width
0
       self[:width] || storage.measure(absolute_path, :width)
0
     end
0
-    
0
+
0
     def height
0
       self[:height] || storage.measure(absolute_path, :height)
0
     end
0
-    
0
+
0
     def image_size
0
       [width, height] * 'x'
0
     end
0
-    
0
+
0
     # Deletes the image from the storage.
0
     def remove_images
0
       return if send(has_image_options[:column]).blank? || !has_image_options[:delete]
0
@@ -204,7 +247,7 @@ module HasImage
0
         end
0
       end
0
     end
0
-    
0
+
0
     # Creates new images and removes the old ones when image_data has been
0
     # set.
0
     def update_images
0
@@ -218,21 +261,13 @@ module HasImage
0
       return if !storage.temp_file
0
       populate_attributes
0
     end
0
-    
0
-    def populate_attributes
0
-      send("#{has_image_options[:column]}=", storage.install_images(self))
0
-      self[:width] = storage.measure(absolute_path, :width) if self.class.column_names.include?('width')
0
-      self[:height] = storage.measure(absolute_path, :height) if self.class.column_names.include?('height')
0
-      save!
0
-    end
0
-    private :populate_attributes
0
-    
0
+
0
     # Gets an instance of the underlying storage functionality. See
0
     # HasImage::Storage.
0
     def storage
0
       @storage ||= HasImage::Storage.new(has_image_options)
0
     end
0
-    
0
+
0
     # By default, just returns the model's id. Since this id is used to divide
0
     # the images up in directories, you can override this to return a related
0
     # model's id if you want the images to be grouped differently. For example,
0
@@ -241,7 +276,17 @@ module HasImage
0
     def has_image_id
0
       id
0
     end
0
-    
0
+
0
+    private
0
+
0
+    def populate_attributes
0
+      send("#{has_image_options[:column]}=", storage.install_images(self))
0
+      self[:width] = storage.measure(absolute_path, :width) if self.class.column_names.include?('width')
0
+      self[:height] = storage.measure(absolute_path, :height) if self.class.column_names.include?('height')
0
+      save!
0
+    end
0
+
0
+
0
   end
0
 
0
   module ModelClassMethods
0
@@ -251,11 +296,11 @@ module HasImage
0
     def thumbnails
0
       has_image_options[:thumbnails]
0
     end
0
-    
0
+
0
     def from_partitioned_path(path)
0
       find HasImage::Storage.id_from_path(path)
0
     end
0
-    
0
+
0
   end
0
 
0
 end

0
@@ -9,17 +9,24 @@ module HasImage
0
     
0
     class << self
0
       
0
-      # "The form of an {extended geometry
0
-      # string}[http://www.imagemagick.org/script/command-line-options.php?#resize] is
0
-      # <width>x<height>{+-}<xoffset>{+-}<yoffset>{%}{!}{<}{>}"
0
+      # The form of an {extended geometry string}[http://www.imagemagick.org/script/command-line-options.php?#resize] is:
0
+      #
0
+      #   <width>x<height>{+-}<xoffset>{+-}<yoffset>{%}{!}{<}{>}
0
       def geometry_string_valid?(string)
0
         string =~ /\A[\d]*x[\d]*([+-][0-9][+-][0-9])?[%@!<>^]?\Z/
0
       end
0
       
0
-      # Arg should be either a file, or a path. This runs ImageMagick's
0
-      # "identify" command and looks for an exit status indicating an error. If
0
-      # there is no error, then ImageMagick has identified the file as something
0
-      # it can work with and it will be converted to the desired output format.
0
+      # Arg should be either a file or a path. This runs ImageMagick's
0
+      # "identify" command and looks for an exit status indicating an error.
0
+      # If there is no error, then ImageMagick has identified the file as
0
+      # something it can work with and it will be converted to the desired
0
+      # output format.
0
+      #
0
+      # Note that this is used in place of any mimetype checks. HasImage
0
+      # assumes that is ImageMagick is able to process the file, then it's OK.
0
+      # Since ImageMagick can be compiled with many different options for
0
+      # supporting various file types (or not) this is safer and more complete
0
+      # than checking the mime type.
0
       def valid?(arg)
0
         arg.close if arg.respond_to?(:close) && !arg.closed?
0
         silence_stderr do
0
@@ -35,13 +42,13 @@ module HasImage
0
       @options = options
0
     end
0
     
0
-    # Create the resized image, and transforms it to the desired output
0
+    # Creates the resized image, and transforms it to the desired output
0
     # format if necessary. 
0
     # 
0
     # +size+ should be a valid ImageMagick {geometry string}[http://www.imagemagick.org/script/command-line-options.php#resize].
0
     # +format+ should be an image format supported by ImageMagick, e.g. "PNG", "JPEG"
0
-    # yields the processed Image file as a file-like
0
-    def process(file, size=options[:resize_to], format=options[:convert_to])
0
+    # If a block is given, it yields the processed image file as a file-like object using IO#read.
0
+    def process(file, size = options[:resize_to], format = options[:convert_to])
0
       unless size.blank? || Processor.geometry_string_valid?(size)
0
         raise InvalidGeometryError.new('"%s" is not a valid ImageMagick geometry string' % size)
0
       end
0
@@ -54,14 +61,13 @@ module HasImage
0
     end
0
     alias_method :resize, :process #Backwards-compat
0
     
0
-    # Gets the given +dimension+ (width/height) from the image file at +path+
0
+    # Gets the given +dimension+ (width/height) from the image file at +path+.
0
     def measure(path, dimension)
0
       MiniMagick::Image.from_file(path)[dimension.to_sym]
0
     end
0
     
0
   private
0
-    # operate on the image with MiniMagick
0
-    # yields a MiniMagick::Image object
0
+    # Operates on the image with MiniMagick. Yields a MiniMagick::Image object.
0
     def with_image(file)
0
       path = file.respond_to?(:path) ? file.path : file
0
       file.close if file.respond_to?(:close) && !file.closed?
0
@@ -77,7 +83,6 @@ module HasImage
0
       end
0
     end
0
   
0
-    # +image+ should be a MiniMagick::Image and +size+ a Geometry String
0
     # Image resizing is placed in a separate method for easy monkey-patching.
0
     # This is intended to be invoked from resize, rather than directly.
0
     # By default, the following ImageMagick functionality is invoked:
0
@@ -87,6 +92,8 @@ module HasImage
0
     # * gravity[http://www.imagemagick.org/script/command-line-options.php#gravity]
0
     # * extent[http://www.imagemagick.org/script/command-line-options.php#extent]
0
     # * quality[http://www.imagemagick.org/script/command-line-options.php#quality]
0
+    #
0
+    # +image+ should be a MiniMagick::Image. +size+ should be a geometry string.
0
     def resize_image(image, size)
0
       image.combine_options do |commands|
0
         commands.send("auto-orient".to_sym)

0
@@ -14,11 +14,11 @@ class PicTest < Test::Unit::TestCase
0
     Pic.has_image_options = HasImage.default_options_for(Pic)
0
     Pic.has_image_options[:base_path] = File.join(RAILS_ROOT, 'tmp')
0
   end
0
-  
0
+
0
   def teardown
0
     FileUtils.rm_rf(File.join(RAILS_ROOT, 'tmp', 'pics'))
0
   end
0
-  
0
+
0
   def test_should_be_valid
0
     @pic = Pic.new(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
0
     assert @pic.valid? , "#{@pic.errors.full_messages.to_sentence}"
0
@@ -54,24 +54,24 @@ class PicTest < Test::Unit::TestCase
0
     @pic.image_data = fixture_file_upload("/image.png", "image/png")
0
     assert @pic.save!
0
   end
0
-  
0
+
0
   def test_finding_from_url_path
0
     @pic = Pic.new(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
0
     @pic.save!
0
     path = HasImage::Storage.partitioned_path @pic.id
0
     assert_equal @pic, Pic.from_partitioned_path(path)
0
   end
0
-  
0
+
0
   def test_default_options_respect_table_name
0
     assert_equal 'pics', HasImage.default_options_for(PicWithDifferentTableName)[:path_prefix]
0
   end
0
-  
0
+
0
   def test_generate_thumbnails_on_create
0
     Pic.has_image_options[:thumbnails] = {:tiny => "16x16"}
0
     @pic = Pic.create!(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
0
     assert File.exist?(@pic.absolute_path(:tiny))
0
   end
0
-  
0
+
0
   def test_doesnt_generate_thumbnails_if_option_disabled
0
     Pic.has_image_options[:thumbnails] = {:tiny => "16x16"}
0
     Pic.has_image_options[:auto_generate_thumbnails] = false
0
@@ -96,7 +96,7 @@ class PicTest < Test::Unit::TestCase
0
     @pic.save!
0
     assert @pic.destroy
0
   end
0
-  
0
+
0
   def test_destroy_should_not_remove_image_file_if_option_is_set
0
     Pic.has_image_options[:delete] = false
0
     @pic = Pic.create!(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
0
@@ -123,7 +123,7 @@ class PicTest < Test::Unit::TestCase
0
     @pic.valid?
0
     assert @pic.valid?
0
   end
0
-  
0
+
0
   def test_dimension_getters
0
     Pic.has_image_options[:resize_to] = "100x200"
0
     pic = Pic.create!(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
0
@@ -131,7 +131,7 @@ class PicTest < Test::Unit::TestCase
0
     assert_equal 200, pic.height
0
     assert_equal '100x200', pic.image_size
0
   end
0
-  
0
+
0
   def test_image_isnt_resized_when_resize_to_set_to_nil
0
     Pic.has_image_options[:resize_to] = nil
0
     pic = Pic.create!(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
0
@@ -139,7 +139,7 @@ class PicTest < Test::Unit::TestCase
0
     assert_equal 1916, pic.width
0
     assert_equal 1990, pic.height
0
   end
0
-  
0
+
0
   def test_image_isnt_resized_but_converted_when_resize_to_set_to_nil
0
     Pic.has_image_options[:resize_to] = nil
0
     Pic.has_image_options[:convert_to] = 'PNG'
0
@@ -149,6 +149,5 @@ class PicTest < Test::Unit::TestCase
0
     assert_equal 1916, pic.width
0
     assert_equal 1990, pic.height
0
   end
0
-  
0
-end
0
 
0
+end
0
\ No newline at end of file