norman-has_image 0.2.3 → 0.3.0

data/CHANGELOG

@@ -1,3 +1,15 @@
+2008-10-22 Gerrit Keiser and Tricycle Developments
+  * Added option to not delete images on destroy
+  * Made thumbnail name separator configurable
+  * Added height/width methods to storage
+  * Allowed regenerating only one thumbnail size
+  * Made has_image column configurable
+  * Added some compatibility with attachment_fu
+  * General refactorings and overall code improvement
+
+2008-10-22 Norman Clarke <norman@randomba.org>
+  * Documentation improvements and minor code cleanups.
+
 2008-10-09 Dima Sabanin <sdmitry@gmail.com>
   * Fixed display of images with special symbols in the name,
     like '2777-nipple-+-apple-napple.jpg'. + is reserved by HTTP.

data/README.textile

@@ -0,0 +1,193 @@
+h1. "HasImage":http://github.com/norman/has_image
+
+Image attachment gem/plugin for Ruby on Rails
+
+HasImage allows Ruby on Rails applications to have attached images. It is very
+small and lightweight: it only requires one column in your model to store the
+uploaded image's file name.
+
+HasImage 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 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.
+
+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 creates only one database record per image, and 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 the generated
+thumbnails will look good almost all the time.
+
+h2. Another image attachment library? Why?
+
+<blockquote>
+  The three chief virtues of a programmer are: Laziness, Impatience and Hubris. - "Larry Wall":http://en.wikipedia.org/wiki/Larry_Wall
+</blockquote>
+
+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.
+
+h2. HasImage vs. attachment_fu
+
+h3. 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.
+
+h3. Disadvantages
+
+  * Doesn't save image dimensions in the database. However, if you're using
+    fixed-sized images, you can 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, but then again if you use it you'll be cooler (until HasImage becomes popular).
+
+h2. 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) # show the full-sized image %>
+  <%= image_tag_for(@photo, :thumb => :square) # show the square thumbnail %>
+
+The image_tag_for helper calls Rails' image_tag, so you can pass in all the 
+regular options to set the alt property, CSS class, etc:
+  
+  <%= image_tag_for(@photo, :alt => "my cool picture", :class => "photo") %>
+
+Setting up forms for HasImage is simple, too:
+
+<pre>
+  <% form_for(@photo, :html => {:multipart => true}) do |f| %>
+    <p>
+      <%= f.label :image_data %>
+      <%= f.file_field :image_data %>
+    </p>
+    <p>
+      <%= f.submit %>
+    </p>
+  <% end %>
+</pre>
+
+h2. Getting it
+
+Has image can be installed as a gem, or as a Rails plugin. Gem installation
+is easiest, and recommended:
+
+  gem install has_image
+
+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
+
+h2. 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 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 is to keep it very small. If you need *a lot* of
+functionality that's not here, instead of patching this code, you will likely
+be better off using attachment_fu, which is more powerful, but also more
+complex.
+
+h2. Bugs
+
+Please report them on "Lighthouse":http://randomba.lighthouseapp.com/projects/14674-has_image.
+
+Copyright (c) 2008 "Norman Clarke":mailto:norman@randomba.org, released under
+the MIT license
+
+h2. Is anyone using this thing?
+
+HasImage powers "FotoBlog":http://fotoblog.ciudad.com.ar, one of the largest
+Rails sites in Argentina. If you're using it in your project let me know and
+I'll add your link here.
+
+h2. Acknowledgements
+
+I'd like to thank the following contributors:
+
+* "Adrian Mugnolo":http://github.com/xymbol
+* "Gerrit Keiser":http://github.com/gerrit
+* the folks from "Tricycle Developments":http://github.com/tricycle
+* "Dima Sabanin":http://github.com/railsmonk

data/Rakefile

@@ -5,6 +5,8 @@ require 'rake/rdoctask'
 desc 'Default: run unit tests.'
 task :default => :test
 
+task :all_tests  => [:test, :test_rails]
+
 desc 'Test the non-Rails part of has_image.'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
@@ -40,7 +42,7 @@ 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('README.textile')
   rdoc.rdoc_files.include('FAQ')
   rdoc.rdoc_files.include('CHANGELOG')
   rdoc.rdoc_files.include('lib/**/*.rb')

data/init.rb

@@ -1 +1 @@
-require 'has_image'
+require 'has_image'

data/lib/has_image.rb

