carrierwave 0.5.8 → 0.6.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of carrierwave might be problematic. Click here for more details.

data/README.md CHANGED
@@ -24,7 +24,7 @@ Install the latest stable release:
24
24
 
25
25
  In Rails, add it to your Gemfile:
26
26
 
27
- ``` ruby
27
+ ```ruby
28
28
  gem 'carrierwave'
29
29
  ```
30
30
 
@@ -44,7 +44,7 @@ this should give you a file in:
44
44
  Check out this file for some hints on how you can customize your uploader. It
45
45
  should look something like this:
46
46
 
47
- ``` ruby
47
+ ```ruby
48
48
  class AvatarUploader < CarrierWave::Uploader::Base
49
49
  storage :file
50
50
  end
@@ -52,7 +52,7 @@ end
52
52
 
53
53
  You can use your uploader class to store and retrieve files like this:
54
54
 
55
- ``` ruby
55
+ ```ruby
56
56
  uploader = AvatarUploader.new
57
57
 
58
58
  uploader.store!(my_file)
@@ -73,19 +73,19 @@ simply assign files and get going:
73
73
  Make sure you are loading CarrierWave after loading your ORM, otherwise you'll
74
74
  need to require the relevant extension manually, e.g.:
75
75
 
76
- ``` ruby
76
+ ```ruby
77
77
  require 'carrierwave/orm/activerecord'
78
78
  ```
79
79
 
80
80
  Add a string column to the model you want to mount the uploader on:
81
81
 
82
- ``` ruby
82
+ ```ruby
83
83
  add_column :users, :avatar, :string
84
84
  ```
85
85
 
86
86
  Open your model file and mount the uploader:
87
87
 
88
- ``` ruby
88
+ ```ruby
89
89
  class User < ActiveRecord::Base
90
90
  mount_uploader :avatar, AvatarUploader
91
91
  end
@@ -94,14 +94,14 @@ end
94
94
  Now you can cache files by assigning them to the attribute, they will
95
95
  automatically be stored when the record is saved.
96
96
 
97
- ``` ruby
97
+ ```ruby
98
98
  u = User.new
99
99
  u.avatar = params[:file]
100
100
  u.avatar = File.open('somewhere')
101
101
  u.save!
102
102
  u.avatar.url # => '/url/to/file.png'
103
103
  u.avatar.current_path # => 'path/to/file.png'
104
- u.avatar_identifier # => 'file.png'
104
+ u.avatar.identifier # => 'file.png'
105
105
  ```
106
106
 
107
107
  ### DataMapper, Mongoid, Sequel
