test_rails/complex_pic_test.rb @@ -1,7 +1,7 @@ Gem::Specification.new do |s| s.name = "has_image" - s.version = "0.2.3" - s.date = "2008-10-09" + s.version = "0.3.0" + s.date = "2008-10-22" s.add_dependency('mini_magick', '>= 1.2.3') s.rubyforge_project = 'has-image' s.summary = "Lets you attach images with thumbnails to active record models." @@ -27,8 +27,8 @@ Gem::Specification.new do |s| "test_rails/fixtures/bad_image.jpg", "test_rails/fixtures/image.jpg", "test_rails/fixtures/image.png", - "test_rails/pic.rb", "test_rails/pic_test.rb", + "test_rails/complex_pic_test.rb", "test_rails/schema.rb", "test_rails/test_helper.rb", "test/processor_test.rb", has_image.gemspec @@ -1,8 +1,8 @@ def imagemagick_installed? `which identify` - $?.success? + $?.success? end require 'has_image' -abort 'ImageMagick not found in PATH. Is it installed?' unless imagemagick_installed? +abort 'ImageMagick not found in PATH. Is it installed?' unless imagemagick_installed? \ No newline at end of file init.rb @@ -9,9 +9,9 @@ module HasImage class FileTooBigError < StorageError ; end class FileTooSmallError < StorageError ; end class InvalidGeometryError < ProcessorError ; end - + class << self - + def included(base) # :nodoc: base.extend(ClassMethods) end @@ -68,61 +68,104 @@ module HasImage :image_too_big_message => "The image is too big." } end - + end module ClassMethods + # == Using HasImage + # # To use HasImage with a Rails model, all you have to do is add a column - # named "has_image_file." For configuration defaults, you might want to take - # a look at the default options specified in HasImage#default_options_for. - # The different setting options are described below. - # - # Options: - # * +: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. - # * +: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. - # * +: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+ - # * +:delete+ - Flag to indicate if the images should be delete from the storage (e.g. the Filesystem) when the record is destroyed - # * +:min_size</tt> - Minimum file size allowed. It's recommended that you set this size in kilobytes. - # * +:max_size</tt> - Maximum file size allowed. It's recommended that you set this size in megabytes. - # * +:base_path</tt> - Where to install the images. You should probably leave this alone, except for tests. - # * +:path_prefix</tt> - Where to install the images, relative to basepath. You should probably leave this alone. - # * +:convert_to</tt> - An ImageMagick format to convert images to. Recommended formats: JPEG, PNG, GIF. - # * +:output_quality</tt> - Image output quality passed to ImageMagick. - # * +:invalid_image_message</tt> - The message that will be shown when the image data can't be processed. - # * +: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. - # * +: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. + # named "has_image_file." For configuration defaults, you might want to + # take a look at the default options specified in + # HasImage#default_options_for. The different setting options are + # described below. + # + # === Options + # + # * <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. + # * <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. + # * <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+ + # * <tt>:delete</tt> - Flag to indicate if the images should be deleted from the storage (e.g. the filesystem) when the record is destroyed. + # * <tt>:min_size</tt> - Minimum file size allowed. It's recommended that you set this size in kilobytes. + # * <tt>:max_size</tt> - Maximum file size allowed. It's recommended that you set this size in megabytes. + # * <tt>:base_path</tt> - Where to install the images. + # * <tt>:path_prefix</tt> - Where to install the images, relative to basepath. + # * <tt>:convert_to</tt> - An ImageMagick format to convert images to. + # * <tt>:output_quality</tt> - Image output quality passed to ImageMagick. + # * <tt>:invalid_image_message</tt> - The message that will be shown when the image data can't be processed. + # * <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. + # * <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. + # + # === Basic Examples # - # Examples: # has_image # uses all default options # has_image :resize_to "800x800", :thumbnails => {:square => "150x150"} # has_image :resize_to "100x150", :max_size => 500.kilobytes - # has_image :invalid_image_message => "No se puede procesar la imagen." + # + # === Some slightly more advanced examples + # + # ==== Localizing HasImage + # + # has_image :invalid_image_message => "No se puede procesar la imagen." + # + # ==== Using has_image with Capistrano + # + # When deploying using Capistrano, you will likely want to keep images + # under a "system" directory so that newly deployed versions have access + # to them: + # + # has_image :resize_to => "150x150", + # :thumbnails => { + # :square => "75x75", + # }, + # :base_path => File.join(Rails.root, 'public', 'system') + # + # ==== Testing with HasImage: + # + # If you want your tests to actually run the image processing, you should + # make sure your tests write the image files somewhere outside your public + # directory. Add something like this to your config/environments/test.rb: + # + # config.after_initialize do + # MyClass.has_image_options[:base_path] = File.join(RAILS_ROOT, "tmp") + # end + # + # If you want to stub out calls to has_image so that your tests don't do + # the (slow) image processing, here's an example using Test::Unit and + # Mocha: + # + # def setup + # Photo.any_instance.stubs(:image_data=).returns(true) + # Photo.any_instance.stubs(:install_images).returns(true) + # Photo.any_instance.stubs(:image_data_valid?).returns(true) + # end + # def has_image(options = {}) options.assert_valid_keys(HasImage.default_options_for(self).keys) options = HasImage.default_options_for(self).merge(options) class_inheritable_accessor :has_image_options write_inheritable_attribute(:has_image_options, options) - + after_create :install_images after_save :update_images after_destroy :remove_images - + validate_on_create :image_data_valid? - + include ModelInstanceMethods extend ModelClassMethods - + end - + end module ModelInstanceMethods - + # Does the object have an image? def has_image? !send(has_image_options[:column]).blank? end - + # Sets the uploaded image data. Image data can be an instance of Tempfile, # or an instance of any class than inherits from IO. # aliased as uploaded_data= for compatibility with attachment_fu @@ -137,7 +180,7 @@ module HasImage nil end alias_method :uploaded_data, :image_data - + # Is the image data a file that ImageMagick can process, and is it within # the allowed minimum and maximum sizes? def image_data_valid? @@ -150,7 +193,7 @@ module HasImage errors.add_to_base(self.class.has_image_options[:invalid_image_message]) end end - + # Gets the "web path" for the image, or optionally, its thumbnail. # Aliased as +public_filename+ for compatibility with attachment-Fu def public_path(thumbnail = nil) @@ -163,29 +206,29 @@ module HasImage def absolute_path(thumbnail = nil) storage.filesystem_path_for(self, thumbnail) end - + # Regenerates the thumbails from the main image. def regenerate_thumbnails! storage.generate_thumbnails(has_image_id, send(has_image_options[:column])) end alias_method :regenerate_thumbnails, :regenerate_thumbnails! #Backwards compat - + def generate_thumbnail!(thumb_name) storage.generate_thumbnail(has_image_id, send(has_image_options[:column]), thumb_name) end - + def width self[:width] || storage.measure(absolute_path, :width) end - + def height self[:height] || storage.measure(absolute_path, :height) end - + def image_size [width, height] * 'x' end - + # Deletes the image from the storage. def remove_images return if send(has_image_options[:column]).blank? || !has_image_options[:delete] @@ -204,7 +247,7 @@ module HasImage end end end - + # Creates new images and removes the old ones when image_data has been # set. def update_images @@ -218,21 +261,13 @@ module HasImage return if !storage.temp_file populate_attributes end - - def populate_attributes - send("#{has_image_options[:column]}=", storage.install_images(self)) - self[:width] = storage.measure(absolute_path, :width) if self.class.column_names.include?('width') - self[:height] = storage.measure(absolute_path, :height) if self.class.column_names.include?('height') - save! - end - private :populate_attributes - + # Gets an instance of the underlying storage functionality. See # HasImage::Storage. def storage @storage ||= HasImage::Storage.new(has_image_options) end - + # By default, just returns the model's id. Since this id is used to divide # the images up in directories, you can override this to return a related # model's id if you want the images to be grouped differently. For example, @@ -241,7 +276,17 @@ module HasImage def has_image_id id end - + + private + + def populate_attributes + send("#{has_image_options[:column]}=", storage.install_images(self)) + self[:width] = storage.measure(absolute_path, :width) if self.class.column_names.include?('width') + self[:height] = storage.measure(absolute_path, :height) if self.class.column_names.include?('height') + save! + end + + end module ModelClassMethods @@ -251,11 +296,11 @@ module HasImage def thumbnails has_image_options[:thumbnails] end - + def from_partitioned_path(path) find HasImage::Storage.id_from_path(path) end - + end end lib/has_image.rb @@ -9,17 +9,24 @@ module HasImage class << self - # "The form of an {extended geometry - # string}[http://www.imagemagick.org/script/command-line-options.php?#resize] is - # <width>x<height>{+-}<xoffset>{+-}<yoffset>{%}{!}{<}{>}" + # The form of an {extended geometry string}[http://www.imagemagick.org/script/command-line-options.php?#resize] is: + # + # <width>x<height>{+-}<xoffset>{+-}<yoffset>{%}{!}{<}{>} def geometry_string_valid?(string) string =~ /\A[\d]*x[\d]*([+-][0-9][+-][0-9])?[%@!<>^]?\Z/ end - # Arg should be either a file, or a path. This runs ImageMagick's - # "identify" command and looks for an exit status indicating an error. If - # there is no error, then ImageMagick has identified the file as something - # it can work with and it will be converted to the desired output format. + # Arg should be either a file or a path. This runs ImageMagick's + # "identify" command and looks for an exit status indicating an error. + # If there is no error, then ImageMagick has identified the file as + # something it can work with and it will be converted to the desired + # output format. + # + # Note that this is used in place of any mimetype checks. HasImage + # assumes that is ImageMagick is able to process the file, then it's OK. + # Since ImageMagick can be compiled with many different options for + # supporting various file types (or not) this is safer and more complete + # than checking the mime type. def valid?(arg) arg.close if arg.respond_to?(:close) && !arg.closed? silence_stderr do @@ -35,13 +42,13 @@ module HasImage @options = options end - # Create the resized image, and transforms it to the desired output + # Creates the resized image, and transforms it to the desired output # format if necessary. # # +size+ should be a valid ImageMagick {geometry string}[http://www.imagemagick.org/script/command-line-options.php#resize]. # +format+ should be an image format supported by ImageMagick, e.g. "PNG", "JPEG" - # yields the processed Image file as a file-like - def process(file, size=options[:resize_to], format=options[:convert_to]) + # If a block is given, it yields the processed image file as a file-like object using IO#read. + def process(file, size = options[:resize_to], format = options[:convert_to]) unless size.blank? || Processor.geometry_string_valid?(size) raise InvalidGeometryError.new('"%s" is not a valid ImageMagick geometry string' % size) end @@ -54,14 +61,13 @@ module HasImage end alias_method :resize, :process #Backwards-compat - # Gets the given +dimension+ (width/height) from the image file at +path+ + # Gets the given +dimension+ (width/height) from the image file at +path+. def measure(path, dimension) MiniMagick::Image.from_file(path)[dimension.to_sym] end private - # operate on the image with MiniMagick - # yields a MiniMagick::Image object + # Operates on the image with MiniMagick. Yields a MiniMagick::Image object. def with_image(file) path = file.respond_to?(:path) ? file.path : file file.close if file.respond_to?(:close) && !file.closed? @@ -77,7 +83,6 @@ module HasImage end end - # +image+ should be a MiniMagick::Image and +size+ a Geometry String # Image resizing is placed in a separate method for easy monkey-patching. # This is intended to be invoked from resize, rather than directly. # By default, the following ImageMagick functionality is invoked: @@ -87,6 +92,8 @@ module HasImage # * gravity[http://www.imagemagick.org/script/command-line-options.php#gravity] # * extent[http://www.imagemagick.org/script/command-line-options.php#extent] # * quality[http://www.imagemagick.org/script/command-line-options.php#quality] + # + # +image+ should be a MiniMagick::Image. +size+ should be a geometry string. def resize_image(image, size) image.combine_options do |commands| commands.send("auto-orient".to_sym) lib/has_image/processor.rb @@ -14,11 +14,11 @@ class PicTest < Test::Unit::TestCase Pic.has_image_options = HasImage.default_options_for(Pic) Pic.has_image_options[:base_path] = File.join(RAILS_ROOT, 'tmp') end - + def teardown FileUtils.rm_rf(File.join(RAILS_ROOT, 'tmp', 'pics')) end - + def test_should_be_valid @pic = Pic.new(:image_data => fixture_file_upload("/image.jpg", "image/jpeg")) assert @pic.valid? , "#{@pic.errors.full_messages.to_sentence}" @@ -54,24 +54,24 @@ class PicTest < Test::Unit::TestCase @pic.image_data = fixture_file_upload("/image.png", "image/png") assert @pic.save! end - + def test_finding_from_url_path @pic = Pic.new(:image_data => fixture_file_upload("/image.jpg", "image/jpeg")) @pic.save! path = HasImage::Storage.partitioned_path @pic.id assert_equal @pic, Pic.from_partitioned_path(path) end - + def test_default_options_respect_table_name assert_equal 'pics', HasImage.default_options_for(PicWithDifferentTableName)[:path_prefix] end - + def test_generate_thumbnails_on_create Pic.has_image_options[:thumbnails] = {:tiny => "16x16"} @pic = Pic.create!(:image_data => fixture_file_upload("/image.jpg", "image/jpeg")) assert File.exist?(@pic.absolute_path(:tiny)) end - + def test_doesnt_generate_thumbnails_if_option_disabled Pic.has_image_options[:thumbnails] = {:tiny => "16x16"} Pic.has_image_options[:auto_generate_thumbnails] = false @@ -96,7 +96,7 @@ class PicTest < Test::Unit::TestCase @pic.save! assert @pic.destroy end - + def test_destroy_should_not_remove_image_file_if_option_is_set Pic.has_image_options[:delete] = false @pic = Pic.create!(:image_data => fixture_file_upload("/image.jpg", "image/jpeg")) @@ -123,7 +123,7 @@ class PicTest < Test::Unit::TestCase @pic.valid? assert @pic.valid? end - + def test_dimension_getters Pic.has_image_options[:resize_to] = "100x200" pic = Pic.create!(:image_data => fixture_file_upload("/image.jpg", "image/jpeg")) @@ -131,7 +131,7 @@ class PicTest < Test::Unit::TestCase assert_equal 200, pic.height assert_equal '100x200', pic.image_size end - + def test_image_isnt_resized_when_resize_to_set_to_nil Pic.has_image_options[:resize_to] = nil pic = Pic.create!(:image_data => fixture_file_upload("/image.jpg", "image/jpeg")) @@ -139,7 +139,7 @@ class PicTest < Test::Unit::TestCase assert_equal 1916, pic.width assert_equal 1990, pic.height end - + def test_image_isnt_resized_but_converted_when_resize_to_set_to_nil Pic.has_image_options[:resize_to] = nil Pic.has_image_options[:convert_to] = 'PNG' @@ -149,6 +149,5 @@ class PicTest < Test::Unit::TestCase assert_equal 1916, pic.width assert_equal 1990, pic.height end - -end +end \ No newline at end of file test_rails/pic_test.rb test_rails/compex_pic_test.rb cb5ffb6f02bc7d7439b2e195a88c9851f93812ec Norman Clarke norman@randomba.org http://github.com/norman/has_image/commit/756d467405fc9cc7c275bd479f8d79eff1480b11 756d467405fc9cc7c275bd479f8d79eff1480b11 2008-10-22T06:59:24-07:00 2008-10-22T06:59:24-07:00 Cleaning up exapanding documentation. Cleaning up whitespace. Bumped Gem version. d3846bbc30129a9f1eb88c30e26d3d25cb2908c2 Norman Clarke norman@randomba.org