@@ -4,63 +4,73 @@ 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
+# HasImage allows you to very easily attach images to a Rails model. For some
+# more basic info on what it does, please see its {project
+# page}[http://github.com/norman/has_image] on GitHub.
+#
+# Install HasImage by using Ruby Gems:
+#
+#  sudo gem install has_image
+#
+# To use HasImage in your project, you must add a varchar column to your
+# model. By default, this column should be named "has_image_file," though you
+# may easily change this. For option defaults, see
+# HasImage#default_options_for and ClassMethods#has_image.
+#
+# == Basic Examples
+##
+# Uses all default options. This works, but is likely not what you need.
+#
+#  class Photo < ActiveRecord::Base
+#    has_image
+#  end
+#
+# Resize the uploaded image to 800x800 and create a 150x150 thumbnail.
+#
+#   has_image :resize_to "800x800", :thumbnails => {:square => "150x150"}
+#
+# Resize the image and set a max file size to 4 megabytes.
+#
+#   has_image :resize_to "100x150", :max_size => 4.megabytes
+#
+# == 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
-# 	
-# 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!
+#
+# 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
+#
 module HasImage
 
   class ProcessorError < StandardError ; end
@@ -68,9 +78,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
@@ -97,23 +107,29 @@ module HasImage
     #
     # * :resize_to => "200x200",
     # * :thumbnails => {},
+    # * :auto_generate_thumbnails => true,
+    # * :delete => true,
     # * :max_size => 12.megabytes,
     # * :min_size => 4.kilobytes,
-    # * :path_prefix => klass.to_s.tableize,
+    # * :path_prefix => klass.table_name,
     # * :base_path => File.join(RAILS_ROOT, 'public'),
+    # * :column => :has_image_file,
     # * :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.",
+    # * :image_too_big_message => "The image is too big."
     def default_options_for(klass)
       {
         :resize_to => "200x200",
         :thumbnails => {},
+        :auto_generate_thumbnails => true,
+        :delete => true,
         :max_size => 12.megabytes,
         :min_size => 4.kilobytes,
-        :path_prefix => klass.to_s.tableize,
+        :path_prefix => klass.table_name,
         :base_path => File.join(RAILS_ROOT, 'public'),
+        :column => :has_image_file,
         :convert_to => "JPEG",
         :output_quality => "85",
         :invalid_image_message => "Can't process the image.",
@@ -121,68 +137,67 @@ module HasImage
         :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:
+
+    # === 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. 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>: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.
-    #
-    # 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.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?
-      !has_image_file.blank?
+      !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
     def image_data=(image_data)
       return if image_data.blank?
       storage.image_data = image_data
     end
-    
+    alias_method :uploaded_data=, :image_data=
+    # nil placeholder in case this field is used in a form.
+    # Aliased as uploaded_data for compatibility with attachment_fu
+    def image_data
+      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?
@@ -195,62 +210,81 @@ 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)
       storage.public_path_for(self, thumbnail)
     end
+    alias_method :public_filename, :public_path
 
     # Gets the absolute filesystem path for the image, or optionally, its
     # thumbnail.
     def absolute_path(thumbnail = nil)
       storage.filesystem_path_for(self, thumbnail)
     end
-    
+
     # Regenerates the thumbails from the main image.
-    def regenerate_thumbnails
-      storage.regenerate_thumbnails(has_image_id, has_image_file)
+    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 has_image_file.blank?
+      return if send(has_image_options[:column]).blank? || !has_image_options[:delete]
       self.class.transaction do
         begin
-          storage.remove_images(self, has_image_file)
+          storage.remove_images(self, send(has_image_options[:column]))
           # The record will be frozen if we're being called after destroy.
           unless frozen?
             # Resorting to SQL here to avoid triggering callbacks. There must be
             # a better way to do this.
-            self.connection.execute("UPDATE #{self.class.table_name} SET has_image_file = NULL WHERE id = #{id}")          
-            self.has_image_file = nil
+            self.connection.execute("UPDATE #{self.class.table_name} SET #{has_image_options[:column]} = NULL WHERE id = #{id}")          
+            self.send("#{has_image_options[:column]}=", nil)
           end
         rescue Errno::ENOENT
           logger.warn("Could not delete files for #{self.class.to_s} #{to_param}")
         end
       end
     end
-    
+
     # Creates new images and removes the old ones when image_data has been
     # set.
     def update_images
       return if storage.temp_file.blank?
       remove_images
-      update_attribute(:has_image_file, storage.install_images(self))      
+      populate_attributes
     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))
+      populate_attributes
     end
-    
+
     # 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,
@@ -259,7 +293,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
@@ -270,6 +314,10 @@ module HasImage
       has_image_options[:thumbnails]
     end
 
+    def from_partitioned_path(path)
+      find HasImage::Storage.id_from_path(path)
+    end
+
   end
 
 end