has_image 0.1.0

data/CHANGELOG

@@ -0,0 +1,3 @@
+2008-07-25 Norman Clarke <norman@randomba.org>
+
+	* First public release.	

data/FAQ

@@ -0,0 +1,25 @@
+= Frequently Asked Questions
+
+HasImage is too new to have many FAQ items yet. {Ask
+me}[mailto:norman@randomba.org] and they will be included; this is a work in
+progress.
+
+= How do I validate the mime type of my uploaded images?
+
+You don't. Rather than examine the mime type, HasImage runs the "identify"
+command on the file to determine if it is processable by ImageMagick, and if
+it is, converts it to the format you specify, which defaults to JPEG.
+
+This is better than checking for mime types, because your users may upload
+exotic image types that you didn't even realize would work, such as Truevision
+Targa images, or Seattle Film Works files.
+
+If you wish to give users a list of file types they can upload, a good start
+would be jpeg, png, bmp, and maybe gif and ttf if your installation of
+ImageMagick understands them. You can find out what image types your
+ImageMagick understands by running:
+
+identify -list format
+
+Ideally, if your users just upload files that "look like" images on their
+computers, it HasImage should "just work."

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,139 @@
+= HasImage[http://github.com/norman/has_image] -- Image attachment gem/plugin for Ruby on Rails
+
+HasImage[http://github.com/norman/has_image] was created as a smaller,
+simpler, lighter alternative to
+attachment_fu[http://github.com/technoweenie/attachment_fu] for applications
+that need to handle uploaded images.
+
+It creates only one database record per image, requires only one column in
+your model, and creates great-looking fixed-dimension thumbnails by using
+{ImageMagick's}[http://www.imagemagick.org/]
+resize[http://www.imagemagick.org/script/command-line-options.php#resize],
+crop[http://www.imagemagick.org/script/command-line-options.php#crop] and
+gravity[http://www.imagemagick.org/script/command-line-options.php#gravity]
+functions.
+
+Some typical use cases are: websites that want to create photo galleries with
+fixed-dimension thumbnails, or that want to store user profile pictures
+without creating a separate model for the images.
+
+It supports only filesystem storage, and uses only MiniMagick[http://github.com/probablycorey/mini_magick] to process
+images. However, the codebase is very small, simple, readable, and hackable.
+So it should be easy to modify or enhance its functionality with different
+storage or processor options.
+
+== Another image attachment library? Why?
+
+<em>The three chief virtues of a programmer are: Laziness, Impatience and Hubris.</em> - {Larry Wall}[http://en.wikipedia.org/wiki/Larry_Wall]
+
+Attachment_fu is too large and general for some of the places I want to use
+images. I sometimes found myself writing more code to hack attachment_fu than
+it took to create this gem. In fact, most of the code here has been plucked
+from my various projects that use attachment_fu.
+
+The other image attachment libraries I found fell short of my needs for
+various other reasons, so I decided to roll my own.
+
+== Examples
+
+Point-and-drool use case. It's probably not what you want, but it may be
+useful for bootstrapping.
+
+  class Member < ActiveRecord::Base
+    has_image
+  end
+
+Single image, no thumbnails, with some size limits:
+
+  class Picture < ActiveRecord::Base
+    has_image :resize_to => "200x200",
+      :max_size => 3.megabytes,
+      :min_size => 4.kilobytes
+  end
+
+Image with some thumbnails:
+
+  class Photo < ActiveRecord::Base
+    has_image :resize_to => "640x480",
+      :thumbnails => {
+        :square => "200x200",
+        :medium => "320x240"
+      },
+      :max_size => 3.megabytes,
+      :min_size => 4.kilobytes
+  end
+  
+It also provides a view helper to make displaying the images extremely simple:
+
+  <%= image_tag_for(@photo, :thumb => :square) %>
+
+== Getting it
+
+Has image can be installed as a gem, or as a Rails plugin. Gem installation
+is easiest, and recommended:
+
+  gem install norman-has_image --source http://gems.github.com
+
+and add 
+
+  require 'has_image'
+
+to your environment.rb file.
+
+Alternatively, you can install it as a Rails plugin:
+
+  ./script plugin install git://github.com/norman/has_image.git
+  
+Rails versions before 2.1 do not support plugin installation using Git, so if
+you're on 2.0 (or earlier), then please install the gem rather than the
+plugin.
+  
+Then, make sure the model has a column named "has_image_file."
+
+{Git repository}[http://github.com/norman/has_image]: 
+
+  git://github.com/norman/has_image.git
+
+
+== Hacking it
+
+Don't like the way it makes images? Want to pipe the images through some
+{crazy fast seam carving library written in
+OCaml}[http://eigenclass.org/hiki/seam-carving-in-ocaml], or watermark them
+with your corporate logo? Happiness is just a monkey-patch[http://en.wikipedia.org/wiki/Monkey_patch] away:
+
+  module HasImage
+    class Processor
+      def resize_image(size)
+        # your new-and-improved thumbnailer code goes here.
+      end
+    end
+  end
+
+HasImage[http://github.com/norman/has_image] follows a philosophy of "{skinny
+model, fat plugin}[http://weblog.jamisbuck.org/2006/10/18/skinny-controller-fat-model]."
+This means that it tries to pollute your ActiveRecord model with as little
+functionality as possible, so that in a sense, the model is acts like a
+"controller" and the plugin like a "model" as regards the image handling
+functionality. This makes it easier to test, hack, and reuse, because the
+storage and processing functionality is largely independent of your model, and
+of Rails.
+
+My goal for HasImage[http://github.com/norman/has_image] is to keep it very
+small. If you need <strong>a lot</strong> of functionality that's not here, instead of patching
+this code, you will likely be better off using
+attachment_fu[http://github.com/technoweenie/attachment_fu], which is much
+more powerful, but also more complex.
+
+== Bugs
+
+Please report them on Lighthouse[http://randomba.lighthouseapp.com/projects/14674-has_image].
+
+At the time of writing (July 2008),
+HasImage[http://github.com/norman/has_image] is in its infancy. Your patches,
+bug reports and withering criticism are more than welcome.
+
+
+
+Copyright (c) 2008 {Norman Clarke}[mailto:norman@randomba.org], released under
+the MIT license

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the non-Rails part of has_image.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Test the Rails part of has_image.'
+Rake::TestTask.new(:test_rails) do |t|
+  t.libs << 'lib'
+  t.libs << 'test_rails'
+  t.pattern = 'test_rails/**/*_test.rb'
+  t.verbose = true
+end
+
+desc "Run rcov"
+task :rcov do
+  rm_f "coverage"
+  rm_f "coverage.data"
+  if PLATFORM =~ /darwin/
+    exclude = '--exclude "gems"'
+  else
+    exclude = '--exclude "rubygems"'
+  end
+  rcov = "rcov --rails -Ilib:test --sort coverage --text-report #{exclude} --no-validator-links"
+  cmd = "#{rcov} #{Dir["test/**/*.rb"].join(" ")}"
+  sh cmd
+end
+
+desc 'Generate documentation for has_image.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HasImage'
+  rdoc.options << '--line-numbers' << '--inline-source' << '-c UTF-8'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('FAQ')
+  rdoc.rdoc_files.include('CHANGELOG')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1 @@
+require 'has_image'

data/lib/has_image/processor.rb

@@ -0,0 +1,76 @@
+require 'mini_magick'
+
+module HasImage
+  
+  # Image processing functionality for the HasImage gem.
+  class Processor
+    
+    attr_accessor :options
+    
+    class << self
+      # 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.
+      def valid?(arg)
+        arg.close if arg.respond_to?(:close) && !arg.closed?
+        silence_stderr do
+          `identify #{arg.respond_to?(:path) ? arg.path : arg.to_s}`
+          $? == 0
+        end
+      end    
+    end
+
+    # The constuctor should be invoked with the options set by has_image.
+    def initialize(options) # :nodoc:
+      @options = options
+    end
+    
+    # Create the resized image, and transforms it to the desired output
+    # format if necessary. The size should be a valid ImageMagick {geometry
+    # string}[http://www.imagemagick.org/script/command-line-options.php#resize].
+    def resize(file, size)
+      silence_stderr do
+        path = file.respond_to?(:path) ? file.path : file
+        file.close if file.respond_to?(:close) && !file.closed?
+        @image = MiniMagick::Image.from_file(path)
+        convert_image
+        resize_image(size)   
+        return @image
+      end
+    rescue MiniMagick::MiniMagickError
+      raise ProcessorError.new("That doesn't look like an image file.")
+    end
+    
+    # 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:
+    # * auto-orient[http://www.imagemagick.org/script/command-line-options.php#auto-orient]
+    # * strip[http://www.imagemagick.org/script/command-line-options.php#strip]
+    # * resize[http://www.imagemagick.org/script/command-line-options.php#resize]
+    # * 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]
+    def resize_image(size)
+      @image.combine_options do |commands|
+        commands.send("auto-orient".to_sym)
+        commands.strip
+        commands.resize "#{size}^"
+        commands.gravity "center"
+        commands.extent size
+        commands.quality options[:output_quality]
+      end
+    end
+
+    private
+    
+    # This was placed in a separate method largely to facilitate debugging
+    # and profiling.
+    def convert_image
+      return if @image[:format] == options[:convert_to]
+      @image.format(options[:convert_to])
+    end
+    
+  end
+
+end

data/lib/has_image/storage.rb

@@ -0,0 +1,167 @@
+require 'active_support'
+require 'stringio'
+require 'fileutils'
+require 'zlib'
+
+module HasImage  
+  
+  # Filesystem storage for the HasImage gem. The methods that HasImage inserts
+  # into ActiveRecord models only depend on the public methods in this class, so
+  # it should be reasonably straightforward to implement a different storage
+  # mechanism for Amazon AWS, Photobucket, DBFile, SFTP, or whatever you want.  
+  class Storage
+    
+    attr_accessor :image_data, :options, :temp_file
+
+    class << self
+      
+      # Stolen from {Jamis Buck}[http://www.37signals.com/svn/archives2/id_partitioning.php].
+      def partitioned_path(id, *args)
+        ("%08d" % id).scan(/..../) + args
+      end
+
+      # Generates a 4-6 character random file name to use for the image and its
+      # thumbnails. This is done to avoid having files with unfortunate names.
+      # On one of my sites users frequently upload images with Arabic names, and
+      # they end up being hard to manipulate on the command line. This also
+      # helps prevent a possibly undesirable sitation where the uploaded images
+      # have offensive names.
+      def random_file_name
+        Zlib.crc32(Time.now.to_s + rand(10e10).to_s).to_s(36)
+      end
+          
+    end
+
+    # The constuctor should be invoked with the options set by has_image.
+    def initialize(options) # :nodoc:
+      @options = options
+    end
+
+    # The image data can be anything that inherits from IO. If you pass in an
+    # instance of Tempfile, it will be used directly without being copied to
+    # a new temp file.
+    def image_data=(image_data)
+      raise StorageError.new if image_data.blank?
+      if image_data.is_a?(Tempfile)
+        @temp_file = image_data
+      else
+        image_data.rewind
+        @temp_file = Tempfile.new 'has_image_data_%s' % Storage.random_file_name
+        @temp_file.write(image_data.read)        
+      end
+    end
+
+    # Is uploaded file smaller than the allowed minimum?
+    def image_too_small?
+      @temp_file.open if @temp_file.closed?
+      @temp_file.size < options[:min_size]
+    end
+    
+    # Is uploaded file larger than the allowed maximum?
+    def image_too_big?
+      @temp_file.open if @temp_file.closed?
+      @temp_file.size > options[:max_size]
+    end
+    
+    # A tip of the hat to attachment_fu.
+    alias uploaded_data= image_data=
+    
+    # A tip of the hat to attachment_fu.
+    alias uploaded_data image_data
+    
+    # Invokes the processor to resize the image(s) and the installs them to
+    # the appropriate directory.
+    def install_images(id)
+      random_name = Storage.random_file_name
+      install_main_image(id, random_name)
+      install_thumbnails(id, random_name) if !options[:thumbnails].empty?
+      return random_name
+    ensure  
+      @temp_file.close! if !@temp_file.closed?
+      @temp_file = nil
+    end
+    
+    # Gets the "web" path for an image. For example:
+    #
+    #   /photos/0000/0001/3er0zs.jpg
+    def public_path_for(object, thumbnail = nil)
+      filesystem_path_for(object, thumbnail).gsub(options[:base_path], '')
+    end
+    
+    # Deletes the images and directory that contains them.
+    def remove_images(id)
+      FileUtils.rm_r path_for(id)
+    end
+
+    # Is the uploaded file within the min and max allowed sizes?
+    def valid?
+      !(image_too_small? || image_too_big?)
+    end
+
+    protected
+
+    # Gets the extension to append to the image. Transforms "jpeg" to "jpg."
+    def extension
+      options[:convert_to].to_s.downcase.gsub("jpeg", "jpg")
+    end
+    
+    private
+    
+    # File name, plus thumbnail suffix, plus extension. For example:
+    #
+    #   file_name_for("abc123", :thumb)
+    #
+    # gives you:
+    #
+    #   "abc123_thumb.jpg"
+    #   
+    #
+    def file_name_for(*args)
+      "%s.%s" % [args.compact.join("_"), extension]
+    end
+
+    # Gets the full local filesystem path for an image. For example:
+    #
+    #   /var/sites/example.com/production/public/photos/0000/0001/3er0zs.jpg
+    def filesystem_path_for(object, thumbnail = nil)
+      File.join(path_for(object.id), file_name_for(object.has_image_file, thumbnail))
+    end
+    
+    # Write the main image to the install directory - probably somewhere under
+    # RAILS_ROOT/public.
+    def install_main_image(id, name)
+      FileUtils.mkdir_p path_for(id)
+      main = processor.resize(@temp_file, @options[:resize_to])
+      main.write(File.join(path_for(id), file_name_for(name)))
+      main.tempfile.close!
+    end
+    
+    # Write the thumbnails to the install directory - probably somewhere under
+    # RAILS_ROOT/public.
+    def install_thumbnails(id, name)
+      FileUtils.mkdir_p path_for(id)
+      path = File.join(path_for(id), file_name_for(name))
+      options[:thumbnails].each do |thumb_name, size|
+        thumb = processor.resize(path, size)
+        thumb.write(File.join(path_for(id), file_name_for(name, thumb_name)))
+        thumb.tempfile.close!
+      end
+    end
+    
+    # Get the full path for the id. For example:
+    #
+    #  /var/sites/example.org/production/public/photos/0000/0001
+    def path_for(id)
+      File.join(options[:base_path], options[:path_prefix], Storage.partitioned_path(id))
+    end
+    
+    # Instantiates the processor using the options set in my contructor (if
+    # not already instantiated), stores it in an instance variable, and
+    # returns it.
+    def processor
+      @processor ||= Processor.new(options)
+    end
+    
+  end
+  
+end

data/lib/has_image/view_helpers.rb

@@ -0,0 +1,39 @@
+module HasImage
+  
+  # Some helpers to make working with HasImage models in views a little
+  # easier.
+  module ViewHelpers
+  
+    # Wraps the image_tag helper from Rails. Instead of passing the path to
+    # an image, you can pass any object that uses HasImage. The options can
+    # include the name of one of your thumbnails, for example:
+    #
+    #  image_tag_for(@photo)
+    #  image_tag_for(@photo, :thumb => :square)
+    #
+    # If your object uses fixed dimensions (i.e., "200x200" as opposed to
+    # "200x200>"), then the height and width properties will automatically be
+    # added to the resulting img tag unless you explicitly specify the size in
+    # the options.
+    #
+    # All arguments other than :thumb will simply be passed along to the Rails
+    # image_tag helper without modification.
+    #
+    # See also: HasImage::ModelInstanceMethods#public_path
+    def image_tag_for(object, options = {})
+      thumb = options.delete(:thumb)
+      if !options[:size]
+        if thumb 
+          size = object.class.thumbnails[thumb.to_sym]
+          options[:size] = size if size =~ /\A[\d]*x[\d]*\Z/
+        else
+          size = object.class.resize_to
+          options[:size] = size if size =~ /\A[\d]*x[\d]*\Z/
+        end
+      end
+  	  image_tag(object.public_path(thumb), options)
+    end
+  
+  end
+
+end

data/lib/has_image.rb

@@ -0,0 +1,242 @@
+require 'has_image/processor'
+require 'has_image/storage'
+require 'has_image/view_helpers'
+
+# = HasImage
+#
+# HasImage allows Ruby on Rails applications to have attached images. It is very
+# small and lightweight: it only requires one column ("has_image_file") in your
+# model to store the uploaded image's file name.
+# 
+# HasImage is, by design, very simplistic: It only supports using a filesystem
+# for storage, and only supports
+# MiniMagick[http://github.com/probablycorey/mini_magick] as an image processor.
+# However, its code is very small, clean and hackable, so adding support for
+# other backends or processors should be fairly easy.
+# 
+# HasImage works best for sites that want to show image galleries with
+# fixed-size thumbnails. It uses ImageMagick's
+# crop[http://www.imagemagick.org/script/command-line-options.php#crop] and
+# {center
+# gravity}[http://www.imagemagick.org/script/command-line-options.php#gravity]
+# functions to produce thumbnails that generally look acceptable, unless the
+# image is a panorama, or the subject matter is close to one of the margins,
+# etc. For most sites where people upload pictures of themselves or their pets
+# the generated thumbnails will look good almost all the time.
+# 
+# It's pretty easy to change the image processing / resizing code; you can just
+# override HasImage::Processor#resize_image to do what you wish:
+# 
+#   module HasImage::
+#     class Processor
+#       def resize_image(size)
+#         @image.combine_options do |commands|
+#           commands.my_custom_resizing_goes_here
+#         end
+#       end
+#     end
+#   end
+# 	
+# Compared to attachment_fu, HasImage has advantages and disadvantages.
+# 
+# = Advantages:
+# 
+# * Simpler, smaller, more easily hackable codebase - and specialized for
+#   images only.
+# * Installable via Ruby Gems. This makes version dependencies easy when using
+#   Rails 2.1.
+# * Creates only one database record per image.
+# * Has built-in facilities for making distortion-free, fixed-size thumbnails.
+# * Doesn't regenerate the thumbnails every time you save your model. This means
+#   you can easily use it, for example, inside a Member model to store member
+#   avatars.
+# 
+# = Disadvantages:
+# 
+# * Doesn't save image dimensions. However, if you're using fixed-sized images,
+#   this is not a problem because you can just read the size from MyModel.thumbnails[:my_size]
+# * No support for AWS or DBFile storage, only filesystem.
+# * Only supports MiniMagick[http://github.com/probablycorey/mini_magick/tree] as an image processor, no RMagick, GD, CoreImage,
+#   etc.
+# * No support for anything other than image attachments.
+# * Not as popular as attachment_fu, which means fewer bug reports, and
+#   probably more bugs. Use at your own risk!
+module HasImage
+
+  class ProcessorError < StandardError ; end
+  class StorageError < StandardError ; end  
+  class FileTooBigError < StorageError ; end  
+  class FileTooSmallError < StorageError ; end  
+  
+  class << self
+    
+    def included(base) # :nodoc:
+      base.extend(ClassMethods)
+    end
+
+    # Enables has_image functionality. You probably don't need to ever invoke
+    # this.
+    def enable # :nodoc:
+      return if ActiveRecord::Base.respond_to? :has_image
+      ActiveRecord::Base.send(:include, HasImage)
+      return if ActionView::Base.respond_to? :image_tag_for
+      ActionView::Base.send(:include, ViewHelpers)
+    end
+
+    # If you're invoking this method, you need to pass in the class for which
+    # you want to get default options; this is used to determine the path where
+    # the images will be stored in the file system. Take a look at
+    # HasImage::ClassMethods#has_image to see examples of how to set the options
+    # in your model.
+    #
+    # This method is called by your model when you call has_image. It's
+    # placed here rather than in the model's class methods to make it easier
+    # to access for testing. Unless you're working on the code, it's unlikely
+    # you'll ever need to invoke this method.
+    #
+    # * :resize_to => "200x200",
+    # * :thumbnails => {},
+    # * :max_size => 12.megabytes,
+    # * :min_size => 4.kilobytes,
+    # * :path_prefix => klass.to_s.tableize,
+    # * :base_path => File.join(RAILS_ROOT, 'public'),
+    # * :convert_to => "JPEG",
+    # * :output_quality => "85",
+    # * :invalid_image_message => "Can't process the image.",
+    # * :image_too_small_message => "The image is too small.",
+    # * :image_too_big_message => "The image is too big.",
+    def default_options_for(klass)
+      {
+        :resize_to => "200x200",
+        :thumbnails => {},
+        :max_size => 12.megabytes,
+        :min_size => 4.kilobytes,
+        :path_prefix => klass.to_s.tableize,
+        :base_path => File.join(RAILS_ROOT, 'public'),
+        :convert_to => "JPEG",
+        :output_quality => "85",
+        :invalid_image_message => "Can't process the image.",
+        :image_too_small_message => "The image is too small.",
+        :image_too_big_message => "The image is too big."
+      }
+    end
+    
+  end
+
+  module ClassMethods
+    # 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:
+    # *  <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>: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. You should probably leave this alone, except for tests.
+    # *  <tt>:path_prefix</tt> - Where to install the images, relative to basepath. You should probably leave this alone.
+    # *  <tt>:convert_to</tt> - An ImageMagick format to convert images to. Recommended formats: JPEG, PNG, GIF.
+    # *  <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.
+    #
+    # 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."
+    def has_image(options = {})
+      options.assert_valid_keys(:resize_to, :thumbnails, :max_size, :min_size,
+        :path_prefix, :base_path, :convert_to, :output_quality,
+        :invalid_image_message, :image_too_big_message, :image_too_small_message)
+      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
+    
+    # Sets the uploaded image data. Image data can be an instance of Tempfile,
+    # or an instance of any class than inherits from IO.
+    def image_data=(image_data)
+      return if image_data.blank?
+      storage.image_data = image_data
+    end
+    
+    # Is the image data a file that ImageMagick can process, and is it within
+    # the allowed minimum and maximum sizes?
+    def image_data_valid?
+      return if !storage.temp_file
+      if storage.image_too_big?
+        errors.add_to_base(self.class.has_image_options[:image_too_big_message])
+      elsif storage.image_too_small?
+        errors.add_to_base(self.class.has_image_options[:image_too_small_message])
+      elsif !HasImage::Processor.valid?(storage.temp_file)
+        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.
+    def public_path(thumbnail = nil)
+      storage.public_path_for(self, thumbnail)
+    end
+    
+    # Deletes the image from the storage.
+    def remove_images
+      return if has_image_file.blank?
+      storage.remove_images(self.id)
+    rescue Errno::ENOENT
+      logger.warn("Could not delete files for #{self.class.to_s} #{to_param}") 
+    end
+    
+    # Creates new images and removes the old ones when image_data has been
+    # set.
+    def update_images
+      return if storage.temp_file.blank?
+      storage.remove_images(self.id)
+      update_attribute(:has_image_file, storage.install_images(self.id))      
+    end
+
+    # Processes and installs the image and its thumbnails.
+    def install_images
+      return if !storage.temp_file
+      update_attribute(:has_image_file, storage.install_images(self.id))
+    end
+    
+    # Gets an instance of the underlying storage functionality. See
+    # HasImage::Storage.
+    def storage
+      @storage ||= HasImage::Storage.new(has_image_options)
+    end
+    
+  end
+
+  module ModelClassMethods
+
+    # Get the hash of thumbnails set by the options specified when invoking
+    # HasImage::ClassMethods#has_image.
+    def thumbnails
+      has_image_options[:thumbnails]
+    end
+
+  end
+
+end
+
+if defined?(Rails) and defined?(ActiveRecord) and defined?(ActionController)
+  HasImage.enable
+end

data/test/processor_test.rb

@@ -0,0 +1,49 @@
+require 'test_helper.rb'
+
+class StorageTest < Test::Unit::TestCase
+  
+  def teardown
+    @temp_file.close if @temp_file
+    FileUtils.rm_rf(File.dirname(__FILE__) + '/../tmp')
+  end
+  
+  def temp_file(fixture)
+    @temp_file = Tempfile.new('test')
+    @temp_file.write(File.new(File.dirname(__FILE__) + "/../test_rails/fixtures/#{fixture}", "r").read)
+    return @temp_file
+  end
+  
+  def test_detect_valid_image
+    assert HasImage::Processor.valid?(File.dirname(__FILE__) + "/../test_rails/fixtures/image.jpg")
+  end
+
+  def test_detect_valid_image_from_tmp_file
+    assert HasImage::Processor.valid?(temp_file("image.jpg"))
+  end
+
+  def test_detect_invalid_image
+    assert !HasImage::Processor.valid?(File.dirname(__FILE__) + "/../test_rails/fixtures/bad_image.jpg")
+  end
+
+  def test_detect_invalid_image_from_tmp_file
+    assert !HasImage::Processor.valid?(temp_file("bad_image.jpg"))
+  end
+  
+  def test_resize
+    @processor = HasImage::Processor.new({:convert_to => "JPEG", :output_quality => "85"})
+    assert @processor.resize(temp_file("image.jpg"), "100x100")
+  end
+
+  def test_resize_and_convert
+    @processor = HasImage::Processor.new({:convert_to => "JPEG", :output_quality => "85"})
+    assert @processor.resize(temp_file("image.png"), "100x100")
+  end
+
+  def test_resize_should_fail_with_bad_image
+    @processor = HasImage::Processor.new({:convert_to => "JPEG", :output_quality => "85"})
+    assert_raises HasImage::ProcessorError do
+      @processor.resize(temp_file("bad_image.jpg"), "100x100")
+    end
+  end
+
+end

data/test/storage_test.rb

@@ -0,0 +1,98 @@
+require 'test_helper.rb'
+
+class StorageTest < Test::Unit::TestCase
+  
+  def setup
+  end
+  
+  def teardown
+    FileUtils.rm_rf(File.dirname(__FILE__) + '/../tmp')
+    @temp_file.close! if @temp_file && !@temp_file.closed?
+  end
+  
+  def default_options
+    HasImage.default_options_for("tests").merge(
+      :base_path => File.join(File.dirname(__FILE__), '..', 'tmp')
+    )
+  end
+  
+  def test_partitioned_path
+    assert_equal(["0001", "2345"], HasImage::Storage.partitioned_path("12345"))
+  end
+  
+  def test_random_file_name
+    assert_match(/[a-z0-9]{4,6}/i, HasImage::Storage.random_file_name)
+  end
+  
+  def test_path_for
+    @storage = HasImage::Storage.new(default_options)
+    assert_match(/\/tmp\/tests\/0000\/0001/, @storage.send(:path_for, 1))
+  end
+  
+  def test_public_path_for
+    @storage = HasImage::Storage.new(default_options)
+    pic = stub(:has_image_file => "mypic", :id => 1)
+    assert_equal "/tests/0000/0001/mypic_square.jpg", @storage.public_path_for(pic, :square)
+  end
+  
+  def test_filename_for
+    @storage = HasImage::Storage.new(default_options)
+    assert_equal "test.jpg", @storage.send(:file_name_for, "test")
+  end
+
+  def test_set_data_from_file
+    @storage = HasImage::Storage.new(default_options)
+    @file = File.new(File.dirname(__FILE__) + "/../test_rails/fixtures/image.jpg", "r")
+    @storage.image_data = @file
+    assert @storage.temp_file.size > 0
+    assert_equal Zlib.crc32(@file.read), Zlib.crc32(@storage.temp_file.read)
+  end
+  
+  def test_set_data_from_tempfile
+    @storage = HasImage::Storage.new(default_options)
+    @storage.image_data = temp_file("image.jpg")
+    assert @storage.temp_file.size > 0
+    assert_equal Zlib.crc32(@storage.temp_file.read), Zlib.crc32(@temp_file.read)
+  end
+  
+  def test_install_and_remove_images
+    @storage = HasImage::Storage.new(default_options)
+    @storage.image_data = temp_file("image.jpg")
+    assert @storage.install_images(1)
+    assert @storage.remove_images(1)    
+  end
+
+  def test_image_not_too_small
+    @storage = HasImage::Storage.new(default_options.merge(:min_size => 1.kilobyte))
+    @storage.image_data = temp_file("image.jpg")
+    assert !@storage.image_too_small?
+  end
+  
+  def test_image_too_small
+    @storage = HasImage::Storage.new(default_options.merge(:min_size => 1.gigabyte))
+    @storage.image_data = temp_file("image.jpg")
+    assert @storage.image_too_small?
+  end
+  
+  def test_image_too_big
+    @storage = HasImage::Storage.new(default_options.merge(:max_size => 1.kilobyte))
+    @storage.image_data = temp_file("image.jpg")    
+    assert @storage.image_too_big?
+  end
+
+  def test_image_not_too_big
+    @storage = HasImage::Storage.new(default_options.merge(:max_size => 1.gigabyte))
+    @storage.image_data = temp_file("image.jpg")    
+    assert !@storage.image_too_big?
+  end
+  
+  private
+  
+  def temp_file(fixture)
+    file = File.new(File.dirname(__FILE__) + "/../test_rails/fixtures/#{fixture}", "r")
+    @temp_file = Tempfile.new("test")
+    @temp_file.write(file.read)
+    return @temp_file
+  end
+  
+end

data/test_rails/database.yml

@@ -0,0 +1,3 @@
+sqlite3:
+  adapter: sqlite3
+  database: ":memory:"

data/test_rails/pic.rb

@@ -0,0 +1,3 @@
+class Pic < ActiveRecord::Base
+  has_image
+end

data/test_rails/pic_test.rb

@@ -0,0 +1,79 @@
+require 'test_helper'
+
+class PicTest < Test::Unit::TestCase
+  
+  def setup
+    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}"
+  end
+
+  def test_should_be_too_big
+    Pic.has_image_options[:max_size] = 1.kilobyte
+    @pic = Pic.new(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
+    assert !@pic.valid?
+  end
+
+  def test_should_be_too_small
+    Pic.has_image_options[:min_size] = 1.gigabyte
+    @pic = Pic.new(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
+    assert !@pic.valid?
+  end
+
+  def test_invalid_image_detected
+    @pic = Pic.new(:image_data => fixture_file_upload("/bad_image.jpg", "image/jpeg"))
+    assert !@pic.valid?
+  end
+
+  def test_create
+    @pic = Pic.new(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
+    assert @pic.save!
+  end
+
+  def test_update
+    @pic = Pic.new(:image_data => fixture_file_upload("/image.jpg", "image/jpeg"))
+    @pic.save!
+    @pic.image_data = fixture_file_upload("/image.png", "image/png")
+    assert @pic.save!
+  end
+
+  def test_create_model_without_setting_image_data
+    assert Pic.new.save!
+  end
+
+  def test_destroy_model_without_no_images
+    @pic = Pic.new
+    @pic.save!
+    assert @pic.destroy
+  end
+
+  def test_destroy_model_with_images_already_deleted_from_filesystem
+    @pic = Pic.new
+    @pic.save!
+    @pic.update_attribute(:has_image_file, "test")
+    assert @pic.destroy
+  end
+
+  def test_create_with_png
+    Pic.has_image_options[:min_size] = 1
+    @pic = Pic.new(:image_data => fixture_file_upload("/image.png", "image/png"))
+    assert @pic.save!
+  end
+
+  def test_multiple_calls_to_valid_doesnt_blow_away_temp_image
+    Pic.has_image_options[:min_size] = 1
+    @pic = Pic.new(:image_data => fixture_file_upload("/image.png", "image/png"))
+    @pic.valid?
+    assert @pic.valid?
+  end
+
+end
+

data/test_rails/schema.rb

@@ -0,0 +1,9 @@
+ActiveRecord::Schema.define(:version => 1) do
+
+  create_table "pics", :force => true do |t|
+    t.string  :has_image_file
+    t.datetime :created_at
+    t.datetime :updated_at
+  end
+
+end

data/test_rails/test_helper.rb

@@ -0,0 +1,54 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+ENV['RAILS_ENV'] = 'test'
+
+require 'test/unit'
+require File.expand_path(File.join(File.dirname(__FILE__), '/../../../../config/environment.rb'))
+require 'active_record/fixtures'
+require 'action_controller/test_process'
+
+config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
+
+db_adapter = ENV['DB']
+
+# no db passed, try one of these fine config-free DBs before bombing.
+db_adapter ||= 
+  begin
+    require 'rubygems'
+    require 'sqlite3'
+    'sqlite3'
+  rescue MissingSourceFile
+    begin
+      require 'sqlite'
+      'sqlite'
+    rescue MissingSourceFile
+    end
+  end
+
+if db_adapter.nil?
+  raise "No DB Adapter selected.  Pass the DB= option to pick one, or install Sqlite3 or Sqlite."
+end
+
+ActiveRecord::Base.establish_connection(config[db_adapter])
+
+load(File.dirname(__FILE__) + "/schema.rb")
+
+Test::Unit::TestCase.fixture_path = File.dirname(__FILE__) + "/fixtures"
+$LOAD_PATH.unshift(Test::Unit::TestCase.fixture_path)
+
+class Test::Unit::TestCase #:nodoc:
+  include ActionController::TestProcess
+  def create_fixtures(*table_names)
+    if block_given?
+      Fixtures.create_fixtures(Test::Unit::TestCase.fixture_path, table_names) { yield }
+    else
+      Fixtures.create_fixtures(Test::Unit::TestCase.fixture_path, table_names)
+    end
+  end
+
+  self.use_transactional_fixtures = true
+  self.use_instantiated_fixtures  = false
+  
+end
+require 'pic'

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: has_image
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Norman Clarke
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-07-23 00:00:00 -03:00
+default_executable: 
+dependencies: []
+
+description: HasImage is a Ruby on Rails gem/plugin that allows you to attach images to ActiveRecord models.
+email: norman@randomba.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- CHANGELOG
+- FAQ
+files: 
+- CHANGELOG
+- FAQ
+- MIT-LICENSE
+- README
+- init.rb
+- lib/has_image.rb
+- lib/has_image/processor.rb
+- lib/has_image/storage.rb
+- lib/has_image/view_helpers.rb
+- Rakefile
+has_rdoc: true
+homepage: http://randomba.org
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+- --inline-source
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Lets you attach images with thumbnails to active record models.
+test_files: 
+- test_rails/database.yml
+- 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/schema.rb
+- test_rails/test_helper.rb
+- test/processor_test.rb
+- test/storage_test.rb