0
@@ -1,4 +1,162 @@
0
 attachment-fu
0
 =====================
0
 
0
-Acts as Attachment rewrite, come back later please!
0
\ No newline at end of file
0
+attachment_fu is a plugin by Rick Olson (aka technoweenie <http://techno-weenie.net>) and is the successor to acts_as_attachment.  To get a basic run-through of its capabilities, check out Mike Clark's tutorial <http://clarkware.com/cgi/blosxom/2007/02/24#FileUploadFu>.
0
+
0
+
0
+attachment_fu functionality
0
+===========================
0
+
0
+attachment_fu facilitates file uploads in Ruby on Rails.  There are a few storage options for the actual file data, but the plugin always at a minimum stores metadata for each file in the database.
0
+
0
+There are three storage options for files uploaded through attachment_fu:
0
+  File system
0
+  Database file
0
+  Amazon S3
0
+
0
+Each method of storage many options associated with it that will be covered in the following section.  Something to note, however, is that the Amazon S3 storage requires you to modify config/amazon_s3.yml and the Database file storage requires an extra table.
0
+
0
+
0
+attachment_fu models
0
+====================
0
+
0
+For all three of these storage options a table of metadata is required.  This table will contain information about the file (hence the 'meta') and its location.  This table has no restrictions on naming, unlike the extra table required for database storage, which must have a table name of db_files (and by convention a model of DbFile).
0
+  
0
+In the model there are two methods made available by this plugins: has_attachment and validates_as_attachment.
0
+
0
+has_attachment(options = {})
0
+  This method accepts the options in a hash:
0
+    :content_type     # Allowed content types.
0
+                      # Allows all by default.  Use :image to allow all standard image types.
0
+    :min_size         # Minimum size allowed.
0
+                      # 1 byte is the default.
0
+    :max_size         # Maximum size allowed.
0
+                      # 1.megabyte is the default.
0
+    :size             # Range of sizes allowed.
0
+                      # (1..1.megabyte) is the default.  This overrides the :min_size and :max_size options.
0
+    :resize_to        # Used by RMagick to resize images.
0
+                      # Pass either an array of width/height, or a geometry string.
0
+    :thumbnails       # Specifies a set of thumbnails to generate.
0
+                      # This accepts a hash of filename suffixes and RMagick resizing options.
0
+                      # This option need only be included if you want thumbnailing.
0
+    :thumbnail_class  # Set which model class to use for thumbnails.
0
+                      # This current attachment class is used by default.
0
+    :path_prefix      # path to store the uploaded files.
0
+                      # Uses public/#{table_name} by default for the filesystem, and just #{table_name} for the S3 backend.  
0
+                      # Setting this sets the :storage to :file_system.
0
+    :storage          # Specifies the storage system to use..
0
+                      # Defaults to :db_file.  Options are :file_system, :db_file, and :s3.
0
+    :processor        # Sets the image processor to use for resizing of the attached image.
0
+                      # Options include ImageScience, Rmagick, and MiniMagick.  Default is whatever is installed.
0
+    
0
+
0
+  Examples:
0
+    has_attachment :max_size => 1.kilobyte
0
+    has_attachment :size => 1.megabyte..2.megabytes
0
+    has_attachment :content_type => 'application/pdf'
0
+    has_attachment :content_type => ['application/pdf', 'application/msword', 'text/plain']
0
+    has_attachment :content_type => :image, :resize_to => [50,50]
0
+    has_attachment :content_type => ['application/pdf', :image], :resize_to => 'x50'
0
+    has_attachment :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
0
+    has_attachment :storage => :file_system, :path_prefix => 'public/files'
0
+    has_attachment :storage => :file_system, :path_prefix => 'public/files', 
0
+                   :content_type => :image, :resize_to => [50,50]
0
+    has_attachment :storage => :file_system, :path_prefix => 'public/files',
0
+                   :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
0
+    has_attachment :storage => :s3
0
+
0
+validates_as_attachment
0
+  This method prevents files outside of the valid range (:min_size to :max_size, or the :size range) from being saved.  It does not however, halt the upload of such files.  They will be uploaded into memory regardless of size before validation.
0
+  
0
+  Example:
0
+    validates_as_attachment
0
+
0
+
0
+attachment_fu migrations
0
+========================
0
+
0
+Fields for attachment_fu metadata tables...
0
+  in general:
0
+    size,         :integer  # file size in bytes
0
+    content_type, :string   # mime type, ex: application/mp3
0
+    filename,     :string   # sanitized filename
0
+  that reference images:
0
+    height,       :integer  # in pixels
0
+    width,        :integer  # in pixels
0
+  that reference images that will be thumbnailed:
0
+    parent_id,    :integer  # id of parent image (on the same table, a self-referencing foreign-key).
0
+                            # Only populated if the current object is a thumbnail.
0
+    thumbnail,    :string   # the 'type' of thumbnail this attachment record describes.  
0
+                            # Only populated if the current object is a thumbnail.
0
+                            # Usage:
0
+                            # [ In Model 'Avatar' ]
0
+                            #   has_attachment :content_type => :image, 
0
+                            #                  :storage => :file_system, 
0
+                            #                  :max_size => 500.kilobytes,
0
+                            #                  :resize_to => '320x200>',
0
+                            #                  :thumbnails => { :small => '10x10>',
0
+                            #                                   :thumb => '100x100>' }
0
+                            # [ Elsewhere ]
0
+                            # @user.avatar.thumbnails.first.thumbnail #=> 'small'
0
+  that reference files stored in the database (:db_file):
0
+    db_file_id,   :integer  # id of the file in the database (foreign key)
0
+    
0
+Field for attachment_fu db_files table:
0
+  data, :binary # binary file data, for use in database file storage
0
+
0
+
0
+attachment_fu views
0
+===================
0
+
0
+There are two main views tasks that will be directly affected by attachment_fu: upload forms and displaying uploaded images.
0
+
0
+There are two parts of the upload form that differ from typical usage.
0
+  1. Include ':multipart => true' in the html options of the form_for tag.
0
+    Example:
0
+      <% form_for(:attachment_metadata, :url => { :action => "create" }, :html => { :multipart => true }) do |form| %>
0
+      
0
+  2. Use the file_field helper with :uploaded_data as the field name.
0
+    Example:
0
+      <%= form.file_field :uploaded_data %>
0
+
0
+Displaying uploaded images is made easy by the public_filename method of the ActiveRecord attachment objects using file system and s3 storage.
0
+
0
+public_filename(thumbnail = nil)
0
+  Returns the public path to the file.  If a thumbnail prefix is specified it will return the public file path to the corresponding thumbnail.
0
+  Examples:
0
+    attachment_obj.public_filename          #=> /attachments/2/file.jpg
0
+    attachment_obj.public_filename(:thumb)  #=> /attachments/2/file_thumb.jpg
0
+    attachment_obj.public_filename(:small)  #=> /attachments/2/file_small.jpg
0
+
0
+When serving files from database storage, doing more than simply downloading the file is beyond the scope of this document.
0
+
0
+
0
+attachment_fu controllers
0
+=========================
0
+
0
+There are two considerations to take into account when using attachment_fu in controllers.
0
+
0
+The first is when the files have no publicly accessible path and need to be downloaded through an action.
0
+
0
+Example:
0
+  def readme
0
+    send_file '/path/to/readme.txt', :type => 'plain/text', :disposition => 'inline'
0
+  end
0
+  
0
+See the possible values for send_file for reference.
0
+
0
+
0
+The second is when saving the file when submitted from a form.
0
+Example in view:
0
+ <%= form.file_field :attachable, :uploaded_data %>
0
+
0
+Example in controller:
0
+  def create
0
+    @attachable_file = AttachmentMetadataModel.new(params[:attachable])
0
+    if @attachable_file.save
0
+      flash[:notice] = 'Attachment was successfully created.'
0
+      redirect_to attachable_url(@attachable_file)     
0
+    else
0
+      render :action => :new
0
+    end
0
+  end

0
@@ -2,7 +2,7 @@ module Technoweenie # :nodoc:
0
   module AttachmentFu # :nodoc:
0
     @@default_processors = %w(ImageScience Rmagick MiniMagick)
0
     @@tempfile_path      = File.join(RAILS_ROOT, 'tmp', 'attachment_fu')
0
-    @@content_types      = ['image/jpeg', 'image/pjpeg', 'image/gif', 'image/png', 'image/x-png']
0
+    @@content_types      = ['image/jpeg', 'image/pjpeg', 'image/gif', 'image/png', 'image/x-png', 'image/jpg']
0
     mattr_reader :content_types, :tempfile_path, :default_processors
0
     mattr_writer :tempfile_path
0
 
0
@@ -44,23 +44,32 @@ module Technoweenie # :nodoc:
0
         options[:thumbnails]       ||= {}
0
         options[:thumbnail_class]  ||= self
0
         options[:s3_access]        ||= :public_read
0
+        options[:content_type] = [options[:content_type]].flatten.collect! { |t| t == :image ? Technoweenie::AttachmentFu.content_types : t }.flatten unless options[:content_type].nil?
0
+        
0
+        unless options[:thumbnails].is_a?(Hash)
0
+          raise ArgumentError, ":thumbnails option should be a hash: e.g. :thumbnails => { :foo => '50x50' }"
0
+        end
0
+        
0
+        # doing these shenanigans so that #attachment_options is available to processors and backends
0
+        class_inheritable_accessor :attachment_options
0
+        self.attachment_options = options
0
 
0
         # only need to define these once on a class
0
-        unless included_modules.include? InstanceMethods
0
-          class_inheritable_accessor :attachment_options
0
+        unless included_modules.include?(InstanceMethods)
0
           attr_accessor :thumbnail_resize_options
0
 
0
-          options[:storage]     ||= (options[:file_system_path] || options[:path_prefix]) ? :file_system : :db_file
0
-          options[:path_prefix] ||= options[:file_system_path]
0
-          if options[:path_prefix].nil?
0
-            options[:path_prefix] = options[:storage] == :s3 ? table_name : File.join("public", table_name)
0
+          attachment_options[:storage]     ||= (attachment_options[:file_system_path] || attachment_options[:path_prefix]) ? :file_system : :db_file
0
+          attachment_options[:path_prefix] ||= attachment_options[:file_system_path]
0
+          if attachment_options[:path_prefix].nil?
0
+            attachment_options[:path_prefix] = attachment_options[:storage] == :s3 ? table_name : File.join("public", table_name)
0
           end
0
-          options[:path_prefix]   = options[:path_prefix][1..-1] if options[:path_prefix].first == '/'
0
+          attachment_options[:path_prefix]   = attachment_options[:path_prefix][1..-1] if options[:path_prefix].first == '/'
0
 
0
           with_options :foreign_key => 'parent_id' do |m|
0
-            m.has_many   :thumbnails, :dependent => :destroy, :class_name => options[:thumbnail_class].to_s
0
+            m.has_many   :thumbnails, :class_name => attachment_options[:thumbnail_class].to_s
0
             m.belongs_to :parent, :class_name => base_class.to_s
0
           end
0
+          before_destroy :destroy_thumbnails
0
 
0
           before_validation :set_size_from_temp_path
0
           after_save :after_process_attachment
0
@@ -68,7 +77,7 @@ module Technoweenie # :nodoc:
0
           extend  ClassMethods
0
           include InstanceMethods
0
           include Technoweenie::AttachmentFu::Backends.const_get("#{options[:storage].to_s.classify}Backend")
0
-          case options[:processor]
0
+          case attachment_options[:processor]
0
             when :none
0
             when nil
0
               processors = Technoweenie::AttachmentFu.default_processors.dup
0
@@ -79,13 +88,14 @@ module Technoweenie # :nodoc:
0
                 retry
0
               end
0
             else
0
-              include Technoweenie::AttachmentFu::Processors.const_get("#{options[:processor].to_s.classify}Processor")
0
+              begin
0
+                include Technoweenie::AttachmentFu::Processors.const_get("#{options[:processor].to_s.classify}Processor")
0
+              rescue LoadError, MissingSourceFile
0
+                puts "Problems loading #{options[:processor]}Processor: #{$!}"
0
+              end
0
           end
0
           after_validation :process_attachment
0
         end
0
-        
0
-        options[:content_type] = [options[:content_type]].flatten.collect { |t| t == :image ? Technoweenie::AttachmentFu.content_types : t }.flatten unless options[:content_type].nil?
0
-        self.attachment_options = options
0
       end
0
     end
0
 
0
@@ -158,6 +168,7 @@ module Technoweenie # :nodoc:
0
       # Writes the given data to a new tempfile, returning the closed tempfile.
0
       def write_to_temp_file(data, temp_base_name)
0
         returning Tempfile.new(temp_base_name, Technoweenie::AttachmentFu.tempfile_path) do |tmp|
0
+          tmp.binmode
0
           tmp.write data
0
           tmp.close
0
         end
0
@@ -172,7 +183,7 @@ module Technoweenie # :nodoc:
0
       
0
       # Returns true/false if an attachment is thumbnailable.  A thumbnailable attachment has an image content type and the parent_id attribute.
0
       def thumbnailable?
0
-        image? && respond_to?(:parent_id)
0
+        image? && respond_to?(:parent_id) && parent_id.nil?
0
       end
0
 
0
       # Returns the class used to create new thumbnails for this attachment.
0
@@ -247,7 +258,7 @@ module Technoweenie # :nodoc:
0
           file_data.rewind
0
           self.temp_data = file_data.read
0
         else
0
-          self.temp_path    = file_data.path
0
+          self.temp_path = file_data.path
0
         end
0
       end
0
 
0
@@ -260,9 +271,9 @@ module Technoweenie # :nodoc:
0
         p.respond_to?(:path) ? p.path : p.to_s
0
       end
0
       
0
-      # Gets an array of the currently used temp paths.
0
+      # Gets an array of the currently used temp paths.  Defaults to a copy of #full_filename.
0
       def temp_paths
0
-        @temp_paths ||= []
0
+        @temp_paths ||= (new_record? || !File.exist?(full_filename)) ? [] : [copy_to_temp_file(full_filename)]
0
       end
0
       
0
       # Adds a new temp_path to the array.  This should take a string or a Tempfile.  This class makes no 
0
@@ -384,6 +395,11 @@ module Technoweenie # :nodoc:
0
 
0
           return result
0
         end
0
+        
0
+        # Removes the thumbnails for the attachment, if it has any
0
+        def destroy_thumbnails
0
+          self.thumbnails.each { |thumbnail| thumbnail.destroy } if thumbnailable?
0
+        end
0
     end
0
   end
0
 end

0
@@ -18,7 +18,7 @@ module Technoweenie # :nodoc:
0
         # The optional thumbnail argument will output the thumbnail's filename.
0
         def full_filename(thumbnail = nil)
0
           file_system_path = (thumbnail ? thumbnail_class : self).attachment_options[:path_prefix].to_s
0
-          File.join(RAILS_ROOT, file_system_path, attachment_path_id, thumbnail_name_for(thumbnail))
0
+          File.join(RAILS_ROOT, file_system_path, *partitioned_path(thumbnail_name_for(thumbnail)))
0
         end
0
       
0
         # Used as the base path that #public_filename strips off full_filename to create the public path
0
@@ -28,7 +28,13 @@ module Technoweenie # :nodoc:
0
       
0
         # The attachment ID used in the full path of a file
0
         def attachment_path_id
0
-          ((respond_to?(:parent_id) && parent_id) || id).to_s
0
+          ((respond_to?(:parent_id) && parent_id) || id).to_i
0
+        end
0
+      
0
+        # overrwrite this to do your own app-specific partitioning. 
0
+        # you can thank Jamis Buck for this: http://www.37signals.com/svn/archives2/id_partitioning.php
0
+        def partitioned_path(*args)
0
+          ("%08d" % attachment_path_id).scan(/..../) + args
0
         end
0
       
0
         # Gets the public path to the file

0
@@ -34,6 +34,10 @@ module Technoweenie # :nodoc:
0
       #     access_key_id: <your key>
0
       #     secret_access_key: <your key>
0
       #
0
+      # You can change the location of the config path by passing a full path to the :s3_config_path option.
0
+      #
0
+      #   has_attachment :storage => :s3, :s3_config_path => (RAILS_ROOT + '/config/s3.yml')
0
+      #
0
       # === Required configuration parameters
0
       #
0
       # * <tt>:access_key_id</tt> - The access key id for your S3 account. Provided by Amazon.
0
@@ -128,9 +132,10 @@ module Technoweenie # :nodoc:
0
           end
0
 
0
           begin
0
-            @@s3_config = YAML.load_file(RAILS_ROOT + '/config/amazon_s3.yml')[ENV['RAILS_ENV']].symbolize_keys
0
-          rescue
0
-            raise ConfigFileNotFoundError.new('File RAILS_ROOT/config/amazon_s3.yml not found')
0
+            @@s3_config_path = base.attachment_options[:s3_config_path] || (RAILS_ROOT + '/config/amazon_s3.yml')
0
+            @@s3_config = YAML.load_file(@@s3_config_path)[ENV['RAILS_ENV']].symbolize_keys
0
+          #rescue
0
+          #  raise ConfigFileNotFoundError.new('File %s not found' % @@s3_config_path)
0
           end
0
 
0
           @@bucket_name = s3_config[:bucket_name]
0
@@ -288,7 +293,7 @@ module Technoweenie # :nodoc:
0
             if save_attachment?
0
               S3Object.store(
0
                 full_filename,
0
-                temp_data,
0
+                (temp_path ? File.open(temp_path) : temp_data),
0
                 bucket_name,
0
                 :content_type => content_type,
0
                 :access => attachment_options[:s3_access]

0
@@ -18,12 +18,17 @@ module Technoweenie # :nodoc:
0
         protected
0
           def process_attachment_with_processing
0
             return unless process_attachment_without_processing && image?
0
-            with_image { |img| resize_image_or_thumbnail! img }
0
+            with_image do |img|
0
+              self.width  = img.width  if respond_to?(:width)
0
+              self.height = img.height if respond_to?(:height)
0
+              resize_image_or_thumbnail! img
0
+            end
0
           end
0
 
0
           # Performs the actual resizing operation for a thumbnail
0
           def resize_image(img, size)
0
             # create a dummy temp file to write to
0
+            filename.sub! /gif$/, 'png'
0
             self.temp_path = write_to_temp_file(filename)
0
             grab_dimensions = lambda do |img|
0
               self.width  = img.width  if respond_to?(:width)

0
@@ -48,7 +48,7 @@ module Technoweenie # :nodoc:
0
           else
0
             img.resize(size.to_s)
0
           end
0
-          self.temp_path = img.path
0
+          self.temp_path = img
0
         end
0
       end
0
     end

0
@@ -2,7 +2,7 @@ require File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'test_hel
0
 require 'net/http'
0
 
0
 class S3Test < Test::Unit::TestCase
0
-  if File.exist?(RAILS_ROOT + '/config/amazon_s3.yml')
0
+  if File.exist?(File.join(File.dirname(__FILE__), '../../amazon_s3.yml'))
0
     include BaseAttachmentTests
0
     attachment_model S3Attachment
0
 
0
@@ -85,15 +85,15 @@ class S3Test < Test::Unit::TestCase
0
       end
0
       
0
       def s3_protocol
0
-        Technoweenie::AttachmentFu::Backends::S3.protocol
0
+        Technoweenie::AttachmentFu::Backends::S3Backend.protocol
0
       end
0
       
0
       def s3_hostname
0
-        Technoweenie::AttachmentFu::Backends::S3.hostname
0
+        Technoweenie::AttachmentFu::Backends::S3Backend.hostname
0
       end
0
 
0
       def s3_port_string
0
-        Technoweenie::AttachmentFu::Backends::S3.port_string
0
+        Technoweenie::AttachmentFu::Backends::S3Backend.port_string
0
       end
0
   else
0
     def test_flunk_s3

0
@@ -54,4 +54,11 @@ class BasicTest < Test::Unit::TestCase
0
     @attachment.filename = 'foo.bar.baz'
0
     assert_equal 'foo.bar_blah.baz', @attachment.thumbnail_name_for(:blah)
0
   end
0
+  
0
+  def test_should_require_valid_thumbnails_option
0
+    klass = Class.new(ActiveRecord::Base)
0
+    assert_raise ArgumentError do
0
+      klass.has_attachment :thumbnails => []
0
+    end
0
+  end
0
 end
0
\ No newline at end of file

0
@@ -114,7 +114,7 @@ end
0
 
0
 begin
0
   class S3Attachment < ActiveRecord::Base
0
-    has_attachment :storage => :s3, :processor => :rmagick
0
+    has_attachment :storage => :s3, :processor => :rmagick, :s3_config_path => File.join(File.dirname(__FILE__), '../amazon_s3.yml')
0
     validates_as_attachment
0
   end
0
 
0
@@ -123,4 +123,5 @@ begin
0
     validates_as_attachment
0
   end
0
 rescue Technoweenie::AttachmentFu::Backends::S3Backend::ConfigFileNotFoundError
0
+  puts "S3 error: #{$!}"
0
 end

0
@@ -9,7 +9,7 @@ class ImageScienceTest < Test::Unit::TestCase
0
       assert_valid attachment
0
       assert attachment.image?
0
       # test image science thumbnail
0
-      assert_equal 43, attachment.width
0
+      assert_equal 42, attachment.width
0
       assert_equal 55, attachment.height
0
       
0
       thumb      = attachment.thumbnails.detect { |t| t.filename =~ /_thumb/ }
0
@@ -21,7 +21,7 @@ class ImageScienceTest < Test::Unit::TestCase
0
       
0
       # test geometry string
0
       assert_equal 31, geo.width
0
-      assert_equal 40, geo.height
0
+      assert_equal 41, geo.height
0
     end
0
   else
0
     def test_flunk

0
@@ -162,6 +162,7 @@ class RmagickTest < Test::Unit::TestCase
0
       assert_equal 'rails_thumb.png', attachment.thumbnails.first.filename
0
       assert_equal attachment.thumbnails.first.full_filename, attachment.full_filename(attachment.thumbnails.first.thumbnail),
0
         "#full_filename does not use thumbnail class' path."
0
+      assert_equal attachment.destroy attachment
0
     end
0
     
0
     test_against_subclass :test_should_use_thumbnail_subclass, ImageWithThumbsClassFileAttachment

0
@@ -10,7 +10,28 @@ require 'action_controller/test_process'
0
 
0
 config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
0
 ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
0
-ActiveRecord::Base.establish_connection(config[ENV['DB'] || 'sqlite'])
0
+
0
+db_adapter = ENV['DB']
0
+
0
+# no db passed, try one of these fine config-free DBs before bombing.
0
+db_adapter ||= 
0
+  begin
0
+    require 'rubygems'
0
+    require 'sqlite'
0
+    'sqlite'
0
+  rescue MissingSourceFile
0
+    begin
0
+      require 'sqlite3'
0
+      'sqlite3'
0
+    rescue MissingSourceFile
0
+    end
0
+  end
0
+
0
+if db_adapter.nil?
0
+  raise "No DB Adapter selected.  Pass the DB= option to pick one, or install Sqlite or Sqlite3."
0
+end
0
+
0
+ActiveRecord::Base.establish_connection(config[db_adapter])
0
 
0
 load(File.dirname(__FILE__) + "/schema.rb")
0