Skip to content
This repository
Newer
Older
100644 194 lines (149 sloc) 9.889 kb
1e91f654 »
2006-12-14 attachment-fu, acts_as_attachment rewrite
1 attachment-fu
ca63a36d »
2008-01-25 bs change to test duplikate
2 =============
1e91f654 »
2006-12-14 attachment-fu, acts_as_attachment rewrite
3
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
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>.
1c145749 »
2007-04-02 other fixes, but most importantly: Don't try to remove thumbnails if …
5
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
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
979ceb9a »
2009-03-24 Update README to reflect Cloud Files.
12 There are four storage options for files uploaded through attachment_fu:
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
13 File system
14 Database file
15 Amazon S3
979ceb9a »
2009-03-24 Update README to reflect Cloud Files.
16 Rackspace (Mosso) Cloud Files
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
17
979ceb9a »
2009-03-24 Update README to reflect Cloud Files.
18 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, the Rackspace Cloud Files storage requires you to modify config/rackspace_cloudfiles.yml, and the Database file storage requires an extra table.
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
19
20
21 attachment_fu models
22 ====================
23
24 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).
25
26 In the model there are two methods made available by this plugins: has_attachment and validates_as_attachment.
27
28 has_attachment(options = {})
29 This method accepts the options in a hash:
30 :content_type # Allowed content types.
31 # Allows all by default. Use :image to allow all standard image types.
32 :min_size # Minimum size allowed.
33 # 1 byte is the default.
34 :max_size # Maximum size allowed.
35 # 1.megabyte is the default.
36 :size # Range of sizes allowed.
37 # (1..1.megabyte) is the default. This overrides the :min_size and :max_size options.
38 :resize_to # Used by RMagick to resize images.
39 # Pass either an array of width/height, or a geometry string.
40 :thumbnails # Specifies a set of thumbnails to generate.
41 # This accepts a hash of filename suffixes and RMagick resizing options.
42 # This option need only be included if you want thumbnailing.
43 :thumbnail_class # Set which model class to use for thumbnails.
44 # This current attachment class is used by default.
d55631d1 »
2008-09-23 Improve wording in README.
45 :path_prefix # Path to store the uploaded files in.
979ceb9a »
2009-03-24 Update README to reflect Cloud Files.
46 # Uses public/#{table_name} by default for the filesystem, and just #{table_name} for the S3 and Cloud Files backend.
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
47 # Setting this sets the :storage to :file_system.
d55631d1 »
2008-09-23 Improve wording in README.
48 :partition # Whether to partiton files in directories like /0000/0001/image.jpg. Default is true. Only applicable to the :file_system backend.
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
49 :storage # Specifies the storage system to use..
979ceb9a »
2009-03-24 Update README to reflect Cloud Files.
50 # Defaults to :db_file. Options are :file_system, :db_file, :s3, and :cloud_files.
51c4e276 »
2009-03-15 Updated README to add CloudFront options.
51 :cloudfront # If using S3 for storage, this option allows for serving the files via Amazon CloudFront.
52 # Defaults to false.
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
53 :processor # Sets the image processor to use for resizing of the attached image.
54 # Options include ImageScience, Rmagick, and MiniMagick. Default is whatever is installed.
2c164b68 »
2008-09-23 Add support for models that have a string as primary key.
55 :uuid_primary_key # If your model's primary key is a 128-bit UUID in hexadecimal format, then set this to true.
45b0e31c »
2008-09-23 Add an ':association_options' option for passing additional options t…
56 :association_options # attachment_fu automatically defines associations with thumbnails with has_many and belongs_to. If there are any additional options that you want to pass to these methods, then specify them here.
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
57
58
59 Examples:
60 has_attachment :max_size => 1.kilobyte
61 has_attachment :size => 1.megabyte..2.megabytes
62 has_attachment :content_type => 'application/pdf'
63 has_attachment :content_type => ['application/pdf', 'application/msword', 'text/plain']
64 has_attachment :content_type => :image, :resize_to => [50,50]
65 has_attachment :content_type => ['application/pdf', :image], :resize_to => 'x50'
66 has_attachment :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
67 has_attachment :storage => :file_system, :path_prefix => 'public/files'
68 has_attachment :storage => :file_system, :path_prefix => 'public/files',
8a1e6491 »
2008-06-09 Add documentation for new :partition option
69 :content_type => :image, :resize_to => [50,50], :partition => false
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
70 has_attachment :storage => :file_system, :path_prefix => 'public/files',
71 :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
72 has_attachment :storage => :s3
51c4e276 »
2009-03-15 Updated README to add CloudFront options.
73 has_attachment :store => :s3, :cloudfront => true
979ceb9a »
2009-03-24 Update README to reflect Cloud Files.
74 has_attachment :storage => :cloud_files
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
75
76 validates_as_attachment
77 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.
78
79 Example:
80 validates_as_attachment
81
82
83 attachment_fu migrations
84 ========================
85
86 Fields for attachment_fu metadata tables...
87 in general:
88 size, :integer # file size in bytes
89 content_type, :string # mime type, ex: application/mp3
90 filename, :string # sanitized filename
91 that reference images:
92 height, :integer # in pixels
93 width, :integer # in pixels
94 that reference images that will be thumbnailed:
95 parent_id, :integer # id of parent image (on the same table, a self-referencing foreign-key).
96 # Only populated if the current object is a thumbnail.
97 thumbnail, :string # the 'type' of thumbnail this attachment record describes.
98 # Only populated if the current object is a thumbnail.
99 # Usage:
100 # [ In Model 'Avatar' ]
101 # has_attachment :content_type => :image,
102 # :storage => :file_system,
103 # :max_size => 500.kilobytes,
104 # :resize_to => '320x200>',
105 # :thumbnails => { :small => '10x10>',
106 # :thumb => '100x100>' }
107 # [ Elsewhere ]
108 # @user.avatar.thumbnails.first.thumbnail #=> 'small'
109 that reference files stored in the database (:db_file):
110 db_file_id, :integer # id of the file in the database (foreign key)
111
112 Field for attachment_fu db_files table:
113 data, :binary # binary file data, for use in database file storage
114
115
116 attachment_fu views
117 ===================
118
119 There are two main views tasks that will be directly affected by attachment_fu: upload forms and displaying uploaded images.
120
121 There are two parts of the upload form that differ from typical usage.
122 1. Include ':multipart => true' in the html options of the form_for tag.
123 Example:
124 <% form_for(:attachment_metadata, :url => { :action => "create" }, :html => { :multipart => true }) do |form| %>
125
126 2. Use the file_field helper with :uploaded_data as the field name.
127 Example:
128 <%= form.file_field :uploaded_data %>
129
979ceb9a »
2009-03-24 Update README to reflect Cloud Files.
130 Displaying uploaded images is made easy by the public_filename method of the ActiveRecord attachment objects using file system, s3, and Cloud Files storage.
1b498f4e »
2007-06-27 add bad ass readme doc [fowlduck]
131
132 public_filename(thumbnail = nil)
133 Returns the public path to the file. If a thumbnail prefix is specified it will return the public file path to the corresponding thumbnail.
134 Examples:
135 attachment_obj.public_filename #=> /attachments/2/file.jpg
136 attachment_obj.public_filename(:thumb) #=> /attachments/2/file_thumb.jpg
137 attachment_obj.public_filename(:small) #=> /attachments/2/file_small.jpg
138
139 When serving files from database storage, doing more than simply downloading the file is beyond the scope of this document.
140
141
142 attachment_fu controllers
143 =========================
144
145 There are two considerations to take into account when using attachment_fu in controllers.
146
147 The first is when the files have no publicly accessible path and need to be downloaded through an action.
148
149 Example:
150 def readme
151 send_file '/path/to/readme.txt', :type => 'plain/text', :disposition => 'inline'
152 end
153
154 See the possible values for send_file for reference.
155
156
157 The second is when saving the file when submitted from a form.
158 Example in view:
159 <%= form.file_field :attachable, :uploaded_data %>
160
161 Example in controller:
162 def create
163 @attachable_file = AttachmentMetadataModel.new(params[:attachable])
164 if @attachable_file.save
165 flash[:notice] = 'Attachment was successfully created.'
166 redirect_to attachable_url(@attachable_file)
167 else
168 render :action => :new
169 end
170 end
b6211f21 »
2008-06-09 added docs on how to script an uploaded file
171
172 attachement_fu scripting
173 ====================================
174
175 You may wish to import a large number of images or attachments.
176 The following example shows how to upload a file from a script.
177
178 #!/usr/bin/env ./script/runner
179
180 # required to use ActionController::TestUploadedFile
181 require 'action_controller'
182 require 'action_controller/test_process.rb'
183
dfc4ada5 »
2008-06-09 Modified README to include information about 'uploading' files from a…
184 path = "./public/images/x.jpg"
b6211f21 »
2008-06-09 added docs on how to script an uploaded file
185
dfc4ada5 »
2008-06-09 Modified README to include information about 'uploading' files from a…
186 # mimetype is a string like "image/jpeg". One way to get the mimetype for a given file on a UNIX system
187 # mimetype = `file -ib #{path}`.gsub(/\n/,"")
b6211f21 »
2008-06-09 added docs on how to script an uploaded file
188
dfc4ada5 »
2008-06-09 Modified README to include information about 'uploading' files from a…
189 mimetype = "image/jpeg"
b6211f21 »
2008-06-09 added docs on how to script an uploaded file
190
dfc4ada5 »
2008-06-09 Modified README to include information about 'uploading' files from a…
191 # This will "upload" the file at path and create the new model.
192 @attachable = AttachmentMetadataModel.new(:uploaded_data => ActionController::TestUploadedFile.new(path, mimetype))
193 @attachable.save
Something went wrong with that request. Please try again.