@@ -119,7 +119,7 @@ There are more extensions listed in [the wiki](https://github.com/jnicklas/carri
119
119
  In order to change where uploaded files are put, just override the `store_dir`
120
120
  method:
121
121
 
122
- ``` ruby
122
+ ```ruby
123
123
  class MyUploader < CarrierWave::Uploader::Base
124
124
  def store_dir
125
125
  'public/my/upload/directory'
@@ -139,7 +139,7 @@ allowed extensions.
139
139
  If you're mounting the uploader, uploading a file with the wrong extension will
140
140
  make the record invalid instead. Otherwise, an error is raised.
141
141
 
142
- ``` ruby
142
+ ```ruby
143
143
  class MyUploader < CarrierWave::Uploader::Base
144
144
  def extension_white_list
145
145
  %w(jpg jpeg gif png)
@@ -159,14 +159,14 @@ all *non*-allowed symbols.
159
159
  With Ruby 1.9 and higher you can simply write (as it has [Oniguruma](http://oniguruma.rubyforge.org/oniguruma/)
160
160
  built-in):
161
161
 
162
- ``` ruby
162
+ ```ruby
163
163
  CarrierWave::SanitizedFile.sanitize_regexp = /[^[:word:]\.\-\+]/
164
164
  ```
165
165
 
166
166
  With Ruby 1.8 you have to manually specify all character ranges. For example, for files which may
167
167
  contain Russian letters:
168
168
 
169
- ``` ruby
169
+ ```ruby
170
170
  CarrierWave::SanitizedFile.sanitize_regexp = /[^a-zA-Zа-яА-ЯёЁ0-9\.\-\+_]/u
171
171
  ```
172
172
 
@@ -180,7 +180,7 @@ as expected, you can configure your uploaders to use `CarrierWave::MimeTypes`.
180
180
  This adds a dependency on the [mime-types](http://rubygems.org/gems/mime-types) gem,
181
181
  but is recommended when using fog, and fog already has a dependency on mime-types.
182
182
 
183
- ``` ruby
183
+ ```ruby
184
184
  require 'carrierwave/processing/mime_types'
185
185
 
186
186
  class MyUploader < CarrierWave::Uploader::Base
@@ -195,7 +195,7 @@ end
195
195
  Often you'll want to add different versions of the same file. The classic
196
196
  example is image thumbnails. There is built in support for this:
197
197
 
198
- ``` ruby
198
+ ```ruby
199
199
  class MyUploader < CarrierWave::Uploader::Base
200
200
  include CarrierWave::RMagick
201
201
 
@@ -212,7 +212,7 @@ When this uploader is used, an uploaded image would be scaled to be no larger
212
212
  than 800 by 800 pixels. A version called thumb is then created, which is scaled
213
213
  and cropped to exactly 200 by 200 pixels. The uploader could be used like this:
214
214
 
215
- ``` ruby
215
+ ```ruby
216
216
  uploader = AvatarUploader.new
217
217
  uploader.store!(my_file) # size: 1024x768
218
218
 
@@ -225,7 +225,7 @@ created. This can cut down on processing cost.
225
225
 
226
226
  It is possible to nest versions within versions:
227
227
 
228
- ``` ruby
228
+ ```ruby
229
229
  class MyUploader < CarrierWave::Uploader::Base
230
230
 
231
231
  version :animal do
@@ -241,7 +241,7 @@ end
241
241
  Occasionally you want to restrict the creation of versions on certain
242
242
  properties within the model or based on the picture itself.
243
243
 
244
- ``` ruby
244
+ ```ruby
245
245
  class MyUploader < CarrierWave::Uploader::Base
246
246
 
247
247
  version :human, :if => :is_human?
@@ -253,21 +253,45 @@ protected
253
253
  def is_human? picture
254
254
  model.can_program?(:ruby)
255
255
  end
256
-
256
+
257
257
  def is_monkey? picture
258
258
  model.favorite_food == 'banana'
259
259
  end
260
-
260
+
261
261
  def is_landscape? picture
262
262
  image = MiniMagick::Image.open(picture.path)
263
263
  image[:width] > image[:height]
264
264
  end
265
-
265
+
266
266
  end
267
267
  ```
268
268
 
269
269
  The `model` variable points to the instance object the uploader is attached to.
270
270
 
271
+ ### Create versions from existing versions
272
+
273
+ For performance reasons, it is often useful to create versions from existing ones
274
+ instead of using the original file. If your uploader generates several versions
275
+ where the next is smaller than the last, it will take less time to generate from
276
+ a smaller, already processed image.
277
+
278
+ ```ruby
279
+ class MyUploader < CarrierWave::Uploader::Base
280
+
281
+ version :thumb do
282
+ process resize_to_fill: [280, 280]
283
+ end
284
+
285
+ version :small_thumb, :from_version => :thumb do
286
+ process resize_to_fill: [20, 20]
287
+ end
288
+
289
+ end
290
+ ```
291
+
292
+ The option `:from_version` uses the file cached in the `:thumb` version instead
293
+ of the original version, potentially resulting in faster processing.
294
+
271
295
  ## Making uploads work across form redisplays
272
296
 
273
297
  Often you'll notice that uploaded files disappear when a validation fails.
@@ -276,7 +300,7 @@ in that case. Suppose your `user` model has an uploader mounted on `avatar`
276
300
  file, just add a hidden field called `avatar_cache`. In Rails, this would look
277
301
  like this:
278
302
 
279
- ``` erb
303
+ ```erb
280
304
  <%= form_for @user, :html => {:multipart => true} do |f| %>
281
305
  <p>
282
306
  <label>My Avatar</label>
@@ -289,7 +313,7 @@ like this:
289
313
  It might be a good idea to show the user that a file has been uploaded, in the
290
314
  case of images, a small thumbnail would be a good indicator:
291
315
 
292
- ``` erb
316
+ ```erb
293
317
  <%= form_for @user, :html => {:multipart => true} do |f| %>
294
318
  <p>
295
319
  <label>My Avatar</label>
@@ -305,7 +329,7 @@ case of images, a small thumbnail would be a good indicator:
305
329
  If you want to remove a previously uploaded file on a mounted uploader, you can
306
330
  easily add a checkbox to the form which will remove the file when checked.
307
331
 
308
- ``` erb
332
+ ```erb
309
333
  <%= form_for @user, :html => {:multipart => true} do |f| %>
310
334
  <p>
311
335
  <label>My Avatar</label>
@@ -330,7 +354,7 @@ Your users may find it convenient to upload a file from a location on the Intern
330
354
  via a URL. CarrierWave makes this simple, just add the appropriate attribute to your
331
355
  form and you're good to go:
332
356
 
333
- ``` erb
357
+ ```erb
334
358
  <%= form_for @user, :html => {:multipart => true} do |f| %>
335
359
  <p>
336
360
  <label>My Avatar URL:</label>
@@ -346,7 +370,7 @@ In many cases, especially when working with images, it might be a good idea to
346
370
  provide a default url, a fallback in case no file has been uploaded. You can do
347
371
  this easily by overriding the `default_url` method in your uploader:
348
372
 
349
- ``` ruby
373
+ ```ruby
350
374
  class MyUploader < CarrierWave::Uploader::Base
351
375
  def default_url
352
376
  "/images/fallback/" + [version_name, "default.png"].compact.join('_')
@@ -361,14 +385,14 @@ or add a new one. You can use the recreate_versions! method to recreate the
361
385
  versions from the base file. This uses a naive approach which will re-upload and
362
386
  process all versions.
363
387
 
364
- ``` ruby
388
+ ```ruby
365
389
  instance = MyUploader.new
366
390
  instance.recreate_versions!
367
391
  ```
368
392
 
369
393
  Or on a mounted uploader:
370
394
 
371
- ``` ruby
395
+ ```ruby
372
396
  User.all.each do |user|
373
397
  user.avatar.recreate_versions!
374
398
  end
@@ -379,16 +403,16 @@ end
379
403
  CarrierWave has a broad range of configuration options, which you can configure,
380
404
  both globally and on a per-uploader basis:
381
405
 
382
- ``` ruby
406
+ ```ruby
383
407
  CarrierWave.configure do |config|
384
408
  config.permissions = 0666
385
- config.storage = :s3
409
+ config.storage = :file
386
410
  end
387
411
  ```
388
412
 
389
413
  Or alternatively:
390
414
 
391
- ``` ruby
415
+ ```ruby
392
416
  class AvatarUploader < CarrierWave::Uploader::Base
393
417
  permissions 0777
394
418
  end
@@ -396,7 +420,7 @@ end
396
420
 
397
421
  If you're using Rails, create an initializer for this:
398
422
 
399
- ``` ruby
423
+ ```ruby
400
424
  config/initializers/carrierwave.rb
401
425
  ```
402
426
 
@@ -406,7 +430,7 @@ It's a good idea to test you uploaders in isolation. In order to speed up your
406
430
  tests, it's recommended to switch off processing in your tests, and to use the
407
431
  file storage. In Rails you could do that by adding an initializer with:
408
432
 
409
- ``` ruby
433
+ ```ruby
410
434
  if Rails.env.test? or Rails.env.cucumber?
411
435
  CarrierWave.configure do |config|
412
436
  config.storage = :file
@@ -420,7 +444,7 @@ processing only for those tests that need it.
420
444
 
421
445
  CarrierWave comes with some RSpec matchers which you may find useful:
422
446
 
423
- ``` ruby
447
+ ```ruby
424
448
  require 'carrierwave/test/matchers'
425
449
 
426
450
  describe MyUploader do
@@ -434,6 +458,7 @@ describe MyUploader do
434
458
 
435
459
  after do
436
460
  MyUploader.enable_processing = false
461
+ @uploader.remove!
437
462
  end
438
463
 
439
464
  context 'the thumb version' do
@@ -457,13 +482,13 @@ end
457
482
  Setting the enable_processing flag on an uploader will prevent any of the versions from processing as well.
458
483
  Processing can be enabled for a single version by setting the processing flag on the version like so:
459
484
 
460
- ``` ruby
485
+ ```ruby
461
486
  @uploader.thumb.enable_processing = true
462
487
  ```
463
488
 
464
489
  ## Using Amazon S3
465
490
 
466
- [Fog](http://github.com/geemus/fog) is used to support Amazon S3. Ensure you have it installed:
491
+ [Fog](http://github.com/fog/fog) is used to support Amazon S3. Ensure you have it installed:
467
492
 
468
493
  gem install fog
469
494
 
@@ -471,7 +496,7 @@ You'll need to provide your fog_credentials and a fog_directory (also known as a
471
496
  For the sake of performance it is assumed that the directory already exists, so please create it if need be.
472
497
  You can also pass in additional options, as documented fully in lib/carrierwave/storage/fog.rb. Here's a full example:
473
498
 
474
- ``` ruby
499
+ ```ruby
475
500
  CarrierWave.configure do |config|
476
501
  config.fog_credentials = {
477
502
  :provider => 'AWS', # required
@@ -488,7 +513,7 @@ end
488
513
 
489
514
  In your uploader, set the storage to :fog
490
515
 
491
- ``` ruby
516
+ ```ruby
492
517
  class AvatarUploader < CarrierWave::Uploader::Base
493
518
  storage :fog
494
519
  end
@@ -498,14 +523,14 @@ That's it! You can still use the `CarrierWave::Uploader#url` method to return th
498
523
 
499
524
  ## Using Rackspace Cloud Files
500
525
 
501
- [Fog](http://github.com/geemus/fog) is used to support Rackspace Cloud Files. Ensure you have it installed:
526
+ [Fog](http://github.com/fog/fog) is used to support Rackspace Cloud Files. Ensure you have it installed:
502
527
 
503
528
  gem install fog
504
529
 
505
530
  You'll need to configure a directory (also known as a container), username and API key in the initializer.
506
531
  For the sake of performance it is assumed that the directory already exists, so please create it if need be.
507
532
 
508
- ``` ruby
533
+ ```ruby
509
534
  CarrierWave.configure do |config|
510
535
  config.fog_credentials = {
511
536
  :provider => 'Rackspace',
@@ -520,20 +545,13 @@ You can optionally include your CDN host name in the configuration.
520
545
  This is *highly* recommended, as without it every request requires a lookup
521
546
  of this information.
522
547
 
523
- ``` ruby
548
+ ```ruby
524
549
  config.fog_host = "http://c000000.cdn.rackspacecloud.com"
525
550
  ```
526
551
 
527
- The UK Rackspace Cloud doesn’t have the same auth server as the US Cloud.
528
- In case you are using Rackspace UK, you have to adjust the Auth URL:
529
-
530
- ``` ruby
531
- config.rackspace_auth_url = 'lon.auth.api.rackspacecloud.com'
532
- ```
533
-
534
552
  In your uploader, set the storage to :fog
535
553
 
536
- ``` ruby
554
+ ```ruby
537
555
  class AvatarUploader < CarrierWave::Uploader::Base
538
556
  storage :fog
539
557
  end
@@ -544,14 +562,14 @@ the url to the file on Rackspace Cloud Files.
544
562
 
545
563
  ## Using Google Storage for Developers
546
564
 
547
- [Fog](http://github.com/geemus/fog) is used to support Google Storage for Developers. Ensure you have it installed:
565
+ [Fog](http://github.com/fog/fog) is used to support Google Storage for Developers. Ensure you have it installed:
548
566
 
549
567
  gem install fog
550
568
 
551
569
  You'll need to configure a directory (also known as a bucket), access key id and secret access key in the initializer.
552
570
  For the sake of performance it is assumed that the directory already exists, so please create it if need be.
553
571
 
554
- ``` ruby
572
+ ```ruby
555
573
  CarrierWave.configure do |config|
556
574
  config.fog_credentials = {
557
575
  :provider => 'Google',
@@ -564,7 +582,7 @@ end
564
582
 
565
583
  In your uploader, set the storage to :fog
566
584
 
567
- ``` ruby
585
+ ```ruby
568
586
  class AvatarUploader < CarrierWave::Uploader::Base
569
587
  storage :fog
570
588
  end
@@ -573,6 +591,19 @@ end
573
591
  That's it! You can still use the `CarrierWave::Uploader#url` method to return
574
592
  the url to the file on Google.
575
593
 
594
+ ## Dynamic Fog Host
595
+
596
+ The `fog_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` as its only argument.
597
+
598
+ ```ruby
599
+ CarrierWave.configure do |config|
600
+ config.fog_host = proc do |file|
601
+ identifier = # some logic
602
+ "http://#{identifier}.cdn.rackspacecloud.com"
603
+ end
604
+ end
605
+ ```
606
+
576
607
  ## Using RMagick
577
608
 
578
609
  If you're uploading images, you'll probably want to manipulate them in some way,
@@ -580,7 +611,7 @@ you might want to create thumbnail images for example. CarrierWave comes with a
580
611
  small library to make manipulating images with RMagick easier, you'll need to
581
612
  include it in your Uploader:
582
613
 
583
- ``` ruby
614
+ ```ruby
584
615
  class AvatarUploader < CarrierWave::Uploader::Base
585
616
  include CarrierWave::RMagick
586
617
  end
@@ -593,7 +624,7 @@ file is uploaded.
593
624
  There is a demonstration of convert here.
594
625
  Convert will only work if the file has the same file extension, thus the use of the filename method.
595
626
 
596
- ``` ruby
627
+ ```ruby
597
628
  class AvatarUploader < CarrierWave::Uploader::Base
598
629
  include CarrierWave::RMagick
599
630
 
@@ -626,7 +657,7 @@ http://www.imagemagick.org/script/command-line-options.php
626
657
  Currently, the MiniMagick carrierwave processor provides exactly the same methods as
627
658
  for the RMagick processor.
628
659
 
629
- ``` ruby
660
+ ```ruby
630
661
  class AvatarUploader < CarrierWave::Uploader::Base
631
662
  include CarrierWave::MiniMagick
632
663
 
@@ -638,7 +669,7 @@ end
638
669
 
639
670
  If you are using Paperclip, you can use the provided compatibility module:
640
671
 
641
- ``` ruby
672
+ ```ruby
642
673
  class AvatarUploader < CarrierWave::Uploader::Base
643
674
  include CarrierWave::Compatibility::Paperclip
644
675
  end
@@ -649,7 +680,7 @@ details.
649
680
 
650
681
  Be sure to use mount_on to specify the correct column:
651
682
 
652
- ``` ruby
683
+ ```ruby
653
684
  mount_uploader :avatar, AvatarUploader, :mount_on => :avatar_file_name
654
685
  ```
655
686
 
@@ -662,7 +693,7 @@ happily accepted.
662
693
  The Active Record validations use the Rails i18n framework. Add these keys to
663
694
  your translations file:
664
695
 
665
- ``` yaml
696
+ ```yaml
666
697
  errors:
667
698
  messages:
668
699
  carrierwave_processing_error: 'Cannot resize image.'
@@ -674,10 +705,10 @@ errors:
674
705
  By default, CarrierWave copies an uploaded file twice, first copying the file into the cache, then
675
706
  copying the file into the store. For large files, this can be prohibitively time consuming.
676
707
 
677
- You may change this behavior by overriding either or both of the `move_to_cache` and
708
+ You may change this behavior by overriding either or both of the `move_to_cache` and
678
709
  `move_to_store` methods:
679
710
 
680
- ``` ruby
711
+ ```ruby
681
712
  class MyUploader < CarrierWave::Uploader::Base
682
713
  def move_to_cache
683
714
  true
@@ -708,7 +739,7 @@ You should now be able to run the local tests:
708
739
 
709
740
  You can also run the remote specs by creating a ~/.fog file:
710
741
 
711
- ``` yaml
742
+ ```yaml
712
743
  :carrierwave:
713
744
  :aws_access_key_id: xxx
714
745
  :aws_secret_access_key: yyy
@@ -726,7 +757,7 @@ Please test with the latest Ruby 1.8.x and 1.9.x versions using RVM if possible.
726
757
 
727
758
  ## License
728
759
 
729
- Copyright (c) 2008 Jonas Nicklas
760
+ Copyright (c) 2008-2012 Jonas Nicklas
730
761
 
731
762
  Permission is hereby granted, free of charge, to any person obtaining
732
763
  a copy of this software and associated documentation files (the