dsturnbull-carrierwave 0.4.5
Sign up to get free protection for your applications and to get access to all the features.
- data/Generators +4 -0
- data/History.txt +118 -0
- data/Manifest.txt +107 -0
- data/README.rdoc +502 -0
- data/Rakefile +38 -0
- data/cucumber.yml +2 -0
- data/features/caching.feature +28 -0
- data/features/download.feature +20 -0
- data/features/file_storage.feature +37 -0
- data/features/file_storage_overridden_filename.feature +38 -0
- data/features/file_storage_overridden_store_dir.feature +38 -0
- data/features/file_storage_reversing_processor.feature +43 -0
- data/features/fixtures/bork.txt +1 -0
- data/features/fixtures/monkey.txt +1 -0
- data/features/grid_fs_storage.feature +32 -0
- data/features/mount_activerecord.feature +46 -0
- data/features/mount_datamapper.feature +46 -0
- data/features/step_definitions/activerecord_steps.rb +22 -0
- data/features/step_definitions/caching_steps.rb +14 -0
- data/features/step_definitions/datamapper_steps.rb +29 -0
- data/features/step_definitions/download_steps.rb +4 -0
- data/features/step_definitions/file_steps.rb +53 -0
- data/features/step_definitions/general_steps.rb +85 -0
- data/features/step_definitions/mount_steps.rb +19 -0
- data/features/step_definitions/store_steps.rb +18 -0
- data/features/support/activerecord.rb +30 -0
- data/features/support/datamapper.rb +7 -0
- data/features/support/env.rb +22 -0
- data/features/versions_basics.feature +50 -0
- data/features/versions_nested_versions.feature +70 -0
- data/features/versions_overridden_filename.feature +51 -0
- data/features/versions_overriden_store_dir.feature +41 -0
- data/lib/carrierwave/compatibility/paperclip.rb +95 -0
- data/lib/carrierwave/core_ext/blank.rb +46 -0
- data/lib/carrierwave/core_ext/inheritable_attributes.rb +104 -0
- data/lib/carrierwave/core_ext/module_setup.rb +51 -0
- data/lib/carrierwave/mount.rb +359 -0
- data/lib/carrierwave/orm/activerecord.rb +73 -0
- data/lib/carrierwave/orm/datamapper.rb +27 -0
- data/lib/carrierwave/orm/mongoid.rb +23 -0
- data/lib/carrierwave/orm/mongomapper.rb +27 -0
- data/lib/carrierwave/orm/sequel.rb +45 -0
- data/lib/carrierwave/processing/image_science.rb +101 -0
- data/lib/carrierwave/processing/mini_magick.rb +269 -0
- data/lib/carrierwave/processing/rmagick.rb +282 -0
- data/lib/carrierwave/sanitized_file.rb +268 -0
- data/lib/carrierwave/storage/abstract.rb +30 -0
- data/lib/carrierwave/storage/file.rb +48 -0
- data/lib/carrierwave/storage/grid_fs.rb +96 -0
- data/lib/carrierwave/storage/right_s3.rb +170 -0
- data/lib/carrierwave/storage/s3.rb +199 -0
- data/lib/carrierwave/test/matchers.rb +128 -0
- data/lib/carrierwave/uploader/cache.rb +145 -0
- data/lib/carrierwave/uploader/callbacks.rb +42 -0
- data/lib/carrierwave/uploader/configuration.rb +122 -0
- data/lib/carrierwave/uploader/default_url.rb +19 -0
- data/lib/carrierwave/uploader/download.rb +59 -0
- data/lib/carrierwave/uploader/extension_whitelist.rb +37 -0
- data/lib/carrierwave/uploader/mountable.rb +39 -0
- data/lib/carrierwave/uploader/processing.rb +83 -0
- data/lib/carrierwave/uploader/proxy.rb +62 -0
- data/lib/carrierwave/uploader/remove.rb +22 -0
- data/lib/carrierwave/uploader/store.rb +89 -0
- data/lib/carrierwave/uploader/url.rb +24 -0
- data/lib/carrierwave/uploader/versions.rb +146 -0
- data/lib/carrierwave/uploader.rb +44 -0
- data/lib/carrierwave.rb +96 -0
- data/merb_generators/uploader_generator.rb +22 -0
- data/rails_generators/uploader/USAGE +2 -0
- data/rails_generators/uploader/templates/uploader.rb +47 -0
- data/rails_generators/uploader/uploader_generator.rb +21 -0
- data/script/console +10 -0
- data/script/destroy +14 -0
- data/script/generate +14 -0
- data/spec/compatibility/paperclip_spec.rb +52 -0
- data/spec/fixtures/bork.txt +1 -0
- data/spec/fixtures/landscape.jpg +0 -0
- data/spec/fixtures/portrait.jpg +0 -0
- data/spec/fixtures/test.jpeg +1 -0
- data/spec/fixtures/test.jpg +1 -0
- data/spec/mount_spec.rb +538 -0
- data/spec/orm/activerecord_spec.rb +271 -0
- data/spec/orm/datamapper_spec.rb +168 -0
- data/spec/orm/mongoid_spec.rb +206 -0
- data/spec/orm/mongomapper_spec.rb +202 -0
- data/spec/orm/sequel_spec.rb +183 -0
- data/spec/processing/image_science_spec.rb +56 -0
- data/spec/processing/mini_magick_spec.rb +76 -0
- data/spec/processing/rmagick_spec.rb +75 -0
- data/spec/sanitized_file_spec.rb +601 -0
- data/spec/spec_helper.rb +99 -0
- data/spec/storage/grid_fs_spec.rb +82 -0
- data/spec/storage/right_s3_spec.rb +75 -0
- data/spec/storage/s3_spec.rb +95 -0
- data/spec/uploader/cache_spec.rb +209 -0
- data/spec/uploader/configuration_spec.rb +105 -0
- data/spec/uploader/default_url_spec.rb +85 -0
- data/spec/uploader/download_spec.rb +75 -0
- data/spec/uploader/extension_whitelist_spec.rb +44 -0
- data/spec/uploader/mountable_spec.rb +33 -0
- data/spec/uploader/paths_spec.rb +22 -0
- data/spec/uploader/processing_spec.rb +73 -0
- data/spec/uploader/proxy_spec.rb +54 -0
- data/spec/uploader/remove_spec.rb +70 -0
- data/spec/uploader/store_spec.rb +248 -0
- data/spec/uploader/url_spec.rb +87 -0
- data/spec/uploader/versions_spec.rb +298 -0
- metadata +351 -0
data/README.rdoc
ADDED
@@ -0,0 +1,502 @@
|
|
1
|
+
= CarrierWave
|
2
|
+
|
3
|
+
http://carrierwave.rubyforge.org
|
4
|
+
|
5
|
+
== Summary
|
6
|
+
|
7
|
+
This plugin for Merb and Rails provides a simple and extremely flexible way to
|
8
|
+
upload files.
|
9
|
+
|
10
|
+
== Description
|
11
|
+
|
12
|
+
* RDoc Documentation {available at Rubyforge}[http://carrierwave.rubyforge.org/rdoc].
|
13
|
+
* Source code {hosted at GitHub}[http://github.com/jnicklas/carrierwave]
|
14
|
+
* Please {report any issues}[http://github.com/jnicklas/carrierwave/issues] on GitHub
|
15
|
+
* Please direct any questions at the {mailing list}[http://groups.google.com/group/carrierwave]
|
16
|
+
* Check out the {example app}[http://github.com/jnicklas/carrierwave-example-app]
|
17
|
+
|
18
|
+
== Getting Started
|
19
|
+
|
20
|
+
Install the latest stable release:
|
21
|
+
|
22
|
+
[sudo] gem install carrierwave
|
23
|
+
|
24
|
+
In Merb, add it as a dependency to your config/dependencies.rb:
|
25
|
+
|
26
|
+
dependency 'carrierwave'
|
27
|
+
|
28
|
+
In Rails, add it to your environment.rb:
|
29
|
+
|
30
|
+
config.gem "carrierwave"
|
31
|
+
|
32
|
+
== Quick Start
|
33
|
+
|
34
|
+
Start off by generating an uploader:
|
35
|
+
|
36
|
+
merb-gen uploader Avatar
|
37
|
+
|
38
|
+
or in Rails:
|
39
|
+
|
40
|
+
script/generate uploader Avatar
|
41
|
+
|
42
|
+
this should give you a file in:
|
43
|
+
|
44
|
+
app/uploaders/avatar_uploader.rb
|
45
|
+
|
46
|
+
Check out this file for some hints on how you can customize your uploader. It
|
47
|
+
should look something like this:
|
48
|
+
|
49
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
50
|
+
storage :file
|
51
|
+
end
|
52
|
+
|
53
|
+
You can use your uploader class to store and retrieve files like this:
|
54
|
+
|
55
|
+
uploader = AvatarUploader.new
|
56
|
+
|
57
|
+
uploader.store!(my_file)
|
58
|
+
|
59
|
+
uploader.retrieve_from_store!('my_file.png')
|
60
|
+
|
61
|
+
CarrierWave gives you a +store+ for permanent storage, and a +cache+ for
|
62
|
+
temporary storage. You can use different stores, at the moment a filesystem
|
63
|
+
store, an Amazon S3 store and a store for MongoDB's GridFS are bundled.
|
64
|
+
|
65
|
+
Most of the time you are going to want to use CarrierWave together with an ORM.
|
66
|
+
It is quite simple to mount uploaders on columns in your model, so you can
|
67
|
+
simply assign files and get going:
|
68
|
+
|
69
|
+
=== ActiveRecord, DataMapper, Sequel, MongoMapper
|
70
|
+
|
71
|
+
Make sure you are loading CarrierWave after loading your ORM, otherwise you'll
|
72
|
+
need to require the relevant extension manually, e.g.:
|
73
|
+
|
74
|
+
require 'carrierwave/orm/activerecord'
|
75
|
+
|
76
|
+
Add a string column to the model you want to mount the uploader on:
|
77
|
+
|
78
|
+
add_column :user, :avatar, :string
|
79
|
+
|
80
|
+
Open your model file and mount the uploader:
|
81
|
+
|
82
|
+
class User
|
83
|
+
mount_uploader :avatar, AvatarUploader
|
84
|
+
end
|
85
|
+
|
86
|
+
This works the same with all supported ORMs.
|
87
|
+
|
88
|
+
Now you can cache files by assigning them to the attribute, they will
|
89
|
+
automatically be stored when the record is saved.
|
90
|
+
|
91
|
+
u = User.new
|
92
|
+
u.avatar = params[:file]
|
93
|
+
u.avatar = File.open('somewhere')
|
94
|
+
u.save!
|
95
|
+
u.avatar.url # => '/url/to/file.png'
|
96
|
+
u.avatar.current_path # => 'path/to/file.png'
|
97
|
+
|
98
|
+
== Changing the storage directory
|
99
|
+
|
100
|
+
In order to change where uploaded files are put, just override the +store_dir+
|
101
|
+
method:
|
102
|
+
|
103
|
+
class MyUploader < CarrierWave::Uploader::Base
|
104
|
+
def store_dir
|
105
|
+
'public/my/upload/directory'
|
106
|
+
end
|
107
|
+
end
|
108
|
+
|
109
|
+
This works for the file storage as well as Amazon S3.
|
110
|
+
|
111
|
+
== Securing uploads
|
112
|
+
|
113
|
+
Certain file might be dangerous if uploaded to the wrong location, such as php files or other script files. CarrierWave allows you to specify a white-list of allowed extensions.
|
114
|
+
|
115
|
+
If you're mounting the uploader, uploading a file with the wrong extension will make the record invalid instead. Otherwise, an error is raised.
|
116
|
+
|
117
|
+
class MyUploader < CarrierWave::Uploader::Base
|
118
|
+
def extension_white_list
|
119
|
+
%w(jpg jpeg gif png)
|
120
|
+
end
|
121
|
+
end
|
122
|
+
|
123
|
+
== Adding versions
|
124
|
+
|
125
|
+
Often you'll want to add different versions of the same file. The classic
|
126
|
+
example is image thumbnails. There is built in support for this:
|
127
|
+
|
128
|
+
class MyUploader < CarrierWave::Uploader::Base
|
129
|
+
include CarrierWave::RMagick
|
130
|
+
|
131
|
+
process :resize_to_fit => [800, 800]
|
132
|
+
|
133
|
+
version :thumb do
|
134
|
+
process :resize_to_fill => [200,200]
|
135
|
+
end
|
136
|
+
|
137
|
+
end
|
138
|
+
|
139
|
+
When this uploader is used, an uploaded image would be scaled to be no larger
|
140
|
+
than 800 by 800 pixels. A version called thumb is then created, which is scaled
|
141
|
+
and cropped to exactly 200 by 200 pixels. The uploader could be used like this:
|
142
|
+
|
143
|
+
uploader = AvatarUploader.new
|
144
|
+
uploader.store!(my_file) # size: 1024x768
|
145
|
+
|
146
|
+
uploader.url # => '/url/to/my_file.png' # size: 800x600
|
147
|
+
uploader.thumb.url # => '/url/to/thumb_my_file.png' # size: 200x200
|
148
|
+
|
149
|
+
One important thing to remember is that process is called *before* versions are
|
150
|
+
created. This can cut down on processing cost.
|
151
|
+
|
152
|
+
It is possible to nest versions within versions:
|
153
|
+
|
154
|
+
class MyUploader < CarrierWave::Uploader::Base
|
155
|
+
|
156
|
+
version :animal do
|
157
|
+
version :human
|
158
|
+
version :monkey
|
159
|
+
version :llama
|
160
|
+
end
|
161
|
+
end
|
162
|
+
|
163
|
+
== Making uploads work across form redisplays
|
164
|
+
|
165
|
+
Often you'll notice that uploaded files disappear when a validation fails.
|
166
|
+
CarrierWave has a feature that makes it easy to remember the uploaded file even
|
167
|
+
in that case. Suppose your +user+ model has an uploader mounted on +avatar+
|
168
|
+
file, just add a hidden field called +avatar_cache+. In Rails, this would look
|
169
|
+
like this:
|
170
|
+
|
171
|
+
<% form_for @user do |f| %>
|
172
|
+
<p>
|
173
|
+
<label>My Avatar</label>
|
174
|
+
<%= f.file_field :avatar %>
|
175
|
+
<%= f.hidden_field :avatar_cache %>
|
176
|
+
</p>
|
177
|
+
<% end %>
|
178
|
+
|
179
|
+
It might be a good idea to show the user that a file has been uploaded, in the
|
180
|
+
case of images, a small thumbnail would be a good indicator:
|
181
|
+
|
182
|
+
<% form_for @user do |f| %>
|
183
|
+
<p>
|
184
|
+
<label>My Avatar</label>
|
185
|
+
<%= image_tag(@user.avatar_url) if @user.avatar? %>
|
186
|
+
<%= f.file_field :avatar %>
|
187
|
+
<%= f.hidden_field :avatar_cache %>
|
188
|
+
</p>
|
189
|
+
<% end %>
|
190
|
+
|
191
|
+
== Removing uploaded files
|
192
|
+
|
193
|
+
If you want to remove a previously uploaded file on a mounted uploader, you can
|
194
|
+
easily add a checkbox to the form which will remove the file when checked.
|
195
|
+
|
196
|
+
<% form_for @user do |f| %>
|
197
|
+
<p>
|
198
|
+
<label>My Avatar</label>
|
199
|
+
<%= image_tag(@user.avatar_url) if @user.avatar? %>
|
200
|
+
<%= f.file_field :avatar %>
|
201
|
+
</p>
|
202
|
+
|
203
|
+
<p>
|
204
|
+
<label>
|
205
|
+
<%= f.check_box :remove_avatar %>
|
206
|
+
Remove avatar
|
207
|
+
</label>
|
208
|
+
</p>
|
209
|
+
<% end %>
|
210
|
+
|
211
|
+
If you want to remove the file manually, you can call <code>remove_avatar!</code>.
|
212
|
+
|
213
|
+
== Uploading files from a remote location
|
214
|
+
|
215
|
+
Your users may find it convenient to upload a file from a location on the Internet
|
216
|
+
via a URL. CarrierWave makes this simple, just add the appropriate column to your
|
217
|
+
form and you're good to go:
|
218
|
+
|
219
|
+
<% form_for @user do |f| %>
|
220
|
+
<p>
|
221
|
+
<label>My Avatar URL:</label>
|
222
|
+
<%= image_tag(@user.avatar_url) if @user.avatar? %>
|
223
|
+
<%= f.text_field :remote_avatar_url %>
|
224
|
+
</p>
|
225
|
+
<% end %>
|
226
|
+
|
227
|
+
== Providing a default URL
|
228
|
+
|
229
|
+
In many cases, especially when working with images, it might be a good idea to
|
230
|
+
provide a default url, a fallback in case no file has been uploaded. You can do
|
231
|
+
this easily by overriding the +default_url+ method in your uploader:
|
232
|
+
|
233
|
+
class MyUploader < CarrierWave::Uploader::Base
|
234
|
+
def default_url
|
235
|
+
"/images/fallback/" + [version_name, "default.png"].compact.join('_')
|
236
|
+
end
|
237
|
+
end
|
238
|
+
|
239
|
+
== Configuring CarrierWave
|
240
|
+
|
241
|
+
CarrierWave has a broad range of configuration options, which you can configure,
|
242
|
+
both globally and on a per-uploader basis:
|
243
|
+
|
244
|
+
CarrierWave.configure do |config|
|
245
|
+
config.permissions = 0666
|
246
|
+
config.storage = :s3
|
247
|
+
end
|
248
|
+
|
249
|
+
Or alternatively:
|
250
|
+
|
251
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
252
|
+
permissions 0777
|
253
|
+
end
|
254
|
+
|
255
|
+
== Testing CarrierWave
|
256
|
+
|
257
|
+
It's a good idea to test you uploaders in isolation. In order to speed up your
|
258
|
+
tests, it's recommended to switch off processing in your tests, and to use the
|
259
|
+
file storage. In Rails you could do that by adding an initializer with:
|
260
|
+
|
261
|
+
if Rails.env.test?
|
262
|
+
CarrierWave.configure do |config|
|
263
|
+
config.storage = :file
|
264
|
+
config.enable_processing = false
|
265
|
+
end
|
266
|
+
end
|
267
|
+
|
268
|
+
If you need to test your processing, you should test it in isolation, and enable
|
269
|
+
processing only for those tests that need it.
|
270
|
+
|
271
|
+
CarrierWave comes with some RSpec matchers which you may find useful:
|
272
|
+
|
273
|
+
require 'carrierwave/test/matchers'
|
274
|
+
|
275
|
+
describe MyUploader do
|
276
|
+
before do
|
277
|
+
MyUploader.enable_processing = true
|
278
|
+
@uploader = MyUploader.new(@user, :avatar)
|
279
|
+
@uploader.store!(File.open(path_to_file))
|
280
|
+
end
|
281
|
+
|
282
|
+
after do
|
283
|
+
MyUploader.enable_processing = false
|
284
|
+
end
|
285
|
+
|
286
|
+
context 'the thumb version' do
|
287
|
+
it "should scale down a landscape image to be exactly 64 by 64 pixels" do
|
288
|
+
@uploader.thumb.should have_dimensions(200, 200)
|
289
|
+
end
|
290
|
+
end
|
291
|
+
|
292
|
+
context 'the small version' do
|
293
|
+
it "should scale down a landscape image to fit within 200 by 200 pixels" do
|
294
|
+
@uploader.small.should be_no_larger_than(200, 200)
|
295
|
+
end
|
296
|
+
end
|
297
|
+
|
298
|
+
it "should make the image readable only to the owner and not executable" do
|
299
|
+
@uploader.should have_premissions(0600)
|
300
|
+
end
|
301
|
+
end
|
302
|
+
|
303
|
+
== Using Amazon S3
|
304
|
+
|
305
|
+
You'll need to configure a bucket, access id and secret key like this:
|
306
|
+
|
307
|
+
CarrierWave.configure do |config|
|
308
|
+
config.s3_access_key_id = 'xxxxxx'
|
309
|
+
config.s3_secret_access_key = 'xxxxxx'
|
310
|
+
config.s3_bucket = 'name_of_bucket'
|
311
|
+
end
|
312
|
+
|
313
|
+
Do this in an initializer in Rails, and in a +before_app_loads+ block in Merb.
|
314
|
+
|
315
|
+
And then in your uploader, set the storage to :s3
|
316
|
+
|
317
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
318
|
+
storage :s3
|
319
|
+
end
|
320
|
+
|
321
|
+
That's it! You can still use the <code>CarrierWave::Uploader#url</code> method to return
|
322
|
+
the url to the file on Amazon S3.
|
323
|
+
|
324
|
+
Alternatively, and especially if your bucket is located in Europe, you can use the
|
325
|
+
RightAWS library by setting the storage to :right_s3
|
326
|
+
|
327
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
328
|
+
storage :right_s3
|
329
|
+
end
|
330
|
+
|
331
|
+
CarrierWave uses the RightAWS S3 Interface directly, meaning that the performance issues
|
332
|
+
mentioned by Jonathan Yurek for paperclip do not apply: http://groups.google.com/group/paperclip-plugin/browse_thread/thread/d4dc166a9a5f0df4#
|
333
|
+
|
334
|
+
|
335
|
+
== Using MongoDB's GridFS store
|
336
|
+
|
337
|
+
You'll need to configure the database and host to use:
|
338
|
+
|
339
|
+
CarrierWave.configure do |config|
|
340
|
+
config.grid_fs_database = 'my_mongo_database'
|
341
|
+
config.grid_fs_host = 'mongo.example.com'
|
342
|
+
end
|
343
|
+
|
344
|
+
The defaults are 'carrierwave' and 'localhost'.
|
345
|
+
|
346
|
+
And then in your uploader, set the storage to <code>:grid_fs</code>:
|
347
|
+
|
348
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
349
|
+
storage :grid_fs
|
350
|
+
end
|
351
|
+
|
352
|
+
Since GridFS doesn't make the files available via HTTP, you'll need to stream
|
353
|
+
them yourself. In Rails for example, you could use the +send_data+ method. You
|
354
|
+
can tell CarrierWave the URL you will serve your images from, allowing it to
|
355
|
+
generate the correct URL, by setting eg:
|
356
|
+
|
357
|
+
CarrierWave.configure do |config|
|
358
|
+
config.grid_fs_access_url = "/image/show"
|
359
|
+
end
|
360
|
+
|
361
|
+
== Using RMagick
|
362
|
+
|
363
|
+
If you're uploading images, you'll probably want to manipulate them in some way,
|
364
|
+
you might want to create thumbnail images for example. CarrierWave comes with a
|
365
|
+
small library to make manipulating images with RMagick easier, you'll need to
|
366
|
+
include it in your Uploader:
|
367
|
+
|
368
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
369
|
+
include CarrierWave::RMagick
|
370
|
+
end
|
371
|
+
|
372
|
+
The RMagick module gives you a few methods, like
|
373
|
+
<code>CarrierWave::RMagick#resize_to_fill</code> which manipulate the image file in some
|
374
|
+
way. You can set a +process+ callback, which will call that method any time a
|
375
|
+
file is uploaded.
|
376
|
+
|
377
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
378
|
+
include CarrierWave::RMagick
|
379
|
+
|
380
|
+
process :resize_to_fill => [200, 200]
|
381
|
+
process :convert => 'png'
|
382
|
+
|
383
|
+
def filename
|
384
|
+
super + '.png'
|
385
|
+
end
|
386
|
+
end
|
387
|
+
|
388
|
+
Check out the manipulate! method, which makes it easy for you to write your own
|
389
|
+
manipulation methods.
|
390
|
+
|
391
|
+
== Using ImageScience
|
392
|
+
|
393
|
+
ImageScience works the same way as RMagick.
|
394
|
+
|
395
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
396
|
+
include CarrierWave::ImageScience
|
397
|
+
|
398
|
+
process :resize_to_fill => [200, 200]
|
399
|
+
end
|
400
|
+
|
401
|
+
== Using MiniMagick
|
402
|
+
|
403
|
+
MiniMagick is similar to RMagick but performs all the operations using the 'mogrify'
|
404
|
+
command which is part of the standard ImageMagick kit. This allows you to have the power
|
405
|
+
of ImageMagick without having to worry about installing all the RMagick libraries.
|
406
|
+
|
407
|
+
See the MiniMagick site for more details:
|
408
|
+
|
409
|
+
http://github.com/probablycorey/mini_magick
|
410
|
+
|
411
|
+
And the ImageMagick command line options for more for whats on offer:
|
412
|
+
|
413
|
+
http://www.imagemagick.org/script/command-line-options.php
|
414
|
+
|
415
|
+
Currently, the MiniMagick carrierwave processor provides exactly the same methods as
|
416
|
+
for the RMagick processor.
|
417
|
+
|
418
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
419
|
+
include CarrierWave::MiniMagick
|
420
|
+
|
421
|
+
process :resize_to_fill => [200, 200]
|
422
|
+
end
|
423
|
+
|
424
|
+
== Migrating
|
425
|
+
|
426
|
+
If you are using Paperclip, you can use the provided compatibility module:
|
427
|
+
|
428
|
+
class AvatarUploader < CarrierWave::Uploader::Base
|
429
|
+
include CarrierWave::Compatibility::Paperclip
|
430
|
+
end
|
431
|
+
|
432
|
+
See the documentation for <code>Paperclip::Compatibility::Paperclip</code> for more
|
433
|
+
detaills.
|
434
|
+
|
435
|
+
Be sure to use mount_on to specify the correct column:
|
436
|
+
|
437
|
+
mount_uploader :avatar, AvatarUploader, :mount_on => :avatar_file_name
|
438
|
+
|
439
|
+
Unfortunately AttachmentFoo differs too much in philosophy for there to be a
|
440
|
+
sensible compatibility mode. Patches for migrating from other solutions will be
|
441
|
+
happily accepted.
|
442
|
+
|
443
|
+
== i18n
|
444
|
+
|
445
|
+
The activerecord validations use the Rails i18n framework. Add these keys to
|
446
|
+
your translations file:
|
447
|
+
|
448
|
+
carrierwave:
|
449
|
+
errors:
|
450
|
+
integrity: 'Not an image.'
|
451
|
+
processing: 'Cannot resize image.'
|
452
|
+
|
453
|
+
== Contributors
|
454
|
+
|
455
|
+
These people have contributed their time and effort to CarrierWave:
|
456
|
+
|
457
|
+
* Jonas Nicklas
|
458
|
+
* Pavel Kunc
|
459
|
+
* Andrew Timberlake
|
460
|
+
* Durran Jordan
|
461
|
+
* Scott Motte
|
462
|
+
* Sho Fukamachi
|
463
|
+
* Sam Lown
|
464
|
+
* Dave Ott
|
465
|
+
* Quin Hoxie
|
466
|
+
|
467
|
+
== License
|
468
|
+
|
469
|
+
Copyright (c) 2008 Jonas Nicklas
|
470
|
+
|
471
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
472
|
+
a copy of this software and associated documentation files (the
|
473
|
+
"Software"), to deal in the Software without restriction, including
|
474
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
475
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
476
|
+
permit persons to whom the Software is furnished to do so, subject to
|
477
|
+
the following conditions:
|
478
|
+
|
479
|
+
The above copyright notice and this permission notice shall be
|
480
|
+
included in all copies or substantial portions of the Software.
|
481
|
+
|
482
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
483
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
484
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
485
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
486
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
487
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
488
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
489
|
+
|
490
|
+
== Development
|
491
|
+
|
492
|
+
If you want to run the tests (and you should) it might be convenient to install
|
493
|
+
the development dependencies, you can do that with:
|
494
|
+
|
495
|
+
sudo gem install carrierwave --development
|
496
|
+
|
497
|
+
CarrierWave is still young, but most of it is pretty well documented. It is also
|
498
|
+
extensively specced, and there are cucumber features for some common use cases.
|
499
|
+
Just dig in and look at the source for more in-depth explanation of what things
|
500
|
+
are doing.
|
501
|
+
|
502
|
+
Issues are reported on GitHub, pull requests are very welcome!
|
data/Rakefile
ADDED
@@ -0,0 +1,38 @@
|
|
1
|
+
require 'rubygems'
|
2
|
+
gem 'hoe', '>= 2.1.0'
|
3
|
+
require 'hoe'
|
4
|
+
require 'fileutils'
|
5
|
+
$:.unshift File.join(File.dirname(__FILE__), 'lib')
|
6
|
+
require 'carrierwave'
|
7
|
+
|
8
|
+
Hoe.plugin :newgem
|
9
|
+
# Hoe.plugin :website
|
10
|
+
Hoe.plugin :cucumberfeatures
|
11
|
+
|
12
|
+
$hoe = Hoe.spec 'dsturnbull-carrierwave' do
|
13
|
+
self.developer 'Jonas Nicklas', 'jonas.nicklas@gmail.com'
|
14
|
+
self.rubyforge_name = self.name
|
15
|
+
self.readme_file = 'README.rdoc'
|
16
|
+
self.version = CarrierWave::VERSION
|
17
|
+
self.extra_dev_deps << ['newgem', '>=1.5.2']
|
18
|
+
self.extra_dev_deps << ['rspec', '>=1.2.8']
|
19
|
+
self.extra_dev_deps << ['cucumber', '>=0.3.96']
|
20
|
+
self.extra_dev_deps << ['activerecord', '>=2.3.3']
|
21
|
+
self.extra_dev_deps << ['sqlite3-ruby', '>=1.2.5']
|
22
|
+
self.extra_dev_deps << ['dm-core', '>=0.9.11']
|
23
|
+
self.extra_dev_deps << ['data_objects', '>=0.9.12']
|
24
|
+
self.extra_dev_deps << ['do_sqlite3', '>=0.9.11']
|
25
|
+
self.extra_dev_deps << ['sequel', '>=3.2.0']
|
26
|
+
self.extra_dev_deps << ['rmagick', '>=2.10.0']
|
27
|
+
self.extra_dev_deps << ['mini_magick', '>=1.2.5']
|
28
|
+
self.extra_dev_deps << ['mongo_mapper', '>=0.6.8']
|
29
|
+
self.extra_dev_deps << ['mongoid', '>=0.10.4']
|
30
|
+
self.extra_dev_deps << ['aws-s3', '>=0.6.2']
|
31
|
+
self.extra_dev_deps << ['timecop', '>=0.3.4']
|
32
|
+
self.extra_rdoc_files << 'README.rdoc'
|
33
|
+
end
|
34
|
+
|
35
|
+
require 'newgem/tasks'
|
36
|
+
Dir['tasks/**/*.rake'].each { |t| load t }
|
37
|
+
|
38
|
+
task :default => [:spec, :features]
|
data/cucumber.yml
ADDED
@@ -0,0 +1,28 @@
|
|
1
|
+
Feature: uploader with file storage
|
2
|
+
In order to be able to temporarily store files to disk
|
3
|
+
As a developer using CarrierWave
|
4
|
+
I want to cache files
|
5
|
+
|
6
|
+
Scenario: cache a file
|
7
|
+
Given an uploader class that uses the 'file' storage
|
8
|
+
And an instance of that class
|
9
|
+
When I cache the file 'fixtures/bork.txt'
|
10
|
+
Then there should be a file called 'bork.txt' somewhere in a subdirectory of 'public/uploads/tmp'
|
11
|
+
And the file called 'bork.txt' in a subdirectory of 'public/uploads/tmp' should be identical to the file at 'fixtures/bork.txt'
|
12
|
+
|
13
|
+
Scenario: cache two files in succession
|
14
|
+
Given an uploader class that uses the 'file' storage
|
15
|
+
And an instance of that class
|
16
|
+
When I cache the file 'fixtures/bork.txt'
|
17
|
+
Then there should be a file called 'bork.txt' somewhere in a subdirectory of 'public/uploads/tmp'
|
18
|
+
And the file called 'bork.txt' in a subdirectory of 'public/uploads/tmp' should be identical to the file at 'fixtures/bork.txt'
|
19
|
+
When I cache the file 'fixtures/monkey.txt'
|
20
|
+
Then there should be a file called 'monkey.txt' somewhere in a subdirectory of 'public/uploads/tmp'
|
21
|
+
And the file called 'monkey.txt' in a subdirectory of 'public/uploads/tmp' should be identical to the file at 'fixtures/monkey.txt'
|
22
|
+
|
23
|
+
Scenario: retrieving a file from cache
|
24
|
+
Given an uploader class that uses the 'file' storage
|
25
|
+
And an instance of that class
|
26
|
+
And the file 'fixtures/bork.txt' is cached file at 'public/uploads/tmp/20090212-2343-8336-0348/bork.txt'
|
27
|
+
When I retrieve the cache name '20090212-2343-8336-0348/bork.txt' from the cache
|
28
|
+
Then the uploader should have 'public/uploads/tmp/20090212-2343-8336-0348/bork.txt' as its current path
|
@@ -0,0 +1,20 @@
|
|
1
|
+
Feature: downloading files
|
2
|
+
In order to allow users to upload remote files
|
3
|
+
As a developer using CarrierWave
|
4
|
+
I want to download files to the filesystem via HTTP
|
5
|
+
|
6
|
+
Background:
|
7
|
+
Given an uploader class that uses the 'file' storage
|
8
|
+
And an instance of that class
|
9
|
+
|
10
|
+
Scenario: download a file
|
11
|
+
When I download the file 'http://s3.amazonaws.com/Monkey/testfile.txt'
|
12
|
+
Then there should be a file called 'testfile.txt' somewhere in a subdirectory of 'public/uploads/tmp'
|
13
|
+
And the file called 'testfile.txt' in a subdirectory of 'public/uploads/tmp' should contain 'S3 Remote File'
|
14
|
+
|
15
|
+
Scenario: downloading a file then storing
|
16
|
+
When I download the file 'http://s3.amazonaws.com/Monkey/testfile.txt'
|
17
|
+
And I store the file
|
18
|
+
Then there should be a file at 'public/uploads/testfile.txt'
|
19
|
+
And the file at 'public/uploads/testfile.txt' should contain 'S3 Remote File'
|
20
|
+
|
@@ -0,0 +1,37 @@
|
|
1
|
+
Feature: uploader with file storage
|
2
|
+
In order to be awesome
|
3
|
+
As a developer using CarrierWave
|
4
|
+
I want to upload files to the filesystem
|
5
|
+
|
6
|
+
Background:
|
7
|
+
Given an uploader class that uses the 'file' storage
|
8
|
+
And an instance of that class
|
9
|
+
|
10
|
+
Scenario: store a file
|
11
|
+
When I store the file 'fixtures/bork.txt'
|
12
|
+
Then there should be a file at 'public/uploads/bork.txt'
|
13
|
+
And the file at 'public/uploads/bork.txt' should be identical to the file at 'fixtures/bork.txt'
|
14
|
+
|
15
|
+
Scenario: store two files in succession
|
16
|
+
When I store the file 'fixtures/bork.txt'
|
17
|
+
Then there should be a file at 'public/uploads/bork.txt'
|
18
|
+
And the file at 'public/uploads/bork.txt' should be identical to the file at 'fixtures/bork.txt'
|
19
|
+
When I store the file 'fixtures/monkey.txt'
|
20
|
+
Then there should be a file at 'public/uploads/monkey.txt'
|
21
|
+
And the file at 'public/uploads/monkey.txt' should be identical to the file at 'fixtures/monkey.txt'
|
22
|
+
|
23
|
+
Scenario: cache a file and then store it
|
24
|
+
When I cache the file 'fixtures/bork.txt'
|
25
|
+
Then there should be a file called 'bork.txt' somewhere in a subdirectory of 'public/uploads/tmp'
|
26
|
+
And the file called 'bork.txt' in a subdirectory of 'public/uploads/tmp' should be identical to the file at 'fixtures/bork.txt'
|
27
|
+
And there should not be a file at 'public/uploads/bork.txt'
|
28
|
+
When I store the file
|
29
|
+
Then there should be a file at 'public/uploads/bork.txt'
|
30
|
+
And the file at 'public/uploads/bork.txt' should be identical to the file at 'fixtures/bork.txt'
|
31
|
+
|
32
|
+
Scenario: retrieving a file from cache then storing
|
33
|
+
Given the file 'fixtures/bork.txt' is cached file at 'public/uploads/tmp/20090212-2343-8336-0348/bork.txt'
|
34
|
+
When I retrieve the cache name '20090212-2343-8336-0348/bork.txt' from the cache
|
35
|
+
And I store the file
|
36
|
+
Then there should be a file at 'public/uploads/bork.txt'
|
37
|
+
And the file at 'public/uploads/bork.txt' should be identical to the file at 'fixtures/bork.txt'
|
@@ -0,0 +1,38 @@
|
|
1
|
+
Feature: uploader with file storage and overriden filename
|
2
|
+
In order to be awesome
|
3
|
+
As a developer using CarrierWave
|
4
|
+
I want to upload files to the filesystem with an overriden filename
|
5
|
+
|
6
|
+
Background:
|
7
|
+
Given an uploader class that uses the 'file' storage
|
8
|
+
And that the uploader reverses the filename
|
9
|
+
And an instance of that class
|
10
|
+
|
11
|
+
Scenario: store a file
|
12
|
+
When I store the file 'fixtures/bork.txt'
|
13
|
+
Then there should be a file at 'public/uploads/txt.krob'
|
14
|
+
And the file at 'public/uploads/txt.krob' should be identical to the file at 'fixtures/bork.txt'
|
15
|
+
|
16
|
+
Scenario: store two files in succession
|
17
|
+
When I store the file 'fixtures/bork.txt'
|
18
|
+
Then there should be a file at 'public/uploads/txt.krob'
|
19
|
+
And the file at 'public/uploads/txt.krob' should be identical to the file at 'fixtures/bork.txt'
|
20
|
+
When I store the file 'fixtures/monkey.txt'
|
21
|
+
Then there should be a file at 'public/uploads/txt.yeknom'
|
22
|
+
And the file at 'public/uploads/txt.yeknom' should be identical to the file at 'fixtures/monkey.txt'
|
23
|
+
|
24
|
+
Scenario: cache a file and then store it
|
25
|
+
When I cache the file 'fixtures/bork.txt'
|
26
|
+
Then there should be a file called 'bork.txt' somewhere in a subdirectory of 'public/uploads/tmp'
|
27
|
+
And the file called 'bork.txt' in a subdirectory of 'public/uploads/tmp' should be identical to the file at 'fixtures/bork.txt'
|
28
|
+
And there should not be a file at 'public/uploads/txt.krob'
|
29
|
+
When I store the file
|
30
|
+
Then there should be a file at 'public/uploads/txt.krob'
|
31
|
+
And the file at 'public/uploads/txt.krob' should be identical to the file at 'fixtures/bork.txt'
|
32
|
+
|
33
|
+
Scenario: retrieving a file from cache then storing
|
34
|
+
Given the file 'fixtures/bork.txt' is cached file at 'public/uploads/tmp/20090212-2343-8336-0348/bork.txt'
|
35
|
+
When I retrieve the cache name '20090212-2343-8336-0348/bork.txt' from the cache
|
36
|
+
And I store the file
|
37
|
+
Then there should be a file at 'public/uploads/txt.krob'
|
38
|
+
And the file at 'public/uploads/txt.krob' should be identical to the file at 'fixtures/bork.txt'
|