attachment_fu plug

Microsoft Windows XP [版本 5.1.2600]
(C) 版权所有 1985-2001 Microsoft Corp.

C:\Documents and Settings\sunchaohui>cd D:\radrails-0.7.2-win32\workspace\mm

C:\Documents and Settings\sunchaohui>d:

D:\radrails-0.7.2-win32\workspace\mm>ruby script/plugin install attachment_fu
svn: No repository found in 'svn://rubyforge.org/var/svn/cartographer/plugins'
+ ./CHANGELOG
+ ./README
+ ./Rakefile
+ ./amazon_s3.yml.tpl
+ ./init.rb
+ ./install.rb
+ ./lib/geometry.rb
+ ./lib/technoweenie/attachment_fu/backends/db_file_backend.rb
+ ./lib/technoweenie/attachment_fu/backends/file_system_backend.rb
+ ./lib/technoweenie/attachment_fu/backends/s3_backend.rb
+ ./lib/technoweenie/attachment_fu/processors/core_image_processor.rb
+ ./lib/technoweenie/attachment_fu/processors/gd2_processor.rb
+ ./lib/technoweenie/attachment_fu/processors/image_science_processor.rb
+ ./lib/technoweenie/attachment_fu/processors/mini_magick_processor.rb
+ ./lib/technoweenie/attachment_fu/processors/rmagick_processor.rb
+ ./lib/technoweenie/attachment_fu.rb
+ ./test/backends/db_file_test.rb
+ ./test/backends/file_system_test.rb
+ ./test/backends/remote/s3_test.rb
+ ./test/base_attachment_tests.rb
+ ./test/basic_test.rb
+ ./test/database.yml
+ ./test/extra_attachment_test.rb
+ ./test/fixtures/attachment.rb
+ ./test/fixtures/files/fake/rails.png
+ ./test/fixtures/files/foo.txt
+ ./test/fixtures/files/rails.png
+ ./test/geometry_test.rb
+ ./test/processors/core_image_test.rb
+ ./test/processors/gd2_test.rb
+ ./test/processors/image_science_test.rb
+ ./test/processors/mini_magick_test.rb
+ ./test/processors/rmagick_test.rb
+ ./test/schema.rb
+ ./test/test_helper.rb
+ ./test/validation_test.rb
+ ./vendor/red_artisan/core_image/filters/color.rb
+ ./vendor/red_artisan/core_image/filters/effects.rb
+ ./vendor/red_artisan/core_image/filters/perspective.rb
+ ./vendor/red_artisan/core_image/filters/quality.rb
+ ./vendor/red_artisan/core_image/filters/scale.rb
+ ./vendor/red_artisan/core_image/filters/watermark.rb
+ ./vendor/red_artisan/core_image/processor.rb
attachment-fu
=============

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/blo
sxom/2007/02/24#FileUploadFu>.


attachment_fu functionality
===========================

attachment_fu facilitates file uploads in Ruby on Rails.  There are a few storag
e options for the actual file data, but the plugin always at a minimum stores me
tadata for each file in the database.

There are three storage options for files uploaded through attachment_fu:
  File system
  Database file
  Amazon S3

Each method of storage many options associated with it that will be covered in t
he 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 requi
res an extra table.


attachment_fu models
====================

For all three of these storage options a table of metadata is required.  This ta
ble 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).

In the model there are two methods made available by this plugins: has_attachmen
t and validates_as_attachment.

has_attachment(options = {})
  This method accepts the options in a hash:
    :content_type     # Allowed content types.
                      # Allows all by default.  Use :image to allow all standard
 image types.
    :min_size         # Minimum size allowed.
                      # 1 byte is the default.
    :max_size         # Maximum size allowed.
                      # 1.megabyte is the default.
    :size             # Range of sizes allowed.
                      # (1..1.megabyte) is the default.  This overrides the :min
_size and :max_size options.
    :resize_to        # Used by RMagick to resize images.
                      # Pass either an array of width/height, or a geometry stri
ng.
    :thumbnails       # Specifies a set of thumbnails to generate.
                      # This accepts a hash of filename suffixes and RMagick res
izing options.
                      # This option need only be included if you want thumbnaili
ng.
    :thumbnail_class  # Set which model class to use for thumbnails.
                      # This current attachment class is used by default.
    :path_prefix      # path to store the uploaded files.
                      # Uses public/#{table_name} by default for the filesystem,
 and just #{table_name} for the S3 backend.
                      # Setting this sets the :storage to :file_system.
    :storage          # Specifies the storage system to use..
                      # Defaults to :db_file.  Options are :file_system, :db_fil
