pothoven-attachment_fu 3.2.8 → 3.2.9
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGELOG +6 -0
- data/README.rdoc +352 -0
- data/lib/technoweenie/attachment_fu/backends/s3_backend.rb +25 -9
- data/lib/technoweenie/attachment_fu.rb +8 -1
- metadata +4 -4
- data/README +0 -255
data/CHANGELOG
CHANGED
@@ -1,3 +1,9 @@
|
|
1
|
+
* Aug 21, 2013 *
|
2
|
+
* Added S3 :encrypted_storage option support from cschulte22
|
3
|
+
|
4
|
+
* Jul 5, 2013
|
5
|
+
* Pull in changes from lchimonji10 to reformat README to RDoc format
|
6
|
+
|
1
7
|
* Apr 10, 2013 *
|
2
8
|
* Ruby 2 compatibility fix
|
3
9
|
* Removed some lingering occurrences of RAILS_ROOT and RAILS_ENV
|
data/README.rdoc
ADDED
@@ -0,0 +1,352 @@
|
|
1
|
+
= attachment-fu
|
2
|
+
|
3
|
+
attachment_fu is a plugin by Rick Olson (aka technoweenie
|
4
|
+
http://techno-weenie.net) and is the successor to acts_as_attachment. To get a
|
5
|
+
basic run-through of its capabilities, check out {Mike Clark's
|
6
|
+
tutorial}[http://clarkware.com/cgi/blosxom/2007/02/24#FileUploadFu].
|
7
|
+
|
8
|
+
= attachment_fu functionality
|
9
|
+
|
10
|
+
attachment_fu facilitates file uploads in Ruby on Rails. There are a few
|
11
|
+
storage options for the actual file data, but the plugin always at a minimum
|
12
|
+
stores metadata for each file in the database.
|
13
|
+
|
14
|
+
There are four storage options for files uploaded through attachment_fu:
|
15
|
+
|
16
|
+
* File system
|
17
|
+
* Database file
|
18
|
+
* Amazon S3
|
19
|
+
* Rackspace (Mosso) Cloud Files
|
20
|
+
|
21
|
+
Each method of storage many options associated with it that will be covered in
|
22
|
+
the following section. Something to note, however, is that the Amazon S3 storage
|
23
|
+
requires you to modify +config/amazon_s3.yml+, the Rackspace Cloud Files storage
|
24
|
+
requires you to modify +config/rackspace_cloudfiles.yml+, and the Database file
|
25
|
+
storage requires an extra table.
|
26
|
+
|
27
|
+
= attachment_fu models
|
28
|
+
|
29
|
+
For all three of these storage options a table of metadata is required. This
|
30
|
+
table will contain information about the file (hence the 'meta') and its
|
31
|
+
location. This table has no restrictions on naming, unlike the extra table
|
32
|
+
required for database storage, which must have a table name of +db_files+ (and
|
33
|
+
by convention a model of +DbFile+).
|
34
|
+
|
35
|
+
Two methods are available to models: +has_attachment+ and
|
36
|
+
+validates_as_attachment+.
|
37
|
+
|
38
|
+
== has_attachment(options = {})
|
39
|
+
|
40
|
+
This method accepts the options in a hash:
|
41
|
+
|
42
|
+
[:content_type]
|
43
|
+
Allowed content types.
|
44
|
+
|
45
|
+
By default, all content types are allowed. Use +:image+ to allow all
|
46
|
+
standard image types.
|
47
|
+
|
48
|
+
[:min_size]
|
49
|
+
Minimum file size.
|
50
|
+
|
51
|
+
By default, set to +1.byte+.
|
52
|
+
|
53
|
+
[:max_size]
|
54
|
+
Maximum file size.
|
55
|
+
|
56
|
+
By default, set to +1.megabyte+.
|
57
|
+
|
58
|
+
[:size]
|
59
|
+
Minimum and maximum file size.
|
60
|
+
|
61
|
+
By default, set to +1..1.megabyte+. Overrides +:min_size+ and
|
62
|
+
+:max_size+.
|
63
|
+
|
64
|
+
[:resize_to]
|
65
|
+
Used by RMagick.
|
66
|
+
|
67
|
+
Tells RMagick how to resize images. Pass either an array specifying
|
68
|
+
width and height or a geometry string. Prefixing the geometry string
|
69
|
+
with a 'c' will crop the image to the specified size.
|
70
|
+
|
71
|
+
[:sharpen_on_resize]
|
72
|
+
Used by RMagick.
|
73
|
+
|
74
|
+
If set to true, images are sharpened after being resized.
|
75
|
+
|
76
|
+
[:thumbnails]
|
77
|
+
A set of thumbnails to generate.
|
78
|
+
|
79
|
+
This accepts a hash of filename suffixes and RMagick resizing options. This
|
80
|
+
option need only be included if you want thumbnailing.
|
81
|
+
|
82
|
+
If you have a polymorphic parent relationship, you can provide
|
83
|
+
parent-type-specific thumbnail settings by using a pair with the type string
|
84
|
+
as key and a Hash of thumbnail definitions, or a method symbol, as value.
|
85
|
+
The method symbol will call the named method in order to get a
|
86
|
+
dynamically-built Hash of thumbnail definitions, which gives you full
|
87
|
+
flexibility. AttachmentFu automatically detects your first polymorphic
|
88
|
+
+belongs_to+ relationship.
|
89
|
+
|
90
|
+
[:thumbnail_class]
|
91
|
+
Which model class to use for thumbnails.
|
92
|
+
|
93
|
+
By default, the current attachment class is used.
|
94
|
+
|
95
|
+
[:jpeg_quality]
|
96
|
+
JPEG quality settings for thumbnail resizes.
|
97
|
+
|
98
|
+
Arguments can be in multiple formats:
|
99
|
+
|
100
|
+
* Integer from 0 (basically crap) to 100 (basically lossless, fat files).
|
101
|
+
|
102
|
+
* When relying on tdd-image_science, you can also use one of its +JPEG_xxx+
|
103
|
+
constants for predefined ratios/settings.
|
104
|
+
|
105
|
+
* You can also use a Hash, with keys being either thumbnail symbols (I
|
106
|
+
repeat: _symbols_) or surface boundaries. A surface boundary is a string
|
107
|
+
starting with either '<' or '>=', followed by a number of pixels. This
|
108
|
+
lets you specify per-thumbnail or per-general-thumbnail-"size" JPEG
|
109
|
+
qualities. (which can be useful when you have a _lot_ of thumbnail
|
110
|
+
options). Surface example: <code>{'<2000' => 90, '>=2000' => 75}</code>.
|
111
|
+
|
112
|
+
Defaults vary depending on the processor (ImageScience: 100%,
|
113
|
+
Rmagick/MiniMagick/Gd2: 75%, CoreImage: auto-adjust). Note that only
|
114
|
+
tdd-image_science (available from GitHub) currently supports explicit JPEG
|
115
|
+
quality; the default image_science currently forces 100%.
|
116
|
+
|
117
|
+
[:path_prefix]
|
118
|
+
Path to store the uploaded files in. Uses <code>public/#{table_name}</code>
|
119
|
+
by default for the filesystem, and just <code>#{table_name}</code> for the
|
120
|
+
S3 and Cloud Files backend. Setting this sets the +:storage+ to
|
121
|
+
+:file_system+.
|
122
|
+
|
123
|
+
[:partition]
|
124
|
+
Whether to partiton files in directories like +/0000/0001/image.jpg+.
|
125
|
+
Default is true. Only applicable to the +:file_system+ backend.
|
126
|
+
|
127
|
+
[:storage]
|
128
|
+
Specifies the storage system to use. Defaults to +:db_file+. Options are
|
129
|
+
+:file_system+, +:db_file+, +:s3+, and +:cloud_files+.
|
130
|
+
|
131
|
+
[:cloudfront]
|
132
|
+
If using S3 for storage, this option allows for serving the files via Amazon
|
133
|
+
CloudFront. Defaults to false.
|
134
|
+
|
135
|
+
[:processor]
|
136
|
+
Sets the image processor to use for resizing of the attached image. Options
|
137
|
+
include ImageScience, Rmagick, MiniMagick, Gd2 and CoreImage. Default is
|
138
|
+
whatever is installed.
|
139
|
+
|
140
|
+
[:uuid_primary_key]
|
141
|
+
If your model's primary key is a 128-bit UUID in hexadecimal format, then
|
142
|
+
set this to true.
|
143
|
+
|
144
|
+
[:association_options]
|
145
|
+
attachment_fu automatically defines associations with thumbnails with
|
146
|
+
+has_many+ and +belongs_to+. If there are any additional options that you
|
147
|
+
want to pass to these methods, then specify them here.
|
148
|
+
|
149
|
+
Examples:
|
150
|
+
|
151
|
+
has_attachment(content_type: 'application/pdf')
|
152
|
+
has_attachment(
|
153
|
+
content_type: ['application/pdf', 'application/msword', 'text/plain']
|
154
|
+
)
|
155
|
+
has_attachment(content_type: ['application/pdf', :image], resize_to: 'x50')
|
156
|
+
has_attachment(content_type: :image, resize_to: [50,50])
|
157
|
+
has_attachment(max_size: 1.kilobyte)
|
158
|
+
has_attachment(size: 1.megabyte..2.megabytes)
|
159
|
+
has_attachment(storage: :cloud_files)
|
160
|
+
has_attachment(storage: :file_system, path_prefix: 'public/files')
|
161
|
+
has_attachment(
|
162
|
+
storage: :file_system,
|
163
|
+
path_prefix: 'public/files',
|
164
|
+
content_type: :image,
|
165
|
+
resize_to: [50, 50],
|
166
|
+
partition: false
|
167
|
+
)
|
168
|
+
has_attachment(
|
169
|
+
storage: :file_system,
|
170
|
+
path_prefix: 'public/files',
|
171
|
+
thumbnails: {thumb: [50, 50], geometry: 'x50'}
|
172
|
+
)
|
173
|
+
has_attachment(storage: :s3)
|
174
|
+
has_attachment(store: :s3, cloudfront: true)
|
175
|
+
has_attachment(thumbnails: {thumb: [50, 50], geometry: 'x50'})
|
176
|
+
|
177
|
+
# Let's say we have a polymorphic belongs_to, e.g. called 'imageable', where
|
178
|
+
# imageable_type (or whatever the :foreign_type option was set to) can be,
|
179
|
+
# among other things, 'Product', 'User' or 'Editorial', each of which should
|
180
|
+
# have extra thumbnails:
|
181
|
+
|
182
|
+
has_attachment(thumbnails: {
|
183
|
+
editorials: {fullsize: '150x100>'},
|
184
|
+
geometry: 'x50',
|
185
|
+
products: {large_thumb: '169x169!', zoomed: '500x500>'},
|
186
|
+
thumb: [50, 50],
|
187
|
+
users: {avatar: '64x64!'}
|
188
|
+
})
|
189
|
+
|
190
|
+
# JPEG qualities…
|
191
|
+
|
192
|
+
has_attachment(jpeg_quality: 75)
|
193
|
+
has_attachment(jpeg_quality: 80 | ImageScience::JPEG_PROGRESSIVE)
|
194
|
+
has_attachment(
|
195
|
+
thumbnails: {thumb: [50, 50], geometry: 'x50'},
|
196
|
+
jpeg_quality: {'<2000' => 90, '>=2000' => 75}
|
197
|
+
)
|
198
|
+
has_attachment(
|
199
|
+
thumbnails: {thumb: [50, 50], geometry: 'x50'},
|
200
|
+
jpeg_quality: {nil => 75, thumb: 90, geometry: 90}
|
201
|
+
)
|
202
|
+
|
203
|
+
== validates_as_attachment
|
204
|
+
|
205
|
+
This method prevents files outside of the valid range (+:min_size+ to
|
206
|
+
+:max_size+, or the +:size+ range) from being saved. It does not however, halt
|
207
|
+
the upload of such files. They will be uploaded into memory regardless of size
|
208
|
+
before validation.
|
209
|
+
|
210
|
+
To perform this validation, simply add +validates_as_attachment+ to your model.
|
211
|
+
|
212
|
+
= attachment_fu migrations
|
213
|
+
|
214
|
+
Fields for attachment_fu metadata tables…
|
215
|
+
|
216
|
+
In general:
|
217
|
+
|
218
|
+
size, :integer # file size in bytes
|
219
|
+
content_type, :string # mime type, ex: application/mp3
|
220
|
+
filename, :string # sanitized filename
|
221
|
+
|
222
|
+
That reference images:
|
223
|
+
|
224
|
+
height, :integer # in pixels
|
225
|
+
width, :integer # in pixels
|
226
|
+
|
227
|
+
That reference images that will be thumbnailed:
|
228
|
+
|
229
|
+
parent_id, :integer # id of parent image (on the same table, a
|
230
|
+
# self-referencing foreign-key). Only populated if
|
231
|
+
# the current object is a thumbnail.
|
232
|
+
thumbnail, :string # The type of thumbnail this attachment record
|
233
|
+
# describes. Only populated if the current object is
|
234
|
+
# a thumbnail. Example:
|
235
|
+
#
|
236
|
+
# (In Model 'Avatar')
|
237
|
+
# has_attachment(
|
238
|
+
# :content_type => :image,
|
239
|
+
# :storage => :file_system,
|
240
|
+
# :max_size => 500.kilobytes,
|
241
|
+
# :resize_to => '320x200>',
|
242
|
+
# :thumbnails => {
|
243
|
+
# :small => '10x10>',
|
244
|
+
# :thumb => '100x100>'
|
245
|
+
# }
|
246
|
+
# )
|
247
|
+
#
|
248
|
+
# (Elsewhere)
|
249
|
+
# @user.avatar.thumbnails.first.thumbnail # => 'small'
|
250
|
+
#
|
251
|
+
db_file_id, :integer # ID of the file in the database (foreign key) that
|
252
|
+
# reference files stored in the database (:db_file).
|
253
|
+
|
254
|
+
Field for attachment_fu +db_files+ table:
|
255
|
+
|
256
|
+
data, :binary # binary file data, for use in database file storage
|
257
|
+
|
258
|
+
= attachment_fu views
|
259
|
+
|
260
|
+
There are two main views tasks that will be directly affected by attachment_fu:
|
261
|
+
upload forms and displaying uploaded images.
|
262
|
+
|
263
|
+
There are two parts of the upload form that differ from typical usage.
|
264
|
+
|
265
|
+
1. Include <code>multipart: true</code> in the html options of the +form_for+
|
266
|
+
tag. Example:
|
267
|
+
|
268
|
+
<%=
|
269
|
+
form_for(
|
270
|
+
:attachment_metadata,
|
271
|
+
url: {action: "create"},
|
272
|
+
html: {multipart: true}
|
273
|
+
) do |form|
|
274
|
+
%>
|
275
|
+
|
276
|
+
2. Use the +file_field+ helper with +:uploaded_data+ as the field name. Example:
|
277
|
+
|
278
|
+
<%= form.file_field(:uploaded_data) %>
|
279
|
+
|
280
|
+
Displaying uploaded images is made easy by the +public_filename+ method of the
|
281
|
+
ActiveRecord attachment objects using file system, s3, and Cloud Files storage.
|
282
|
+
|
283
|
+
== public_filename(thumbnail = nil)
|
284
|
+
|
285
|
+
Returns the public path to the file. If a thumbnail prefix is specified it will
|
286
|
+
return the public file path to the corresponding thumbnail. Examples:
|
287
|
+
|
288
|
+
attachment_obj.public_filename #=> /attachments/2/file.jpg
|
289
|
+
attachment_obj.public_filename(:thumb) #=> /attachments/2/file_thumb.jpg
|
290
|
+
attachment_obj.public_filename(:small) #=> /attachments/2/file_small.jpg
|
291
|
+
|
292
|
+
When serving files from database storage, doing more than simply downloading the
|
293
|
+
file is beyond the scope of this document.
|
294
|
+
|
295
|
+
= attachment_fu controllers
|
296
|
+
|
297
|
+
There are two considerations to take into account when using attachment_fu in
|
298
|
+
controllers.
|
299
|
+
|
300
|
+
The first is when the files have no publicly accessible path and need to be
|
301
|
+
downloaded through an action. Example:
|
302
|
+
|
303
|
+
def readme
|
304
|
+
send_file(
|
305
|
+
'/path/to/readme.txt',
|
306
|
+
type: 'plain/text',
|
307
|
+
disposition: 'inline'
|
308
|
+
)
|
309
|
+
end
|
310
|
+
|
311
|
+
See the possible values for +send_file+ for reference.
|
312
|
+
|
313
|
+
The second is when saving the file when submitted from a form. Example:
|
314
|
+
|
315
|
+
In a view:
|
316
|
+
|
317
|
+
<%= form.file_field(:attachable, :uploaded_data) %>
|
318
|
+
|
319
|
+
In a controller:
|
320
|
+
|
321
|
+
def create
|
322
|
+
@attachable_file = AttachmentMetadataModel.new(params[:attachable])
|
323
|
+
if @attachable_file.save
|
324
|
+
flash[:notice] = 'Attachment was successfully created.'
|
325
|
+
redirect_to(attachable_url(@attachable_file))
|
326
|
+
else
|
327
|
+
redirect_to(action: 'new')
|
328
|
+
end
|
329
|
+
end
|
330
|
+
|
331
|
+
= attachment_fu scripting
|
332
|
+
|
333
|
+
You may wish to import a large number of images or attachments. The following
|
334
|
+
example shows how to upload a file from a script.
|
335
|
+
|
336
|
+
#!/usr/bin/env ./script/runner
|
337
|
+
|
338
|
+
# required to use ActionController::TestUploadedFile
|
339
|
+
require 'action_controller'
|
340
|
+
require 'action_controller/test_process.rb'
|
341
|
+
|
342
|
+
path = "./public/images/x.jpg"
|
343
|
+
|
344
|
+
# `mimetype` is a string like "image/jpeg". One way to get the mimetype for
|
345
|
+
# a given file on a UNIX system: mimetype = `file -ib #{path}`.gsub(/\n/,"")
|
346
|
+
mimetype = "image/jpeg"
|
347
|
+
|
348
|
+
# This will "upload" the file at path and create the new model.
|
349
|
+
@attachable = AttachmentMetadataModel.new(
|
350
|
+
uploaded_data: ActionController::TestUploadedFile.new(path, mimetype)
|
351
|
+
)
|
352
|
+
@attachable.save
|
@@ -183,7 +183,7 @@ module Technoweenie # :nodoc:
|
|
183
183
|
end
|
184
184
|
|
185
185
|
begin
|
186
|
-
@@s3_config_path = base.attachment_options[:s3_config_path] || (Rails.root
|
186
|
+
@@s3_config_path = base.attachment_options[:s3_config_path] || File.join(Rails.root, 'config', 'amazon_s3.yml')
|
187
187
|
@@s3_config = @@s3_config = YAML.load(ERB.new(File.read(@@s3_config_path)).result)[Rails.env].symbolize_keys
|
188
188
|
#rescue
|
189
189
|
# raise ConfigFileNotFoundError.new('File %s not found' % @@s3_config_path)
|
@@ -333,7 +333,11 @@ module Technoweenie # :nodoc:
|
|
333
333
|
end
|
334
334
|
|
335
335
|
def current_data
|
336
|
-
|
336
|
+
if attachment_options[:encrypted_storage] && self.respond_to?(:encryption_key) && self.encryption_key != nil
|
337
|
+
EncryptedData.decrypt_data(S3Object.value(full_filename, bucket_name), self.encryption_key)
|
338
|
+
else
|
339
|
+
S3Object.value full_filename, bucket_name
|
340
|
+
end
|
337
341
|
end
|
338
342
|
|
339
343
|
def s3_protocol
|
@@ -376,13 +380,25 @@ module Technoweenie # :nodoc:
|
|
376
380
|
|
377
381
|
def save_to_storage
|
378
382
|
if save_attachment?
|
379
|
-
|
380
|
-
|
381
|
-
|
382
|
-
|
383
|
-
|
384
|
-
|
385
|
-
|
383
|
+
if attachment_options[:encrypted_storage]
|
384
|
+
S3Object.store(
|
385
|
+
full_filename,
|
386
|
+
(temp_path ? File.open(temp_path) : temp_data),
|
387
|
+
bucket_name,
|
388
|
+
:content_type => content_type,
|
389
|
+
:access => attachment_options[:s3_access],
|
390
|
+
'x-amz-server-side-encryption' => 'AES256',
|
391
|
+
'Content-Disposition' => "attachment; filename=\"#{filename}\""
|
392
|
+
)
|
393
|
+
else
|
394
|
+
S3Object.store(
|
395
|
+
full_filename,
|
396
|
+
(temp_path ? File.open(temp_path) : temp_data),
|
397
|
+
bucket_name,
|
398
|
+
:content_type => content_type,
|
399
|
+
:access => attachment_options[:s3_access]
|
400
|
+
)
|
401
|
+
end
|
386
402
|
end
|
387
403
|
|
388
404
|
@old_filename = nil
|
@@ -296,7 +296,14 @@ module Technoweenie # :nodoc:
|
|
296
296
|
|
297
297
|
# Gets the thumbnail name for a filename. 'foo.jpg' becomes 'foo_thumbnail.jpg'
|
298
298
|
def thumbnail_name_for(thumbnail = nil)
|
299
|
-
|
299
|
+
if thumbnail.blank?
|
300
|
+
if filename.nil?
|
301
|
+
return ''
|
302
|
+
else
|
303
|
+
return filename
|
304
|
+
end
|
305
|
+
end
|
306
|
+
|
300
307
|
ext = nil
|
301
308
|
basename = filename.gsub /\.\w+$/ do |s|
|
302
309
|
ext = s; ''
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: pothoven-attachment_fu
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 3.2.
|
4
|
+
version: 3.2.9
|
5
5
|
prerelease:
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
@@ -10,7 +10,7 @@ authors:
|
|
10
10
|
autorequire:
|
11
11
|
bindir: bin
|
12
12
|
cert_chain: []
|
13
|
-
date: 2013-
|
13
|
+
date: 2013-08-21 00:00:00.000000000 Z
|
14
14
|
dependencies: []
|
15
15
|
description: This is a fork of Rick Olson's attachment_fu adding Ruby 1.9 and Rails
|
16
16
|
3.2 support as well as some other enhancements.
|
@@ -18,7 +18,7 @@ email: steven@pothoven.net
|
|
18
18
|
executables: []
|
19
19
|
extensions: []
|
20
20
|
extra_rdoc_files:
|
21
|
-
- README
|
21
|
+
- README.rdoc
|
22
22
|
files:
|
23
23
|
- lib/geometry.rb
|
24
24
|
- lib/pothoven-attachment_fu.rb
|
@@ -41,7 +41,7 @@ files:
|
|
41
41
|
- vendor/red_artisan/core_image/filters/perspective.rb
|
42
42
|
- CHANGELOG
|
43
43
|
- LICENSE
|
44
|
-
- README
|
44
|
+
- README.rdoc
|
45
45
|
- amazon_s3.yml.tpl
|
46
46
|
- rackspace_cloudfiles.yml.tpl
|
47
47
|
homepage: http://github.com/pothoven/attachment_fu
|
data/README
DELETED
@@ -1,255 +0,0 @@
|
|
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 four storage options for files uploaded through attachment_fu:
|
13
|
-
File system
|
14
|
-
Database file
|
15
|
-
Amazon S3
|
16
|
-
Rackspace (Mosso) Cloud Files
|
17
|
-
|
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.
|
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
|
-
#
|
33
|
-
:min_size # Minimum size allowed.
|
34
|
-
# 1 byte is the default.
|
35
|
-
#
|
36
|
-
:max_size # Maximum size allowed.
|
37
|
-
# 1.megabyte is the default.
|
38
|
-
#
|
39
|
-
:size # Range of sizes allowed.
|
40
|
-
# (1..1.megabyte) is the default. This overrides the :min_size and :max_size options.
|
41
|
-
#
|
42
|
-
:resize_to # Used by RMagick to resize images.
|
43
|
-
# Pass either an array of width/height, or a geometry string.
|
44
|
-
# Note: prefixing geometry string with a 'c' will crop the image to specified size.
|
45
|
-
#
|
46
|
-
:sharpen_on_resize # RMagick only. Sharpens image after it is resized if this is set to true.
|
47
|
-
:thumbnails # Specifies a set of thumbnails to generate.
|
48
|
-
# This accepts a hash of filename suffixes and RMagick resizing options.
|
49
|
-
# This option need only be included if you want thumbnailing.
|
50
|
-
# If you have a polymorphic parent relationship, you can provide parent-type-specific
|
51
|
-
# thumbnail settings by using a pair with the type string as key and a Hash of thumbnail
|
52
|
-
# definitions, or a method symbol, as value. The method symbol will call the named
|
53
|
-
# method in order to get a dynamically-built Hash of thumbnail definitions, which gives
|
54
|
-
# you full flexibility.
|
55
|
-
# AttachmentFu automatically detects your first polymorphic +belongs_to+ relationship.
|
56
|
-
#
|
57
|
-
:thumbnail_class # Set which model class to use for thumbnails.
|
58
|
-
# This current attachment class is used by default.
|
59
|
-
#
|
60
|
-
:jpeg_quality # Used to provide explicit JPEG quality for thumbnail/resize saves. Can have multiple
|
61
|
-
# formats:
|
62
|
-
# * Integer from 0 (basically crap) to 100 (basically lossless, fat files).
|
63
|
-
# * When relying on tdd-image_science, you can also use one of its +JPEG_xxx+ constants
|
64
|
-
# for predefined ratios/settings.
|
65
|
-
# * You can also use a Hash, with keys being either thumbnail symbols (I repeat:
|
66
|
-
# _symbols_) or surface boundaries. A surface boundary is a string starting with either
|
67
|
-
# '<' or '>=', followed by a number of pixels. This lets you specify per-thumbnail or
|
68
|
-
# per-general-thumbnail-"size" JPEG qualities. (which can be useful when you have a
|
69
|
-
# _lot_ of thumbnail options). Surface example: +{ '<2000' => 90, '>=2000' => 75 }+.
|
70
|
-
#
|
71
|
-
# Defaults vary depending on the processor (ImageScience: 100%,
|
72
|
-
# Rmagick/MiniMagick/Gd2: 75%, CoreImage: auto-adjust).
|
73
|
-
# Note that only tdd-image_science (available from GitHub) currently supports explicit
|
74
|
-
# JPEG quality; the default image_science currently forces 100%.
|
75
|
-
#
|
76
|
-
:path_prefix # Path to store the uploaded files in.
|
77
|
-
# Uses public/#{table_name} by default for the filesystem, and just #{table_name} for the
|
78
|
-
# S3 and Cloud Files backend.
|
79
|
-
# Setting this sets the :storage to :file_system.
|
80
|
-
#
|
81
|
-
:partition # Whether to partiton files in directories like /0000/0001/image.jpg. Default is true.
|
82
|
-
# Only applicable to the :file_system backend.
|
83
|
-
#
|
84
|
-
:storage # Specifies the storage system to use..
|
85
|
-
# Defaults to :db_file. Options are :file_system, :db_file, :s3, and :cloud_files.
|
86
|
-
#
|
87
|
-
:cloudfront # If using S3 for storage, this option allows for serving the files via Amazon CloudFront.
|
88
|
-
# Defaults to false.
|
89
|
-
#
|
90
|
-
:processor # Sets the image processor to use for resizing of the attached image.
|
91
|
-
# Options include ImageScience, Rmagick, MiniMagick, Gd2 and CoreImage. Default is
|
92
|
-
# whatever is installed.
|
93
|
-
#
|
94
|
-
:uuid_primary_key # If your model's primary key is a 128-bit UUID in hexadecimal format, then set this to
|
95
|
-
# true.
|
96
|
-
#
|
97
|
-
:association_options # attachment_fu automatically defines associations with thumbnails with has_many and
|
98
|
-
# belongs_to. If there are any additional options that you want to pass to these methods,
|
99
|
-
# then specify them here.
|
100
|
-
|
101
|
-
|
102
|
-
Examples:
|
103
|
-
has_attachment :max_size => 1.kilobyte
|
104
|
-
has_attachment :size => 1.megabyte..2.megabytes
|
105
|
-
has_attachment :content_type => 'application/pdf'
|
106
|
-
has_attachment :content_type => ['application/pdf', 'application/msword', 'text/plain']
|
107
|
-
has_attachment :content_type => :image, :resize_to => [50,50]
|
108
|
-
has_attachment :content_type => ['application/pdf', :image], :resize_to => 'x50'
|
109
|
-
has_attachment :thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
|
110
|
-
has_attachment :storage => :file_system, :path_prefix => 'public/files'
|
111
|
-
has_attachment :storage => :file_system, :path_prefix => 'public/files',
|
112
|
-
:content_type => :image, :resize_to => [50,50], :partition => false
|
113
|
-
has_attachment :storage => :file_system, :path_prefix => 'public/files',
|
114
|
-
:thumbnails => { :thumb => [50, 50], :geometry => 'x50' }
|
115
|
-
has_attachment :storage => :s3
|
116
|
-
has_attachment :store => :s3, :cloudfront => true
|
117
|
-
has_attachment :storage => :cloud_files
|
118
|
-
|
119
|
-
# Let's say we have a polymorphic belongs_to, e.g. called 'imageable', where imageable_type (or whatever the
|
120
|
-
# :foreign_type option was set to) can be, among other things, 'Product', 'User' or 'Editorial', each of which
|
121
|
-
# should have extra thumbnails:
|
122
|
-
|
123
|
-
has_attachment :thumbnails => { :thumb => [50, 50], :geometry => 'x50',
|
124
|
-
:products => { :large_thumb => '169x169!', :zoomed => '500x500>' },
|
125
|
-
:editorials => { :fullsize => '150x100>' },
|
126
|
-
:users => { :avatar => '64x64!' } }
|
127
|
-
|
128
|
-
# JPEG qualities…
|
129
|
-
|
130
|
-
has_attachment :jpeg_quality => 75
|
131
|
-
has_attachment :jpeg_quality => 80 | ImageScience::JPEG_PROGRESSIVE
|
132
|
-
has_attachment :thumbnails => { :thumb => [50, 50], :geometry => 'x50' },
|
133
|
-
:jpeg_quality => { nil => 75, :thumb => 90, :geometry => 90 }
|
134
|
-
has_attachment :thumbnails => { :thumb => [50, 50], :geometry => 'x50' },
|
135
|
-
:jpeg_quality => { '<2000' => 90, '>=2000' => 75 }
|
136
|
-
}
|
137
|
-
|
138
|
-
validates_as_attachment
|
139
|
-
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.
|
140
|
-
|
141
|
-
Example:
|
142
|
-
validates_as_attachment
|
143
|
-
|
144
|
-
|
145
|
-
attachment_fu migrations
|
146
|
-
========================
|
147
|
-
|
148
|
-
Fields for attachment_fu metadata tables...
|
149
|
-
in general:
|
150
|
-
size, :integer # file size in bytes
|
151
|
-
content_type, :string # mime type, ex: application/mp3
|
152
|
-
filename, :string # sanitized filename
|
153
|
-
that reference images:
|
154
|
-
height, :integer # in pixels
|
155
|
-
width, :integer # in pixels
|
156
|
-
that reference images that will be thumbnailed:
|
157
|
-
parent_id, :integer # id of parent image (on the same table, a self-referencing foreign-key).
|
158
|
-
# Only populated if the current object is a thumbnail.
|
159
|
-
thumbnail, :string # the 'type' of thumbnail this attachment record describes.
|
160
|
-
# Only populated if the current object is a thumbnail.
|
161
|
-
# Usage:
|
162
|
-
# [ In Model 'Avatar' ]
|
163
|
-
# has_attachment :content_type => :image,
|
164
|
-
# :storage => :file_system,
|
165
|
-
# :max_size => 500.kilobytes,
|
166
|
-
# :resize_to => '320x200>',
|
167
|
-
# :thumbnails => { :small => '10x10>',
|
168
|
-
# :thumb => '100x100>' }
|
169
|
-
# [ Elsewhere ]
|
170
|
-
# @user.avatar.thumbnails.first.thumbnail #=> 'small'
|
171
|
-
that reference files stored in the database (:db_file):
|
172
|
-
db_file_id, :integer # id of the file in the database (foreign key)
|
173
|
-
|
174
|
-
Field for attachment_fu db_files table:
|
175
|
-
data, :binary # binary file data, for use in database file storage
|
176
|
-
|
177
|
-
|
178
|
-
attachment_fu views
|
179
|
-
===================
|
180
|
-
|
181
|
-
There are two main views tasks that will be directly affected by attachment_fu: upload forms and displaying uploaded images.
|
182
|
-
|
183
|
-
There are two parts of the upload form that differ from typical usage.
|
184
|
-
1. Include ':multipart => true' in the html options of the form_for tag.
|
185
|
-
Example:
|
186
|
-
<% form_for(:attachment_metadata, :url => { :action => "create" }, :html => { :multipart => true }) do |form| %>
|
187
|
-
|
188
|
-
2. Use the file_field helper with :uploaded_data as the field name.
|
189
|
-
Example:
|
190
|
-
<%= form.file_field :uploaded_data %>
|
191
|
-
|
192
|
-
Displaying uploaded images is made easy by the public_filename method of the ActiveRecord attachment objects using file system, s3, and Cloud Files storage.
|
193
|
-
|
194
|
-
public_filename(thumbnail = nil)
|
195
|
-
Returns the public path to the file. If a thumbnail prefix is specified it will return the public file path to the corresponding thumbnail.
|
196
|
-
Examples:
|
197
|
-
attachment_obj.public_filename #=> /attachments/2/file.jpg
|
198
|
-
attachment_obj.public_filename(:thumb) #=> /attachments/2/file_thumb.jpg
|
199
|
-
attachment_obj.public_filename(:small) #=> /attachments/2/file_small.jpg
|
200
|
-
|
201
|
-
When serving files from database storage, doing more than simply downloading the file is beyond the scope of this document.
|
202
|
-
|
203
|
-
|
204
|
-
attachment_fu controllers
|
205
|
-
=========================
|
206
|
-
|
207
|
-
There are two considerations to take into account when using attachment_fu in controllers.
|
208
|
-
|
209
|
-
The first is when the files have no publicly accessible path and need to be downloaded through an action.
|
210
|
-
|
211
|
-
Example:
|
212
|
-
def readme
|
213
|
-
send_file '/path/to/readme.txt', :type => 'plain/text', :disposition => 'inline'
|
214
|
-
end
|
215
|
-
|
216
|
-
See the possible values for send_file for reference.
|
217
|
-
|
218
|
-
|
219
|
-
The second is when saving the file when submitted from a form.
|
220
|
-
Example in view:
|
221
|
-
<%= form.file_field :attachable, :uploaded_data %>
|
222
|
-
|
223
|
-
Example in controller:
|
224
|
-
def create
|
225
|
-
@attachable_file = AttachmentMetadataModel.new(params[:attachable])
|
226
|
-
if @attachable_file.save
|
227
|
-
flash[:notice] = 'Attachment was successfully created.'
|
228
|
-
redirect_to attachable_url(@attachable_file)
|
229
|
-
else
|
230
|
-
render :action => :new
|
231
|
-
end
|
232
|
-
end
|
233
|
-
|
234
|
-
attachement_fu scripting
|
235
|
-
====================================
|
236
|
-
|
237
|
-
You may wish to import a large number of images or attachments.
|
238
|
-
The following example shows how to upload a file from a script.
|
239
|
-
|
240
|
-
#!/usr/bin/env ./script/runner
|
241
|
-
|
242
|
-
# required to use ActionController::TestUploadedFile
|
243
|
-
require 'action_controller'
|
244
|
-
require 'action_controller/test_process.rb'
|
245
|
-
|
246
|
-
path = "./public/images/x.jpg"
|
247
|
-
|
248
|
-
# mimetype is a string like "image/jpeg". One way to get the mimetype for a given file on a UNIX system
|
249
|
-
# mimetype = `file -ib #{path}`.gsub(/\n/,"")
|
250
|
-
|
251
|
-
mimetype = "image/jpeg"
|
252
|
-
|
253
|
-
# This will "upload" the file at path and create the new model.
|
254
|
-
@attachable = AttachmentMetadataModel.new(:uploaded_data => ActionController::TestUploadedFile.new(path, mimetype))
|
255
|
-
@attachable.save
|