Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 1031 lines (756 sloc) 30.719 kB
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
1 # CarrierWave
2
3 This gem provides a simple and extremely flexible way to upload files from Ruby applications.
4 It works well with Rack based web applications, such as Ruby on Rails.
5
5cc961e @rmm5t Switch to SVG badges in readme
rmm5t authored
6 [![Build Status](https://travis-ci.org/carrierwaveuploader/carrierwave.svg?branch=master)](http://travis-ci.org/carrierwaveuploader/carrierwave)
7 [![Code Climate](http://img.shields.io/codeclimate/github/carrierwaveuploader/carrierwave.svg)](https://codeclimate.com/github/carrierwaveuploader/carrierwave)
f30f54e @bensie Add Travis CI build status badge
bensie authored
8
68ba569 @nacengineer Squelch the confusion with a big disclaimer
nacengineer authored
9
10 > ## carrierwave version disclaimer
94fe489 @eavgerinos [Fix #1622] Remove mandatory requiring of Fog gem
eavgerinos authored
11 > ***This README is for a branch which is still in development.
68ba569 @nacengineer Squelch the confusion with a big disclaimer
nacengineer authored
12 > Please switch to latest `0.x` branch for stable version.***
13
14
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
15 ## Information
16
17 * RDoc documentation [available on RubyDoc.info](http://rubydoc.info/gems/carrierwave/frames)
1e87bb5 @bensie Update URLs to carrierwaveuploader/carrierwave
bensie authored
18 * Source code [available on GitHub](http://github.com/carrierwaveuploader/carrierwave)
19 * More information, known limitations, and how-tos [available on the wiki](https://github.com/carrierwaveuploader/carrierwave/wiki)
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
20
21 ## Getting Help
22
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
23 * Please ask the community on [Stack Overflow](http://stackoverflow.com/) for help if you have any questions. Please do not post usage questions on the issue tracker.
1e87bb5 @bensie Update URLs to carrierwaveuploader/carrierwave
bensie authored
24 * Please report bugs on the [issue tracker](http://github.com/carrierwaveuploader/carrierwave/issues) but read the "getting help" section in the wiki first.
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
25
26 ## Installation
27
28 Install the latest stable release:
29
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
30 ```
31 $ gem install carrierwave
32 ```
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
33
34 In Rails, add it to your Gemfile:
35
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
36 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
37 gem 'carrierwave'
38 ```
39
fa5304a @davekiss Update README.md
davekiss authored
40 Finally, restart the server to apply the changes.
41
fe5001f @trevrosen Clarify what's necessary for mount_uploaders
trevrosen authored
42 As of version 1.0.0 (forthcoming), CarrierWave requires Rails 4.0 or higher and Ruby 2.0
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
43 or higher. If you're on Rails 3, you should use v0.10.0.
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
44
45 ## Getting Started
46
47 Start off by generating an uploader:
48
49 rails generate uploader Avatar
50
51 this should give you a file in:
52
53 app/uploaders/avatar_uploader.rb
54
55 Check out this file for some hints on how you can customize your uploader. It
56 should look something like this:
57
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
58 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
59 class AvatarUploader < CarrierWave::Uploader::Base
60 storage :file
61 end
62 ```
63
64 You can use your uploader class to store and retrieve files like this:
65
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
66 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
67 uploader = AvatarUploader.new
68
69 uploader.store!(my_file)
70
71 uploader.retrieve_from_store!('my_file.png')
72 ```
73
74 CarrierWave gives you a `store` for permanent storage, and a `cache` for
8c507be @trevorturk update history and readme
trevorturk authored
75 temporary storage. You can use different stores, including filesystem
76 and cloud storage.
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
77
78 Most of the time you are going to want to use CarrierWave together with an ORM.
79 It is quite simple to mount uploaders on columns in your model, so you can
80 simply assign files and get going:
81
8c507be @trevorturk update history and readme
trevorturk authored
82 ### ActiveRecord
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
83
84 Make sure you are loading CarrierWave after loading your ORM, otherwise you'll
85 need to require the relevant extension manually, e.g.:
86
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
87 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
88 require 'carrierwave/orm/activerecord'
89 ```
90
1e87bb5 @bensie Update URLs to carrierwaveuploader/carrierwave
bensie authored
91 Add a string column to the model you want to mount the uploader by creating
3b5c588 @edusantana Creating a migration
edusantana authored
92 a migration:
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
93
ed7ec3b @edgurgel Fix syntax highlighting on README.md
edgurgel authored
94
95 rails g migration add_avatar_to_users avatar:string
96 rake db:migrate
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
97
98 Open your model file and mount the uploader:
99
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
100 ```ruby
475f315 @mrreynolds Added missing AR::Base inheritance to example in AR subchapter to be …
mrreynolds authored
101 class User < ActiveRecord::Base
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
102 mount_uploader :avatar, AvatarUploader
103 end
104 ```
105
106 Now you can cache files by assigning them to the attribute, they will
107 automatically be stored when the record is saved.
108
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
109 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
110 u = User.new
49eab8e @mlaco Make example in README more clear.
mlaco authored
111 u.avatar = params[:file] # Assign a file like this, or
cd6f1cf @alup Use block for File.open to close files immediately in code examples
alup authored
112
113 # like this
5470e35 @bensie Add missing block var
bensie authored
114 File.open('somewhere') do |f|
cd6f1cf @alup Use block for File.open to close files immediately in code examples
alup authored
115 u.avatar = f
116 end
117
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
118 u.save!
119 u.avatar.url # => '/url/to/file.png'
120 u.avatar.current_path # => 'path/to/file.png'
110a7e9 @StanBoyet Model.attached was nil, using model_attached fixes it.
StanBoyet authored
121 u.avatar_identifier # => 'file.png'
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
122 ```
123
8c507be @trevorturk update history and readme
trevorturk authored
124 ### DataMapper, Mongoid, Sequel
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
125
8c507be @trevorturk update history and readme
trevorturk authored
126 Other ORM support has been extracted into separate gems:
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
127
1e87bb5 @bensie Update URLs to carrierwaveuploader/carrierwave
bensie authored
128 * [carrierwave-datamapper](https://github.com/carrierwaveuploader/carrierwave-datamapper)
129 * [carrierwave-mongoid](https://github.com/carrierwaveuploader/carrierwave-mongoid)
539bfea @taavo fixes #1228 broken link
taavo authored
130 * [carrierwave-sequel](https://github.com/jnicklas/carrierwave-sequel)
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
131
1e87bb5 @bensie Update URLs to carrierwaveuploader/carrierwave
bensie authored
132 There are more extensions listed in [the wiki](https://github.com/carrierwaveuploader/carrierwave/wiki)
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
133
229b664 Add README section about multiple file uploads
Jonas Nicklas and Lisa Hammarström authored
134 ## Multiple file uploads
fe5001f @trevrosen Clarify what's necessary for mount_uploaders
trevrosen authored
135 **Note:** You must specify using the master branch to enable this feature:
136
bff219c @tgxworld Add missing quotes. [CI SKIP]
tgxworld authored
137 `gem 'carrierwave', github:'carrierwaveuploader/carrierwave'`.
229b664 Add README section about multiple file uploads
Jonas Nicklas and Lisa Hammarström authored
138
139 CarrierWave also has convenient support for multiple file upload fields.
140
141 ### ActiveRecord
142
143 Add a column which can store an array. This could be an array column or a JSON
3595ef8 @matthewbarram change "suppors to supports"
matthewbarram authored
144 column for example. Your choice depends on what your database supports. For
229b664 Add README section about multiple file uploads
Jonas Nicklas and Lisa Hammarström authored
145 example, create a migration like this:
146
147
148 rails g migration add_avatars_to_users avatars:json
149 rake db:migrate
150
151 Open your model file and mount the uploader:
152
153 ```ruby
154 class User < ActiveRecord::Base
155 mount_uploaders :avatars, AvatarUploader
156 end
157 ```
158
159 Make sure your file input fields are set up as multiple file fields. For
160 example in Rails you'll want to do something like this:
161
162 ```erb
163 <%= form.file_field :files, multiple: true %>
164 ```
165
166 Now you can cache files by assigning them to the attribute, they will
167 automatically be stored when the record is saved.
168
169 ```ruby
170 u = User.new
171 u.avatars = params[:files] # Assign an array of files like this
172 u.avatars = [File.open('somewhere')] # or like this
173 u.save!
174 u.avatars[0].url # => '/url/to/file.png'
175 u.avatars[0].current_path # => 'path/to/file.png'
176 u.avatars[0].identifier # => 'file.png'
177 ```
178
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
179 ## Changing the storage directory
180
181 In order to change where uploaded files are put, just override the `store_dir`
182 method:
183
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
184 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
185 class MyUploader < CarrierWave::Uploader::Base
186 def store_dir
187 'public/my/upload/directory'
188 end
189 end
190 ```
191
192 This works for the file storage as well as Amazon S3 and Rackspace Cloud Files.
193 Define `store_dir` as `nil` if you'd like to store files at the root level.
194
5e8200d @rilian Example of setting `cache_dir` outside of project folder
rilian authored
195 If you store files outside the project root folder, you may want to define `cache_dir` in the same way:
196
197 ```ruby
198 class MyUploader < CarrierWave::Uploader::Base
199 def cache_dir
200 '/tmp/projectname-cache'
201 end
202 end
203 ```
204
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
205 ## Securing uploads
206
f960fe9 @chesterlaw Fix grammar (pluralize file to files)
chesterlaw authored
207 Certain files might be dangerous if uploaded to the wrong location, such as php
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
208 files or other script files. CarrierWave allows you to specify a white-list of
209 allowed extensions.
210
211 If you're mounting the uploader, uploading a file with the wrong extension will
212 make the record invalid instead. Otherwise, an error is raised.
213
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
214 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
215 class MyUploader < CarrierWave::Uploader::Base
216 def extension_white_list
217 %w(jpg jpeg gif png)
218 end
219 end
220 ```
221
222 ### Filenames and unicode chars
223
224 Another security issue you should care for is the file names (see
225 [Ruby On Rails Security Guide](http://guides.rubyonrails.org/security.html#file-uploads)).
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
226 By default, CarrierWave provides only English letters, arabic numerals and some symbols as
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
227 white-listed characters in the file name. If you want to support local scripts (Cyrillic letters, letters with diacritics and so on), you
228 have to override `sanitize_regexp` method. It should return regular expression which would match
229 all *non*-allowed symbols.
230
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
231 ```ruby
ed7ec3b @edgurgel Fix syntax highlighting on README.md
edgurgel authored
232 CarrierWave::SanitizedFile.sanitize_regexp = /[^[:word:]\.\-\+]/
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
233 ```
234
235 Also make sure that allowing non-latin characters won't cause a compatibility issue with a third-party
236 plugins or client-side software.
237
e2b5faf @trevorturk Shorten mime-types section in readme
trevorturk authored
238 ## Setting the content type
239
85fc0d0 @bensie Fix Onigmo in readme, closes #1415
bensie authored
240 As of v0.10.0, the `mime-types` gem is a runtime dependency and the content type is set automatically.
97a713f @bensie Update README for content-type changes [ci-skip]
bensie authored
241 You no longer need to do this manually.
e2b5faf @trevorturk Shorten mime-types section in readme
trevorturk authored
242
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
243 ## Adding versions
244
2c1af3a @a17levine Specify need for imagemagick/minimagick, and give directions in resiz…
a17levine authored
245 Often you'll want to add different versions of the same file. The classic example is image thumbnails. There is built in support for this*:
246
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
247 *Note:* You must have Imagemagick and MiniMagick installed to do image resizing. MiniMagick is a Ruby interface for Imagemagick which is a C program. This is why MiniMagick fails on 'bundle install' without Imagemagick installed.
2c1af3a @a17levine Specify need for imagemagick/minimagick, and give directions in resiz…
a17levine authored
248
249 Some documentation refers to RMagick instead of MiniMagick but MiniMagick is recommended.
250
251 To install Imagemagick on OSX with homebrew type the following:
252
253 ```
254 $ brew install imagemagick
255 ```
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
256
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
257 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
258 class MyUploader < CarrierWave::Uploader::Base
c5c0747 @janko-m Use CarrierWave::MiniMagick in the readme
janko-m authored
259 include CarrierWave::MiniMagick
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
260
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
261 process resize_to_fit: [800, 800]
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
262
263 version :thumb do
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
264 process resize_to_fill: [200,200]
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
265 end
266
267 end
268 ```
269
270 When this uploader is used, an uploaded image would be scaled to be no larger
271 than 800 by 800 pixels. A version called thumb is then created, which is scaled
272 and cropped to exactly 200 by 200 pixels. The uploader could be used like this:
273
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
274 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
275 uploader = AvatarUploader.new
276 uploader.store!(my_file) # size: 1024x768
277
ab24f50 @bartj3 The resize_to_fit process won't scale to 800x800 but 800x600
bartj3 authored
278 uploader.url # => '/url/to/my_file.png' # size: 800x600
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
279 uploader.thumb.url # => '/url/to/thumb_my_file.png' # size: 200x200
280 ```
281
282 One important thing to remember is that process is called *before* versions are
283 created. This can cut down on processing cost.
284
285 It is possible to nest versions within versions:
286
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
287 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
288 class MyUploader < CarrierWave::Uploader::Base
289
290 version :animal do
291 version :human
292 version :monkey
293 version :llama
294 end
295 end
296 ```
297
04da7ed @ened Added docs about the conditional versions.
ened authored
298 ### Conditional versions
299
300 Occasionally you want to restrict the creation of versions on certain
301 properties within the model or based on the picture itself.
302
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
303 ```ruby
04da7ed @ened Added docs about the conditional versions.
ened authored
304 class MyUploader < CarrierWave::Uploader::Base
305
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
306 version :human, if: :is_human?
307 version :monkey, if: :is_monkey?
308 version :banner, if: :is_landscape?
04da7ed @ened Added docs about the conditional versions.
ened authored
309
c1b9f8b @amatsuda protected => private
amatsuda authored
310 private
04da7ed @ened Added docs about the conditional versions.
ened authored
311
312 def is_human? picture
313 model.can_program?(:ruby)
314 end
5783c36 @bensie Beging preparing for 0.6.0
bensie authored
315
04da7ed @ened Added docs about the conditional versions.
ened authored
316 def is_monkey? picture
317 model.favorite_food == 'banana'
318 end
5783c36 @bensie Beging preparing for 0.6.0
bensie authored
319
04da7ed @ened Added docs about the conditional versions.
ened authored
320 def is_landscape? picture
321 image = MiniMagick::Image.open(picture.path)
322 image[:width] > image[:height]
323 end
5783c36 @bensie Beging preparing for 0.6.0
bensie authored
324
04da7ed @ened Added docs about the conditional versions.
ened authored
325 end
326 ```
327
328 The `model` variable points to the instance object the uploader is attached to.
329
2049cda @ferblape Update README with new option :from_version
ferblape authored
330 ### Create versions from existing versions
331
aba6213 @bensie Reword version from existing version docs
bensie authored
332 For performance reasons, it is often useful to create versions from existing ones
333 instead of using the original file. If your uploader generates several versions
334 where the next is smaller than the last, it will take less time to generate from
335 a smaller, already processed image.
2049cda @ferblape Update README with new option :from_version
ferblape authored
336
337 ```ruby
338 class MyUploader < CarrierWave::Uploader::Base
339
340 version :thumb do
341 process resize_to_fill: [280, 280]
342 end
aba6213 @bensie Reword version from existing version docs
bensie authored
343
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
344 version :small_thumb, from_version: :thumb do
2049cda @ferblape Update README with new option :from_version
ferblape authored
345 process resize_to_fill: [20, 20]
346 end
aba6213 @bensie Reword version from existing version docs
bensie authored
347
2049cda @ferblape Update README with new option :from_version
ferblape authored
348 end
349 ```
350
aba6213 @bensie Reword version from existing version docs
bensie authored
351 The option `:from_version` uses the file cached in the `:thumb` version instead
352 of the original version, potentially resulting in faster processing.
2049cda @ferblape Update README with new option :from_version
ferblape authored
353
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
354 ## Making uploads work across form redisplays
355
356 Often you'll notice that uploaded files disappear when a validation fails.
357 CarrierWave has a feature that makes it easy to remember the uploaded file even
358 in that case. Suppose your `user` model has an uploader mounted on `avatar`
1a0a349 @pupeno Reminder about adding *_cache to attr_accessible
pupeno authored
359 file, just add a hidden field called `avatar_cache` (don't forget to add it to
360 the attr_accessible list as necessary). In Rails, this would look like this:
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
361
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
362 ```erb
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
363 <%= form_for @user, html: { multipart: true } do |f| %>
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
364 <p>
365 <label>My Avatar</label>
366 <%= f.file_field :avatar %>
367 <%= f.hidden_field :avatar_cache %>
368 </p>
369 <% end %>
370 ````
371
372 It might be a good idea to show the user that a file has been uploaded, in the
373 case of images, a small thumbnail would be a good indicator:
374
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
375 ```erb
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
376 <%= form_for @user, html: { multipart: true } do |f| %>
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
377 <p>
378 <label>My Avatar</label>
379 <%= image_tag(@user.avatar_url) if @user.avatar? %>
380 <%= f.file_field :avatar %>
381 <%= f.hidden_field :avatar_cache %>
382 </p>
383 <% end %>
384 ```
385
386 ## Removing uploaded files
387
388 If you want to remove a previously uploaded file on a mounted uploader, you can
389 easily add a checkbox to the form which will remove the file when checked.
390
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
391 ```erb
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
392 <%= form_for @user, html: { multipart: true } do |f| %>
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
393 <p>
394 <label>My Avatar</label>
395 <%= image_tag(@user.avatar_url) if @user.avatar? %>
396 <%= f.file_field :avatar %>
397 </p>
398
399 <p>
400 <label>
401 <%= f.check_box :remove_avatar %>
402 Remove avatar
403 </label>
404 </p>
405 <% end %>
406 ```
407
d721b28 @erichurst Update README with remove_upload example.
erichurst authored
408 If you want to remove the file manually, you can call <code>remove_avatar!</code>, then save the object.
409
410 ```erb
411 @user.remove_avatar!
412 @user.save
413 #=> true
414 ```
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
415
416 ## Uploading files from a remote location
417
418 Your users may find it convenient to upload a file from a location on the Internet
419 via a URL. CarrierWave makes this simple, just add the appropriate attribute to your
420 form and you're good to go:
421
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
422 ```erb
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
423 <%= form_for @user, html: { multipart: true } do |f| %>
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
424 <p>
425 <label>My Avatar URL:</label>
426 <%= image_tag(@user.avatar_url) if @user.avatar? %>
427 <%= f.text_field :remote_avatar_url %>
428 </p>
429 <% end %>
430 ```
431
1d8dfcf @taavo readme: better document what happens when remote_url fails
taavo authored
432 If you're using ActiveRecord, CarrierWave will indicate invalid URLs and download
433 failures automatically with attribute validation errors. If you aren't, or you
434 disable CarrierWave's `validate_download` option, you'll need to handle those
6b15cd8 @taavo readme: remove outdated reference to inability to handle brackets in …
taavo authored
435 errors yourself.
fa47703 @taavo update readme: you should validate remote_url fields
taavo authored
436
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
437 ## Providing a default URL
438
439 In many cases, especially when working with images, it might be a good idea to
440 provide a default url, a fallback in case no file has been uploaded. You can do
441 this easily by overriding the `default_url` method in your uploader:
442
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
443 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
444 class MyUploader < CarrierWave::Uploader::Base
038457d @yui-knk Fix how to override `default_url` in README.md
yui-knk authored
445 def default_url(*args)
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
446 "/images/fallback/" + [version_name, "default.png"].compact.join('_')
447 end
448 end
449 ```
450
fd1dcc9 @c0 Update README.md to include using the asset pipeline in default_url
c0 authored
451 Or if you are using the Rails asset pipeline:
452
453 ```ruby
454 class MyUploader < CarrierWave::Uploader::Base
038457d @yui-knk Fix how to override `default_url` in README.md
yui-knk authored
455 def default_url(*args)
fd1dcc9 @c0 Update README.md to include using the asset pipeline in default_url
c0 authored
456 ActionController::Base.helpers.asset_path("fallback/" + [version_name, "default.png"].compact.join('_'))
457 end
458 end
459 ```
460
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
461 ## Recreating versions
462
463 You might come to a situation where you want to retroactively change a version
7ae316e @stravid Use single ticks for inline code
stravid authored
464 or add a new one. You can use the `recreate_versions!` method to recreate the
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
465 versions from the base file. This uses a naive approach which will re-upload and
c0737ad @div Update readme
div authored
466 process the specified version or all versions, if none is passed as an argument.
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
467
7ae316e @stravid Use single ticks for inline code
stravid authored
468 When you are generating random unique filenames you have to call `save!` on
469 the model after using `recreate_versions!`. This is necessary because
470 `recreate_versions!` doesn't save the new filename to the database. Calling
471 `save!` yourself will prevent that the database and file system are running
fb7a9fc @stravid Add note about using recreate_versions! with random unique filenames
stravid authored
472 out of sync.
473
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
474 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
475 instance = MyUploader.new
c0737ad @div Update readme
div authored
476 instance.recreate_versions!(:thumb, :large)
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
477 ```
478
479 Or on a mounted uploader:
480
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
481 ```ruby
687d276 @prasselpikachu .all.each is highly inefficient with many rows
prasselpikachu authored
482 User.find_each do |user|
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
483 user.avatar.recreate_versions!
484 end
485 ```
486
b310fbf @rin Improve README on recreate_versions! throwing an exception
rin authored
487 Note: `recreate_versions!` will throw an exception on records without an image. To avoid this, scope the records to those with images or check if an image exists within the block. If you're using ActiveRecord, recreating versions for a user avatar might look like this:
488
489 ```ruby
687d276 @prasselpikachu .all.each is highly inefficient with many rows
prasselpikachu authored
490 User.find_each do |user|
b310fbf @rin Improve README on recreate_versions! throwing an exception
rin authored
491 user.avatar.recreate_versions! if user.avatar?
492 end
493 ```
494
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
495 ## Configuring CarrierWave
496
497 CarrierWave has a broad range of configuration options, which you can configure,
498 both globally and on a per-uploader basis:
499
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
500 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
501 CarrierWave.configure do |config|
502 config.permissions = 0666
26a4d34 @felixbuenemann Support setting permissions of created directories
felixbuenemann authored
503 config.directory_permissions = 0777
5783c36 @bensie Beging preparing for 0.6.0
bensie authored
504 config.storage = :file
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
505 end
506 ```
507
508 Or alternatively:
509
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
510 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
511 class AvatarUploader < CarrierWave::Uploader::Base
512 permissions 0777
513 end
514 ```
515
516 If you're using Rails, create an initializer for this:
517
ed7ec3b @edgurgel Fix syntax highlighting on README.md
edgurgel authored
518 config/initializers/carrierwave.rb
519
c98cbbc @benwoodward update readme with info about silenced errors
benwoodward authored
520 If you want CarrierWave to fail noisily in development, you can change these configs in your environment file:
521
522 ```ruby
523 CarrierWave.configure do |config|
524 config.ignore_integrity_errors = false
525 config.ignore_processing_errors = false
526 config.ignore_download_errors = false
527 end
528 ```
529
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
530
531 ## Testing with CarrierWave
532
70fb8d6 Fixed grammatical error in README.
Ryan Ricard authored
533 It's a good idea to test your uploaders in isolation. In order to speed up your
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
534 tests, it's recommended to switch off processing in your tests, and to use the
535 file storage. In Rails you could do that by adding an initializer with:
536
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
537 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
538 if Rails.env.test? or Rails.env.cucumber?
539 CarrierWave.configure do |config|
540 config.storage = :file
541 config.enable_processing = false
542 end
543 end
544 ```
545
4f7e42f @pjg Add 'remember' note for setting store in initializer
pjg authored
546 Remember, if you have already set `storage :something` in your uploader, the `storage`
547 setting from this initializer will be ignored.
548
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
549 If you need to test your processing, you should test it in isolation, and enable
550 processing only for those tests that need it.
551
552 CarrierWave comes with some RSpec matchers which you may find useful:
553
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
554 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
555 require 'carrierwave/test/matchers'
556
557 describe MyUploader do
558 include CarrierWave::Test::Matchers
559
560 before do
561 MyUploader.enable_processing = true
562 @uploader = MyUploader.new(@user, :avatar)
cd6f1cf @alup Use block for File.open to close files immediately in code examples
alup authored
563
564 File.open(path_to_file) do |f|
565 @uploader.store!(f)
566 end
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
567 end
568
569 after do
570 MyUploader.enable_processing = false
085b96d In the example, helper new users by demonstrating how to also remove …
Jonathan Childress authored
571 @uploader.remove!
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
572 end
573
574 context 'the thumb version' do
575 it "should scale down a landscape image to be exactly 64 by 64 pixels" do
576 @uploader.thumb.should have_dimensions(64, 64)
577 end
578 end
579
580 context 'the small version' do
581 it "should scale down a landscape image to fit within 200 by 200 pixels" do
582 @uploader.small.should be_no_larger_than(200, 200)
583 end
584 end
585
586 it "should make the image readable only to the owner and not executable" do
587 @uploader.should have_permissions(0600)
588 end
589 end
590 ```
591
592 Setting the enable_processing flag on an uploader will prevent any of the versions from processing as well.
593 Processing can be enabled for a single version by setting the processing flag on the version like so:
594
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
595 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
596 @uploader.thumb.enable_processing = true
597 ```
598
94fe489 @eavgerinos [Fix #1622] Remove mandatory requiring of Fog gem
eavgerinos authored
599 ## Fog
600
601 If you want to use fog you must add in your CarrierWave initializer the
602 following lines
603
604 ```ruby
0ed1c51 @eavgerinos [Fix 1631] Add proper documentation for fog/aws [skip ci]
eavgerinos authored
605 config.fog_provider = 'fog' # 'fog/aws' etc. Defaults to 'fog'
94fe489 @eavgerinos [Fix #1622] Remove mandatory requiring of Fog gem
eavgerinos authored
606 config.fog_credentials = { ... } # Provider specific credentials
607 ```
608
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
609 ## Using Amazon S3
610
4160daa @bquorning Allow requiring only fog-aws or fog-core
bquorning authored
611 [Fog AWS](http://github.com/fog/fog-aws) is used to support Amazon S3. Ensure you have it in your Gemfile:
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
612
df4b01a @bensie Add notes for putting fog in your Gemfile and specifying the required…
bensie authored
613 ```ruby
4160daa @bquorning Allow requiring only fog-aws or fog-core
bquorning authored
614 gem "fog-aws"
df4b01a @bensie Add notes for putting fog in your Gemfile and specifying the required…
bensie authored
615 ```
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
616
617 You'll need to provide your fog_credentials and a fog_directory (also known as a bucket) in an initializer.
618 For the sake of performance it is assumed that the directory already exists, so please create it if need be.
619 You can also pass in additional options, as documented fully in lib/carrierwave/storage/fog.rb. Here's a full example:
620
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
621 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
622 CarrierWave.configure do |config|
0ed1c51 @eavgerinos [Fix 1631] Add proper documentation for fog/aws [skip ci]
eavgerinos authored
623 config.fog_provider = 'fog/aws' # required
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
624 config.fog_credentials = {
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
625 provider: 'AWS', # required
626 aws_access_key_id: 'xxx', # required
627 aws_secret_access_key: 'yyy', # required
628 region: 'eu-west-1', # optional, defaults to 'us-east-1'
629 host: 's3.example.com', # optional, defaults to nil
630 endpoint: 'https://s3.example.com:8080' # optional, defaults to nil
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
631 }
c59c033 @abatko update README.md wrt Cache-Control max-age
abatko authored
632 config.fog_directory = 'name_of_directory' # required
633 config.fog_public = false # optional, defaults to true
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
634 config.fog_attributes = { 'Cache-Control' => "max-age=#{365.day.to_i}" } # optional, defaults to {}
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
635 end
636 ```
637
638 In your uploader, set the storage to :fog
639
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
640 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
641 class AvatarUploader < CarrierWave::Uploader::Base
642 storage :fog
643 end
644 ```
645
646 That's it! You can still use the `CarrierWave::Uploader#url` method to return the url to the file on Amazon S3.
647
648 ## Using Rackspace Cloud Files
649
df4b01a @bensie Add notes for putting fog in your Gemfile and specifying the required…
bensie authored
650 [Fog](http://github.com/fog/fog) is used to support Rackspace Cloud Files. Ensure you have it in your Gemfile:
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
651
df4b01a @bensie Add notes for putting fog in your Gemfile and specifying the required…
bensie authored
652 ```ruby
1cc2b61 @bensie Don't specify fog versions in readme
bensie authored
653 gem "fog"
df4b01a @bensie Add notes for putting fog in your Gemfile and specifying the required…
bensie authored
654 ```
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
655
656 You'll need to configure a directory (also known as a container), username and API key in the initializer.
657 For the sake of performance it is assumed that the directory already exists, so please create it if need be.
658
6bd46e3 Updating README.md to reflect the new Rackspace region support in fog…
Kyle Rames authored
659 Using a US-based account:
660
661 ```ruby
662 CarrierWave.configure do |config|
014c091 @plribeiro3000 Add more notes to README [skipci]
plribeiro3000 authored
663 config.fog_provider = "fog/rackspace/storage" # optional, defaults to "fog"
6bd46e3 Updating README.md to reflect the new Rackspace region support in fog…
Kyle Rames authored
664 config.fog_credentials = {
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
665 provider: 'Rackspace',
666 rackspace_username: 'xxxxxx',
667 rackspace_api_key: 'yyyyyy',
014c091 @plribeiro3000 Add more notes to README [skipci]
plribeiro3000 authored
668 rackspace_region: :ord # optional, defaults to :dfw
6bd46e3 Updating README.md to reflect the new Rackspace region support in fog…
Kyle Rames authored
669 }
670 config.fog_directory = 'name_of_directory'
671 end
672 ```
673
674 Using a UK-based account:
675
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
676 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
677 CarrierWave.configure do |config|
014c091 @plribeiro3000 Add more notes to README [skipci]
plribeiro3000 authored
678 config.fog_provider = "fog/rackspace/storage" # optional, defaults to "fog"
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
679 config.fog_credentials = {
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
680 provider: 'Rackspace',
681 rackspace_username: 'xxxxxx',
682 rackspace_api_key: 'yyyyyy',
683 rackspace_auth_url: Fog::Rackspace::UK_AUTH_ENDPOINT,
684 rackspace_region: :lon
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
685 }
686 config.fog_directory = 'name_of_directory'
687 end
688 ```
689
690 You can optionally include your CDN host name in the configuration.
691 This is *highly* recommended, as without it every request requires a lookup
692 of this information.
693
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
694 ```ruby
7046c93 @DouweM Rename 'fog_host' config option to 'asset_host' and add support for f…
DouweM authored
695 config.asset_host = "http://c000000.cdn.rackspacecloud.com"
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
696 ```
697
ecdb304 @trevorturk Edited README.md via GitHub
trevorturk authored
698 In your uploader, set the storage to :fog
420be33 Added documentation for using fog with Rackspace UK
Liborio Cannici authored
699
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
700 ```ruby
ecdb304 @trevorturk Edited README.md via GitHub
trevorturk authored
701 class AvatarUploader < CarrierWave::Uploader::Base
702 storage :fog
420be33 Added documentation for using fog with Rackspace UK
Liborio Cannici authored
703 end
704 ```
705
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
706 That's it! You can still use the `CarrierWave::Uploader#url` method to return
707 the url to the file on Rackspace Cloud Files.
708
709 ## Using Google Storage for Developers
710
3cabb21 @plribeiro3000 Improve Fog Loading
plribeiro3000 authored
711 [Fog](http://github.com/fog/fog-google) is used to support Google Storage for Developers. Ensure you have it in your Gemfile:
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
712
df4b01a @bensie Add notes for putting fog in your Gemfile and specifying the required…
bensie authored
713 ```ruby
3cabb21 @plribeiro3000 Improve Fog Loading
plribeiro3000 authored
714 gem "fog-google"
df4b01a @bensie Add notes for putting fog in your Gemfile and specifying the required…
bensie authored
715 ```
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
716
717 You'll need to configure a directory (also known as a bucket), access key id and secret access key in the initializer.
718 For the sake of performance it is assumed that the directory already exists, so please create it if need be.
719
df7f1aa @adz Added google storage credentials reference
adz authored
720 Sign up [here](http://gs-signup-redirect.appspot.com/) and get your credentials [here](https://storage.cloud.google.com/m)
721 under the section “Interoperable Access”.
722
723
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
724 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
725 CarrierWave.configure do |config|
014c091 @plribeiro3000 Add more notes to README [skipci]
plribeiro3000 authored
726 config.fog_provider = 'fog-google' # required
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
727 config.fog_credentials = {
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
728 provider: 'Google',
729 google_storage_access_key_id: 'xxxxxx',
730 google_storage_secret_access_key: 'yyyyyy'
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
731 }
732 config.fog_directory = 'name_of_directory'
733 end
734 ```
735
736 In your uploader, set the storage to :fog
737
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
738 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
739 class AvatarUploader < CarrierWave::Uploader::Base
740 storage :fog
741 end
742 ```
743
744 That's it! You can still use the `CarrierWave::Uploader#url` method to return
745 the url to the file on Google.
746
7269902 @bquorning We don't need to require all of Fog using ~> 1.20
bquorning authored
747 ## Optimized Loading of Fog
748
3cabb21 @plribeiro3000 Improve Fog Loading
plribeiro3000 authored
749 Since Carrierwave doesn't know which parts of Fog you intend to use, it will just load the entire library (unless you use e.g. [`fog-aws`, `fog-google`] instead of fog proper). If you prefer to load fewer classes into your application, you need to load those parts of Fog yourself *before* loading CarrierWave in your Gemfile. Ex:
7269902 @bquorning We don't need to require all of Fog using ~> 1.20
bquorning authored
750
751 ```ruby
3cabb21 @plribeiro3000 Improve Fog Loading
plribeiro3000 authored
752 gem "fog", "~> 1.27", require: "fog/rackspace/storage"
c173d18 @bensie README fix for fog optimized loading, closes #1381
bensie authored
753 gem "carrierwave"
7269902 @bquorning We don't need to require all of Fog using ~> 1.20
bquorning authored
754 ```
755
1e8dfba @kjohnston Clarify optimized loading of fog in readme.
kjohnston authored
756 A couple of notes about versions:
757 * This functionality was introduced in Fog v1.20.
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
758 * This functionality is slated for CarrierWave v1.0.0.
1e8dfba @kjohnston Clarify optimized loading of fog in readme.
kjohnston authored
759
3cabb21 @plribeiro3000 Improve Fog Loading
plribeiro3000 authored
760 If you're not relying on Gemfile entries alone and are requiring "carrierwave" anywhere, ensure you require "fog/rackspace/storage" before it. Ex:
7269902 @bquorning We don't need to require all of Fog using ~> 1.20
bquorning authored
761
762 ```ruby
3cabb21 @plribeiro3000 Improve Fog Loading
plribeiro3000 authored
763 require "fog/rackspace/storage"
1e8dfba @kjohnston Clarify optimized loading of fog in readme.
kjohnston authored
764 require "carrierwave"
7269902 @bquorning We don't need to require all of Fog using ~> 1.20
bquorning authored
765 ```
766
3cabb21 @plribeiro3000 Improve Fog Loading
plribeiro3000 authored
767 Beware that this specific require is only needed when working with a fog provider that was not extracted to its own gem yet.
768 A list of the extracted providers can be found in the page of the `fog` organizations [here](https://github.com/fog).
769
1e8dfba @kjohnston Clarify optimized loading of fog in readme.
kjohnston authored
770 When in doubt, inspect `Fog.constants` to see what has been loaded.
771
7046c93 @DouweM Rename 'fog_host' config option to 'asset_host' and add support for f…
DouweM authored
772 ## Dynamic Asset Host
b1b100a Document dynamic fog_host
Jesse Trimble authored
773
7046c93 @DouweM Rename 'fog_host' config option to 'asset_host' and add support for f…
DouweM authored
774 The `asset_host` config property can be assigned a proc (or anything that responds to `call`) for generating the host dynamically. The proc-compliant object gets an instance of the current `CarrierWave::Storage::Fog::File` or `CarrierWave::SanitizedFile` as its only argument.
b1b100a Document dynamic fog_host
Jesse Trimble authored
775
776 ```ruby
777 CarrierWave.configure do |config|
7046c93 @DouweM Rename 'fog_host' config option to 'asset_host' and add support for f…
DouweM authored
778 config.asset_host = proc do |file|
b1b100a Document dynamic fog_host
Jesse Trimble authored
779 identifier = # some logic
780 "http://#{identifier}.cdn.rackspacecloud.com"
781 end
782 end
783 ```
784
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
785 ## Using RMagick
786
787 If you're uploading images, you'll probably want to manipulate them in some way,
788 you might want to create thumbnail images for example. CarrierWave comes with a
789 small library to make manipulating images with RMagick easier, you'll need to
790 include it in your Uploader:
791
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
792 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
793 class AvatarUploader < CarrierWave::Uploader::Base
794 include CarrierWave::RMagick
795 end
796 ```
797
798 The RMagick module gives you a few methods, like
799 `CarrierWave::RMagick#resize_to_fill` which manipulate the image file in some
800 way. You can set a `process` callback, which will call that method any time a
801 file is uploaded.
a302ac6 @gregwebs fix convert in README
gregwebs authored
802 There is a demonstration of convert here.
803 Convert will only work if the file has the same file extension, thus the use of the filename method.
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
804
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
805 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
806 class AvatarUploader < CarrierWave::Uploader::Base
807 include CarrierWave::RMagick
808
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
809 process resize_to_fill: [200, 200]
810 process convert: 'png'
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
811
812 def filename
a15d4dc @taavo fix custom filename
taavo authored
813 super.chomp(File.extname(super)) + '.png' if original_filename.present?
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
814 end
815 end
816 ```
817
818 Check out the manipulate! method, which makes it easy for you to write your own
819 manipulation methods.
820
821 ## Using MiniMagick
822
823 MiniMagick is similar to RMagick but performs all the operations using the 'mogrify'
824 command which is part of the standard ImageMagick kit. This allows you to have the power
825 of ImageMagick without having to worry about installing all the RMagick libraries.
826
827 See the MiniMagick site for more details:
828
b72aef7 @fgrehm Fix minimagick link on README
fgrehm authored
829 https://github.com/minimagick/minimagick
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
830
831 And the ImageMagick command line options for more for whats on offer:
832
833 http://www.imagemagick.org/script/command-line-options.php
834
835 Currently, the MiniMagick carrierwave processor provides exactly the same methods as
836 for the RMagick processor.
837
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
838 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
839 class AvatarUploader < CarrierWave::Uploader::Base
840 include CarrierWave::MiniMagick
841
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
842 process resize_to_fill: [200, 200]
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
843 end
844 ```
845
81028a4 @eavgerinos Add README usage entries for modules using ruby-filemagic
eavgerinos authored
846 ## Using Filemagic
847
848 [Filemagic](https://github.com/blackwinter/ruby-filemagic) is a gem that
849 provides Ruby bindings to the magic library.
850
851 Since magic is writtern in C, modules using Filemagic are optional and
852 don't work with JRuby.
853
854 ### Extract the actual content-type
855
856 You can use the `MagicMimeTypes` processor to extract the actual
857 content-type of the uploaded file.
858
859 For example, a user can upload a file named `file.png` but its actual
860 content type may be JPEG.
861
862 Below you can see an example usage of `MagicMimeTypes` processor.
863
864 ```ruby
865 class AvatarUploader < CarrierWave::Uploader::Base
866 include CarrierWave::MagicMimeTypes
867
868 process :set_content_type
869 end
870 ```
871
872 ### Validate with the actual content-type
873
874 You can use the `MagicMimeWhitelist` mixin to validate uploaded files
875 given a regexp to match the allowed content types.
876
877 Let's say we need an uploader that accepts only images.
878
879 This can be done like this
880
881 ```ruby
882 class AvatarUploader < CarrierWave::Uploader::Base
883 include CarrierWave::Uploader::MagicMimeWhitelist
884
885 # Override it to your needs.
886 # By default it returns nil and the validator allows every
887 # content-type.
888 def whitelist_mime_type_pattern
889 /image\//
890 end
891 end
892 ```
893
894 There is also a `MagicMimeBlacklist` mixin to validate uploaded files
895 given a rexp to match prohibited content types.
896
897 Let's say we need an uploader that reject json files.
898
899 This can be done like this
900
901 ```ruby
902 class NoJsonUploader < CarrierWave::Uploader::Base
903 include CarrierWave::Uploader::MagicMimeBlacklist
904
905 # Override it to your needs.
906 # By default it returns nil and the validator allows every
907 # content-type.
908 def blacklist_mime_type_pattern
909 /(application|text)/json/
910 end
911 end
912 ```
913
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
914 ## Migrating from Paperclip
915
916 If you are using Paperclip, you can use the provided compatibility module:
917
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
918 ```ruby
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
919 class AvatarUploader < CarrierWave::Uploader::Base
920 include CarrierWave::Compatibility::Paperclip
921 end
922 ```
923
924 See the documentation for `CarrierWave::Compatibility::Paperclip` for more
925 details.
926
927 Be sure to use mount_on to specify the correct column:
928
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
929 ```ruby
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
930 mount_uploader :avatar, AvatarUploader, mount_on: :avatar_file_name
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
931 ```
932
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
933 ## I18n
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
934
935 The Active Record validations use the Rails i18n framework. Add these keys to
936 your translations file:
937
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
938 ```yaml
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
939 errors:
940 messages:
e854b50 @mattmenefee Update README.md
mattmenefee authored
941 carrierwave_processing_error: "Cannot resize image."
942 carrierwave_integrity_error: "Not an image."
943 carrierwave_download_error: "Couldn't download image."
68af4a7 @sunny Add extra I18n translation keys to README
sunny authored
944 extension_white_list_error: "You are not allowed to upload %{extension} files, allowed types: %{allowed_types}"
945 extension_black_list_error: "You are not allowed to upload %{extension} files, prohibited types: %{prohibited_types}"
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
946 ```
947
8b11383 Added documentation for move_to_cache and move_to_store options.
Jason Sydes authored
948 ## Large files
949
950 By default, CarrierWave copies an uploaded file twice, first copying the file into the cache, then
951 copying the file into the store. For large files, this can be prohibitively time consuming.
952
5783c36 @bensie Beging preparing for 0.6.0
bensie authored
953 You may change this behavior by overriding either or both of the `move_to_cache` and
8b11383 Added documentation for move_to_cache and move_to_store options.
Jason Sydes authored
954 `move_to_store` methods:
955
f1de7d4 @ngauthier fix syntax highlighting in README.md
ngauthier authored
956 ```ruby
8b11383 Added documentation for move_to_cache and move_to_store options.
Jason Sydes authored
957 class MyUploader < CarrierWave::Uploader::Base
958 def move_to_cache
959 true
960 end
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
961
8b11383 Added documentation for move_to_cache and move_to_store options.
Jason Sydes authored
962 def move_to_store
963 true
964 end
965 end
966 ```
967
968 When the `move_to_cache` and/or `move_to_store` methods return true, files will be moved (instead of copied) to the cache and store respectively.
969
970 This has only been tested with the local filesystem store.
971
744874b @remiprev Add “Skipping ActiveRecord” callbacks section
remiprev authored
972 ## Skipping ActiveRecord callbacks
973
974 By default, mounting an uploader into an ActiveRecord model will add a few
975 callbacks. For example, this code:
976
977 ```ruby
978 class User
979 mount_uploader :avatar, AvatarUploader
980 end
981 ```
982
983 Will add these callbacks:
984
985 ```ruby
986 after_save :store_avatar!
987 before_save :write_avatar_identifier
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
988 after_commit :remove_avatar!, on: :destroy
989 after_commit :"mark_remove_avatar_false", on: :update
5f9a076 @lacco Update README.md
lacco authored
990 after_save :"store_previous_changes_for_avatar"
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
991 after_commit :remove_previously_stored_avatar, on: :update
744874b @remiprev Add “Skipping ActiveRecord” callbacks section
remiprev authored
992 ```
993
994 If you want to skip any of these callbacks (eg. you want to keep the existing
995 avatar, even after uploading a new one), you can use ActiveRecord’s
996 `skip_callback` method.
997
998 ```ruby
999 class User
1000 mount_uploader :avatar, AvatarUploader
5f9a076 @lacco Update README.md
lacco authored
1001 skip_callback :commit, :after, :remove_previously_stored_avatar
744874b @remiprev Add “Skipping ActiveRecord” callbacks section
remiprev authored
1002 end
1003 ```
1004
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
1005 ## Contributing to CarrierWave
1006
1e87bb5 @bensie Update URLs to carrierwaveuploader/carrierwave
bensie authored
1007 See [CONTRIBUTING.md](https://github.com/carrierwaveuploader/carrierwave/blob/master/CONTRIBUTING.md)
4b6fac0 @thiagofm Better readme?
thiagofm authored
1008
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
1009 ## License
1010
2517d66 @bensie Update README and Travis for upcoming 1.0.0 release
bensie authored
1011 Copyright (c) 2008-2015 Jonas Nicklas
0d2e9ee @bensie Converting Readme to GitHub flavored markdown
bensie authored
1012
1013 Permission is hereby granted, free of charge, to any person obtaining
1014 a copy of this software and associated documentation files (the
1015 "Software"), to deal in the Software without restriction, including
1016 without limitation the rights to use, copy, modify, merge, publish,
1017 distribute, sublicense, and/or sell copies of the Software, and to
1018 permit persons to whom the Software is furnished to do so, subject to
1019 the following conditions:
1020
1021 The above copyright notice and this permission notice shall be
1022 included in all copies or substantial portions of the Software.
1023
1024 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
1025 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
1026 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
1027 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
1028 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
1029 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
1030 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.