e, and :s3.
    :processor        # Sets the image processor to use for resizing of the atta
ched image.
                      # Options include ImageScience, Rmagick, and MiniMagick.
Default is whatever is installed.


  Examples:
    has_attachment :max_size => 1.kilobyte
    has_attachment :size => 1.megabyte..2.megabytes
    has_attachment :content_type => 'application/pdf'
    has_attachment :content_type => ['application/pdf', 'application/msword', 't
ext/plain']
    has_attachment :content_type => :image, :resize_to => [50,50]
    has_attachment :content_type => ['application/pdf', :image], :resize_to => '
x50'
    has_attachment :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
    has_attachment :storage => :file_system, :path_prefix => 'public/files'
    has_attachment :storage => :file_system, :path_prefix => 'public/files',
                   :content_type => :image, :resize_to => [50,50]
    has_attachment :storage => :file_system, :path_prefix => 'public/files',
                   :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
    has_attachment :storage => :s3

validates_as_attachment
  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 validat
ion.

  Example:
    validates_as_attachment


attachment_fu migrations
========================

Fields for attachment_fu metadata tables...
  in general:
    size,         :integer  # file size in bytes
    content_type, :string   # mime type, ex: application/mp3
    filename,     :string   # sanitized filename
  that reference images:
    height,       :integer  # in pixels
    width,        :integer  # in pixels
  that reference images that will be thumbnailed:
    parent_id,    :integer  # id of parent image (on the same table, a self-refe
rencing foreign-key).
                            # Only populated if the current object is a thumbnai
l.
    thumbnail,    :string   # the 'type' of thumbnail this attachment record des
cribes.
                            # Only populated if the current object is a thumbnai
l.
                            # Usage:
                            # [ In Model 'Avatar' ]
                            #   has_attachment :content_type => :image,
                            #                  :storage => :file_system,
                            #                  :max_size => 500.kilobytes,
                            #                  :resize_to => '320x200>',
                            #                  :thumbnails => { :small => '10x10
>',
                            #                                   :thumb => '100x1
00>' }
                            # [ Elsewhere ]
                            # @user.avatar.thumbnails.first.thumbnail #=> 'small
'
  that reference files stored in the database (:db_file):
    db_file_id,   :integer  # id of the file in the database (foreign key)

Field for attachment_fu db_files table:
  data, :binary # binary file data, for use in database file storage


attachment_fu views
===================

There are two main views tasks that will be directly affected by attachment_fu:
upload forms and displaying uploaded images.

There are two parts of the upload form that differ from typical usage.
  1. Include ':multipart => true' in the html options of the form_for tag.
    Example:
      <% form_for(:attachment_metadata, :url => { :action => "create" }, :html =
> { :multipart => true }) do |form| %>

  2. Use the file_field helper with :uploaded_data as the field name.
    Example:
      <%= form.file_field :uploaded_data %>

Displaying uploaded images is made easy by the public_filename method of the Act
iveRecord attachment objects using file system and s3 storage.

public_filename(thumbnail = nil)
  Returns the public path to the file.  If a thumbnail prefix is specified it wi
ll return the public file path to the corresponding thumbnail.
  Examples:
    attachment_obj.public_filename          #=> /attachments/2/file.jpg
    attachment_obj.public_filename(:thumb)  #=> /attachments/2/file_thumb.jpg
    attachment_obj.public_filename(:small)  #=> /attachments/2/file_small.jpg

When serving files from database storage, doing more than simply downloading the
 file is beyond the scope of this document.


attachment_fu controllers
=========================

There are two considerations to take into account when using attachment_fu in co
ntrollers.

The first is when the files have no publicly accessible path and need to be down
loaded through an action.

Example:
  def readme
    send_file '/path/to/readme.txt', :type => 'plain/text', :disposition => 'inl
ine'
  end

See the possible values for send_file for reference.


The second is when saving the file when submitted from a form.
Example in view:
 <%= form.file_field :attachable, :uploaded_data %>

Example in controller:
  def create
    @attachable_file = AttachmentMetadataModel.new(params[:attachable])
    if @attachable_file.save
      flash[:notice] = 'Attachment was successfully created.'
      redirect_to attachable_url(@attachable_file)
    else
      render :action => :new
    end
  end

D:\radrails-0.7.2-win32\workspace\mm>