projects.mako.cc - selectricity/blob - vendor/plugins/attachment_fu/README

   1 attachment-fu
   2 =============
   3
   4 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>.
   5
   6
   7 attachment_fu functionality
   8 ===========================
   9
  10 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.
  11
  12 There are three storage options for files uploaded through attachment_fu:
  13   File system
  14   Database file
  15   Amazon S3
  16
  17 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.
  18
  19
  20 attachment_fu models
  21 ====================
  22
  23 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).
  24
  25 In the model there are two methods made available by this plugins: has_attachment and validates_as_attachment.
  26
  27 has_attachment(options = {})
  28   This method accepts the options in a hash:
  29     :content_type     # Allowed content types.
  30                       # Allows all by default.  Use :image to allow all standard image types.
  31     :min_size         # Minimum size allowed.
  32                       # 1 byte is the default.
  33     :max_size         # Maximum size allowed.
  34                       # 1.megabyte is the default.
  35     :size             # Range of sizes allowed.
  36                       # (1..1.megabyte) is the default.  This overrides the :min_size and :max_size options.
  37     :resize_to        # Used by RMagick to resize images.
  38                       # Pass either an array of width/height, or a geometry string.
  39     :thumbnails       # Specifies a set of thumbnails to generate.
  40                       # This accepts a hash of filename suffixes and RMagick resizing options.
  41                       # This option need only be included if you want thumbnailing.
  42     :thumbnail_class  # Set which model class to use for thumbnails.
  43                       # This current attachment class is used by default.
  44     :path_prefix      # path to store the uploaded files.
  45                       # Uses public/#{table_name} by default for the filesystem, and just #{table_name} for the S3 backend.
  46                       # Setting this sets the :storage to :file_system.
  47     :storage          # Specifies the storage system to use..
  48                       # Defaults to :db_file.  Options are :file_system, :db_file, and :s3.
  49     :processor        # Sets the image processor to use for resizing of the attached image.
  50                       # Options include ImageScience, Rmagick, and MiniMagick.  Default is whatever is installed.
  51
  52
  53   Examples:
  54     has_attachment :max_size => 1.kilobyte
  55     has_attachment :size => 1.megabyte..2.megabytes
  56     has_attachment :content_type => 'application/pdf'
  57     has_attachment :content_type => ['application/pdf', 'application/msword', 'text/plain']
  58     has_attachment :content_type => :image, :resize_to => [50,50]
  59     has_attachment :content_type => ['application/pdf', :image], :resize_to => 'x50'
  60     has_attachment :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
  61     has_attachment :storage => :file_system, :path_prefix => 'public/files'
  62     has_attachment :storage => :file_system, :path_prefix => 'public/files',
  63                    :content_type => :image, :resize_to => [50,50]
  64     has_attachment :storage => :file_system, :path_prefix => 'public/files',
  65                    :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
  66     has_attachment :storage => :s3
  67
  68 validates_as_attachment
  69   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.
  70
  71   Example:
  72     validates_as_attachment
  73
  74
  75 attachment_fu migrations
  76 ========================
  77
  78 Fields for attachment_fu metadata tables...
  79   in general:
  80     size,         :integer  # file size in bytes
  81     content_type, :string   # mime type, ex: application/mp3
  82     filename,     :string   # sanitized filename
  83   that reference images:
  84     height,       :integer  # in pixels
  85     width,        :integer  # in pixels
  86   that reference images that will be thumbnailed:
  87     parent_id,    :integer  # id of parent image (on the same table, a self-referencing foreign-key).
  88                             # Only populated if the current object is a thumbnail.
  89     thumbnail,    :string   # the 'type' of thumbnail this attachment record describes.
  90                             # Only populated if the current object is a thumbnail.
  91                             # Usage:
  92                             # [ In Model 'Avatar' ]
  93                             #   has_attachment :content_type => :image,
  94                             #                  :storage => :file_system,
  95                             #                  :max_size => 500.kilobytes,
  96                             #                  :resize_to => '320x200>',
  97                             #                  :thumbnails => { :small => '10x10>',
  98                             #                                   :thumb => '100x100>' }
  99                             # [ Elsewhere ]
 100                             # @user.avatar.thumbnails.first.thumbnail #=> 'small'
 101   that reference files stored in the database (:db_file):
 102     db_file_id,   :integer  # id of the file in the database (foreign key)
 103
 104 Field for attachment_fu db_files table:
 105   data, :binary # binary file data, for use in database file storage
 106
 107
 108 attachment_fu views
 109 ===================
 110
 111 There are two main views tasks that will be directly affected by attachment_fu: upload forms and displaying uploaded images.
 112
 113 There are two parts of the upload form that differ from typical usage.
 114   1. Include ':multipart => true' in the html options of the form_for tag.
 115     Example:
 116       <% form_for(:attachment_metadata, :url => { :action => "create" }, :html => { :multipart => true }) do |form| %>
 117
 118   2. Use the file_field helper with :uploaded_data as the field name.
 119     Example:
 120       <%= form.file_field :uploaded_data %>
 121
 122 Displaying uploaded images is made easy by the public_filename method of the ActiveRecord attachment objects using file system and s3 storage.
 123
 124 public_filename(thumbnail = nil)
 125   Returns the public path to the file.  If a thumbnail prefix is specified it will return the public file path to the corresponding thumbnail.
 126   Examples:
 127     attachment_obj.public_filename          #=> /attachments/2/file.jpg
 128     attachment_obj.public_filename(:thumb)  #=> /attachments/2/file_thumb.jpg
 129     attachment_obj.public_filename(:small)  #=> /attachments/2/file_small.jpg
 130
 131 When serving files from database storage, doing more than simply downloading the file is beyond the scope of this document.
 132
 133
 134 attachment_fu controllers
 135 =========================
 136
 137 There are two considerations to take into account when using attachment_fu in controllers.
 138
 139 The first is when the files have no publicly accessible path and need to be downloaded through an action.
 140
 141 Example:
 142   def readme
 143     send_file '/path/to/readme.txt', :type => 'plain/text', :disposition => 'inline'
 144   end
 145
 146 See the possible values for send_file for reference.
 147
 148
 149 The second is when saving the file when submitted from a form.
 150 Example in view:
 151  <%= form.file_field :attachable, :uploaded_data %>
 152
 153 Example in controller:
 154   def create
 155     @attachable_file = AttachmentMetadataModel.new(params[:attachable])
 156     if @attachable_file.save
 157       flash[:notice] = 'Attachment was successfully created.'
 158       redirect_to attachable_url(@attachable_file)
 159     else
 160       render :action => :new
 161     end
 162   end