thorsson_carrierwave 0.4.5

Sign up to get free protection for your applications and to get access to all the features.
Files changed (109) hide show
  1. data/Generators +4 -0
  2. data/History.txt +125 -0
  3. data/Manifest.txt +111 -0
  4. data/README.rdoc +528 -0
  5. data/Rakefile +39 -0
  6. data/cucumber.yml +2 -0
  7. data/features/caching.feature +28 -0
  8. data/features/download.feature +20 -0
  9. data/features/file_storage.feature +37 -0
  10. data/features/file_storage_overridden_filename.feature +38 -0
  11. data/features/file_storage_overridden_store_dir.feature +38 -0
  12. data/features/file_storage_reversing_processor.feature +43 -0
  13. data/features/fixtures/bork.txt +1 -0
  14. data/features/fixtures/monkey.txt +1 -0
  15. data/features/grid_fs_storage.feature +32 -0
  16. data/features/mount_activerecord.feature +46 -0
  17. data/features/mount_datamapper.feature +46 -0
  18. data/features/step_definitions/activerecord_steps.rb +22 -0
  19. data/features/step_definitions/caching_steps.rb +14 -0
  20. data/features/step_definitions/datamapper_steps.rb +29 -0
  21. data/features/step_definitions/download_steps.rb +4 -0
  22. data/features/step_definitions/file_steps.rb +53 -0
  23. data/features/step_definitions/general_steps.rb +85 -0
  24. data/features/step_definitions/mount_steps.rb +19 -0
  25. data/features/step_definitions/store_steps.rb +18 -0
  26. data/features/support/activerecord.rb +30 -0
  27. data/features/support/datamapper.rb +7 -0
  28. data/features/support/env.rb +22 -0
  29. data/features/versions_basics.feature +50 -0
  30. data/features/versions_nested_versions.feature +70 -0
  31. data/features/versions_overridden_filename.feature +51 -0
  32. data/features/versions_overriden_store_dir.feature +41 -0
  33. data/lib/carrierwave/compatibility/paperclip.rb +95 -0
  34. data/lib/carrierwave/core_ext/blank.rb +46 -0
  35. data/lib/carrierwave/core_ext/inheritable_attributes.rb +104 -0
  36. data/lib/carrierwave/core_ext/module_setup.rb +51 -0
  37. data/lib/carrierwave/mount.rb +359 -0
  38. data/lib/carrierwave/orm/activerecord.rb +73 -0
  39. data/lib/carrierwave/orm/datamapper.rb +27 -0
  40. data/lib/carrierwave/orm/mongoid.rb +23 -0
  41. data/lib/carrierwave/orm/mongomapper.rb +27 -0
  42. data/lib/carrierwave/orm/sequel.rb +45 -0
  43. data/lib/carrierwave/processing/image_science.rb +101 -0
  44. data/lib/carrierwave/processing/mini_magick.rb +265 -0
  45. data/lib/carrierwave/processing/rmagick.rb +282 -0
  46. data/lib/carrierwave/sanitized_file.rb +273 -0
  47. data/lib/carrierwave/storage/abstract.rb +30 -0
  48. data/lib/carrierwave/storage/cloud_files.rb +169 -0
  49. data/lib/carrierwave/storage/file.rb +48 -0
  50. data/lib/carrierwave/storage/grid_fs.rb +97 -0
  51. data/lib/carrierwave/storage/right_s3.rb +167 -0
  52. data/lib/carrierwave/storage/s3.rb +199 -0
  53. data/lib/carrierwave/test/matchers.rb +128 -0
  54. data/lib/carrierwave/uploader/cache.rb +145 -0
  55. data/lib/carrierwave/uploader/callbacks.rb +42 -0
  56. data/lib/carrierwave/uploader/configuration.rb +130 -0
  57. data/lib/carrierwave/uploader/default_url.rb +19 -0
  58. data/lib/carrierwave/uploader/download.rb +59 -0
  59. data/lib/carrierwave/uploader/extension_whitelist.rb +37 -0
  60. data/lib/carrierwave/uploader/mountable.rb +39 -0
  61. data/lib/carrierwave/uploader/processing.rb +83 -0
  62. data/lib/carrierwave/uploader/proxy.rb +62 -0
  63. data/lib/carrierwave/uploader/remove.rb +22 -0
  64. data/lib/carrierwave/uploader/store.rb +89 -0
  65. data/lib/carrierwave/uploader/url.rb +33 -0
  66. data/lib/carrierwave/uploader/versions.rb +146 -0
  67. data/lib/carrierwave/uploader.rb +44 -0
  68. data/lib/carrierwave.rb +99 -0
  69. data/merb_generators/uploader_generator.rb +22 -0
  70. data/rails_generators/uploader/USAGE +2 -0
  71. data/rails_generators/uploader/templates/uploader.rb +47 -0
  72. data/rails_generators/uploader/uploader_generator.rb +21 -0
  73. data/script/console +10 -0
  74. data/script/destroy +14 -0
  75. data/script/generate +14 -0
  76. data/spec/compatibility/paperclip_spec.rb +52 -0
  77. data/spec/fixtures/bork.txt +1 -0
  78. data/spec/fixtures/landscape.jpg +0 -0
  79. data/spec/fixtures/portrait.jpg +0 -0
  80. data/spec/fixtures/test.jpeg +1 -0
  81. data/spec/fixtures/test.jpg +1 -0
  82. data/spec/mount_spec.rb +538 -0
  83. data/spec/orm/activerecord_spec.rb +271 -0
  84. data/spec/orm/datamapper_spec.rb +168 -0
  85. data/spec/orm/mongoid_spec.rb +202 -0
  86. data/spec/orm/mongomapper_spec.rb +202 -0
  87. data/spec/orm/sequel_spec.rb +183 -0
  88. data/spec/processing/image_science_spec.rb +56 -0
  89. data/spec/processing/mini_magick_spec.rb +76 -0
  90. data/spec/processing/rmagick_spec.rb +75 -0
  91. data/spec/sanitized_file_spec.rb +623 -0
  92. data/spec/spec_helper.rb +92 -0
  93. data/spec/storage/grid_fs_spec.rb +83 -0
  94. data/spec/storage/right_s3_spec.rb +83 -0
  95. data/spec/storage/s3_spec.rb +95 -0
  96. data/spec/uploader/cache_spec.rb +209 -0
  97. data/spec/uploader/configuration_spec.rb +105 -0
  98. data/spec/uploader/default_url_spec.rb +85 -0
  99. data/spec/uploader/download_spec.rb +75 -0
  100. data/spec/uploader/extension_whitelist_spec.rb +44 -0
  101. data/spec/uploader/mountable_spec.rb +33 -0
  102. data/spec/uploader/paths_spec.rb +22 -0
  103. data/spec/uploader/processing_spec.rb +73 -0
  104. data/spec/uploader/proxy_spec.rb +54 -0
  105. data/spec/uploader/remove_spec.rb +70 -0
  106. data/spec/uploader/store_spec.rb +264 -0
  107. data/spec/uploader/url_spec.rb +102 -0
  108. data/spec/uploader/versions_spec.rb +298 -0
  109. metadata +436 -0
data/Generators ADDED
@@ -0,0 +1,4 @@
1
+ scope 'merb-gen' do
2
+ dir = File.join(File.dirname(__FILE__), 'merb_generators/')
3
+ Merb.add_generators dir + 'uploader_generator'
4
+ end
data/History.txt ADDED
@@ -0,0 +1,125 @@
1
+ === Version 0.4.5 2010-02-20
2
+
3
+ * [added] Support for Rackspace Cloudfiles
4
+ * [added] GridFS now accepts a port
5
+ * [fixed] s3_headers is now properly initialized
6
+ * [fixed] work around DataMapper's patching of core method
7
+
8
+ === Version 0.4.4 2010-01-31
9
+
10
+ * [added] Support for downloading remote files
11
+ * [added] CarrierWave.clean_cached_files! to remove old cached files
12
+ * [added] Option to set headers for S3
13
+ * [added] GridStore now has authentication
14
+ * [fixed] Rmagick convert method now does what it says
15
+ * [fixed] Content type is stored on GridStore and Amazon S3
16
+ * [fixed] Metadata is no longer broken for S3
17
+
18
+ === Version 0.4.3 2009-12-19
19
+
20
+ * [fixed] cnamed URLs on S3 no longer have a third slash after http
21
+ * [fixed] fixed deprecation warnings on Rails 2.3.5
22
+
23
+ === Version 0.4.2 2009-11-26
24
+
25
+ * [added] RightAWS as an alternative S3 implementation
26
+ * [added] An option to enable/disable processing for tests
27
+ * [added] Mongoid ORM support
28
+ * [fixed] DataMapper now works both with and without dm-validations
29
+
30
+ === Version 0.4.1 2009-10-26
31
+
32
+ * [changed] Major changes to the ImageScience module, it actually works now!
33
+ * [fixed] Bug in configuration where it complais that it can't dup Symbol
34
+
35
+ * [removed] Support for Sequel < 2.12
36
+ * [removed] `crop_resized` and `resize` aliases in RMagick, use `resize_to_fill` and `resize_to_fit` respectively
37
+
38
+ === Version 0.4.0 2009-10-12
39
+
40
+ * [changed] the `public` option has been renamed `root` and the old `root` option was removed. No more ambiguity.
41
+ * [changed] Major *breaking* changes to the configuration syntax.
42
+
43
+ * [removed] support for `default_path`
44
+ * [removed] the `cache_to_cache_dir` option
45
+ * [removed] storage no longer calls `setup!` on storage engines
46
+
47
+ * [added] Support for MongoDB's GridFS store
48
+
49
+ === Version 0.3.4 2009-09-01
50
+
51
+ * [added] `default_url` as a replacement for `default_path`
52
+ * [deprecated] `default_path` is deprecated
53
+
54
+ === Version 0.3.4 2009-08-31
55
+
56
+ * [fixed] Deleting no longer causes TypeError in MongoMapper
57
+
58
+ === Version 0.3.3 2009-08-29
59
+
60
+ * [added] Support for MongoMapper
61
+ * [added] Support for CNamed Bucket URLs for Amazon S3
62
+
63
+ === Version 0.3.2 2009-07-18
64
+
65
+ Incremental upgrade
66
+
67
+ * [added] Ruby 1.9 compatibility
68
+ * [changed] Added Object#blank? implementation into CarrierWave, which removes any dpendencies on external libraries (extlib/activesupport)
69
+ * [fixed] Performance issues with S3 support
70
+ * [fixed] Sequel support for newer verions of Sequel (thanks Pavel!)
71
+
72
+ === Version 0.3.1 2009-07-01
73
+
74
+ A bugfix release. Drop in compatible with 0.3.0.
75
+
76
+ * [fixed] Saving a record with a mounted Uploader no longer removes uploaded file
77
+ * [fixed] The file returned by S3 storage now has the path set to the full store path
78
+ * [added] File returned by S3 storage now responds to S3 specific methods
79
+
80
+ === 0.3 2009-06-20
81
+
82
+ This is a stabilization release. Most features are now working as expected and
83
+ most bugs should be fixed.
84
+
85
+ * [changed] Reworked how storage engines work, some internal API changes
86
+ * [added] Macro-like methods for RMagick, no need to call #process any more!
87
+ * [added] Ability to super to any Mount method
88
+ * [fixed] Sequel support should now work as expected
89
+ * [fixed] ActiveRecord no longer saves the record twice
90
+ * [added] Added convenient macro style class methods to rmagick processing
91
+
92
+ === 0.2.4 2009-06-11
93
+
94
+ * [added] `resize_to_limit` method for rmagick
95
+ * [added] Now deletes files from Amazon S3 when record is destroyed
96
+
97
+ === 0.2.3 2009-05-13
98
+
99
+ * [changed] Mount now no longer returns nil if there is no stored file, it returns a blank uploader instead
100
+ * [added] Possibility to specify a default path
101
+ * [added] Paperclip compatibility module
102
+
103
+ === 0.2.1 2009-05-01
104
+
105
+ * [changed] Url method now optionally takes versions as parameters (like Paperclip)
106
+ * [added] A field which allows files to be removed with a checkbox in mount
107
+ * [added] Mount_on option for Mount, to be able to override the serialization column
108
+ * [added] Added demeter friendly column_url method to Mount
109
+ * [added] Option to not copy files to cache dir, to prevent writes on read only fs systems (this is a workaround and needs a better solution)
110
+
111
+
112
+ === 0.2 2009-04-15
113
+
114
+ * [changed] The version is no longer stored in the store dir. This will break the paths for files uploaded with 0.1
115
+ * [changed] CarrierWave::Uploader is now a module, not a class, so you need to include it, not inherit from it.
116
+ * [added] Integiry checking in uploaders via a white list of extensions
117
+ * [added] Validations for integrity and processing in ActiveRecord, activated by default
118
+ * [added] Support for nested versions
119
+ * [added] Permissions option to set the permissions of the uploaded files
120
+ * [added] Support for Sequel
121
+ * [added] CarrierWave::Uploader#read to read the contents of the uploaded files
122
+
123
+ === 0.1 2009-03-12
124
+
125
+ This is a very experimental release that has not been well tested. All of the major features are in place though. Please note that there currently is a bug with load paths in Merb, which means you need to manually require uploaders.
data/Manifest.txt ADDED
@@ -0,0 +1,111 @@
1
+ Generators
2
+ History.txt
3
+ Manifest.txt
4
+ README.rdoc
5
+ Rakefile
6
+ carrierwave.gemspec
7
+ cucumber.yml
8
+ features/caching.feature
9
+ features/download.feature
10
+ features/file_storage.feature
11
+ features/file_storage_overridden_filename.feature
12
+ features/file_storage_overridden_store_dir.feature
13
+ features/file_storage_reversing_processor.feature
14
+ features/fixtures/bork.txt
15
+ features/fixtures/monkey.txt
16
+ features/grid_fs_storage.feature
17
+ features/mount_activerecord.feature
18
+ features/mount_datamapper.feature
19
+ features/step_definitions/activerecord_steps.rb
20
+ features/step_definitions/caching_steps.rb
21
+ features/step_definitions/datamapper_steps.rb
22
+ features/step_definitions/download_steps.rb
23
+ features/step_definitions/file_steps.rb
24
+ features/step_definitions/general_steps.rb
25
+ features/step_definitions/mount_steps.rb
26
+ features/step_definitions/store_steps.rb
27
+ features/support/activerecord.rb
28
+ features/support/datamapper.rb
29
+ features/support/env.rb
30
+ features/versions_basics.feature
31
+ features/versions_nested_versions.feature
32
+ features/versions_overridden_filename.feature
33
+ features/versions_overriden_store_dir.feature
34
+ lib/carrierwave.rb
35
+ lib/carrierwave/compatibility/paperclip.rb
36
+ lib/carrierwave/core_ext/blank.rb
37
+ lib/carrierwave/core_ext/file.rb
38
+ lib/carrierwave/core_ext/inheritable_attributes.rb
39
+ lib/carrierwave/core_ext/module_setup.rb
40
+ lib/carrierwave/mount.rb
41
+ lib/carrierwave/orm/activerecord.rb
42
+ lib/carrierwave/orm/datamapper.rb
43
+ lib/carrierwave/orm/mongoid.rb
44
+ lib/carrierwave/orm/mongomapper.rb
45
+ lib/carrierwave/orm/sequel.rb
46
+ lib/carrierwave/processing/image_science.rb
47
+ lib/carrierwave/processing/mini_magick.rb
48
+ lib/carrierwave/processing/rmagick.rb
49
+ lib/carrierwave/sanitized_file.rb
50
+ lib/carrierwave/storage/abstract.rb
51
+ lib/carrierwave/storage/cloud_files.rb
52
+ lib/carrierwave/storage/file.rb
53
+ lib/carrierwave/storage/grid_fs.rb
54
+ lib/carrierwave/storage/right_s3.rb
55
+ lib/carrierwave/storage/s3.rb
56
+ lib/carrierwave/test/matchers.rb
57
+ lib/carrierwave/uploader.rb
58
+ lib/carrierwave/uploader/cache.rb
59
+ lib/carrierwave/uploader/callbacks.rb
60
+ lib/carrierwave/uploader/configuration.rb
61
+ lib/carrierwave/uploader/default_url.rb
62
+ lib/carrierwave/uploader/download.rb
63
+ lib/carrierwave/uploader/extension_whitelist.rb
64
+ lib/carrierwave/uploader/mountable.rb
65
+ lib/carrierwave/uploader/processing.rb
66
+ lib/carrierwave/uploader/proxy.rb
67
+ lib/carrierwave/uploader/remove.rb
68
+ lib/carrierwave/uploader/store.rb
69
+ lib/carrierwave/uploader/url.rb
70
+ lib/carrierwave/uploader/versions.rb
71
+ merb_generators/uploader_generator.rb
72
+ rails_generators/uploader/USAGE
73
+ rails_generators/uploader/templates/uploader.rb
74
+ rails_generators/uploader/uploader_generator.rb
75
+ script/console
76
+ script/destroy
77
+ script/generate
78
+ spec/compatibility/paperclip_spec.rb
79
+ spec/fixtures/bork.txt
80
+ spec/fixtures/landscape.jpg
81
+ spec/fixtures/portrait.jpg
82
+ spec/fixtures/test.jpeg
83
+ spec/fixtures/test.jpg
84
+ spec/mount_spec.rb
85
+ spec/orm/activerecord_spec.rb
86
+ spec/orm/datamapper_spec.rb
87
+ spec/orm/mongoid_spec.rb
88
+ spec/orm/mongomapper_spec.rb
89
+ spec/orm/sequel_spec.rb
90
+ spec/processing/image_science_spec.rb
91
+ spec/processing/mini_magick_spec.rb
92
+ spec/processing/rmagick_spec.rb
93
+ spec/sanitized_file_spec.rb
94
+ spec/spec_helper.rb
95
+ spec/storage/cloudfiles_spec.rb
96
+ spec/storage/grid_fs_spec.rb
97
+ spec/storage/right_s3_spec.rb
98
+ spec/storage/s3_spec.rb
99
+ spec/uploader/cache_spec.rb
100
+ spec/uploader/configuration_spec.rb
101
+ spec/uploader/default_url_spec.rb
102
+ spec/uploader/download_spec.rb
103
+ spec/uploader/extension_whitelist_spec.rb
104
+ spec/uploader/mountable_spec.rb
105
+ spec/uploader/paths_spec.rb
106
+ spec/uploader/processing_spec.rb
107
+ spec/uploader/proxy_spec.rb
108
+ spec/uploader/remove_spec.rb
109
+ spec/uploader/store_spec.rb
110
+ spec/uploader/url_spec.rb
111
+ spec/uploader/versions_spec.rb
data/README.rdoc ADDED
@@ -0,0 +1,528 @@
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, a Rackspace Cloud Files 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 and Rackspace Cloud Files.
110
+ Define +store_dir+ as +nil+ if you'd like to store files at the root level.
111
+
112
+ == Securing uploads
113
+
114
+ 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.
115
+
116
+ If you're mounting the uploader, uploading a file with the wrong extension will make the record invalid instead. Otherwise, an error is raised.
117
+
118
+ class MyUploader < CarrierWave::Uploader::Base
119
+ def extension_white_list
120
+ %w(jpg jpeg gif png)
121
+ end
122
+ end
123
+
124
+ == Adding versions
125
+
126
+ Often you'll want to add different versions of the same file. The classic
127
+ example is image thumbnails. There is built in support for this:
128
+
129
+ class MyUploader < CarrierWave::Uploader::Base
130
+ include CarrierWave::RMagick
131
+
132
+ process :resize_to_fit => [800, 800]
133
+
134
+ version :thumb do
135
+ process :resize_to_fill => [200,200]
136
+ end
137
+
138
+ end
139
+
140
+ When this uploader is used, an uploaded image would be scaled to be no larger
141
+ than 800 by 800 pixels. A version called thumb is then created, which is scaled
142
+ and cropped to exactly 200 by 200 pixels. The uploader could be used like this:
143
+
144
+ uploader = AvatarUploader.new
145
+ uploader.store!(my_file) # size: 1024x768
146
+
147
+ uploader.url # => '/url/to/my_file.png' # size: 800x600
148
+ uploader.thumb.url # => '/url/to/thumb_my_file.png' # size: 200x200
149
+
150
+ One important thing to remember is that process is called *before* versions are
151
+ created. This can cut down on processing cost.
152
+
153
+ It is possible to nest versions within versions:
154
+
155
+ class MyUploader < CarrierWave::Uploader::Base
156
+
157
+ version :animal do
158
+ version :human
159
+ version :monkey
160
+ version :llama
161
+ end
162
+ end
163
+
164
+ == Making uploads work across form redisplays
165
+
166
+ Often you'll notice that uploaded files disappear when a validation fails.
167
+ CarrierWave has a feature that makes it easy to remember the uploaded file even
168
+ in that case. Suppose your +user+ model has an uploader mounted on +avatar+
169
+ file, just add a hidden field called +avatar_cache+. In Rails, this would look
170
+ like this:
171
+
172
+ <% form_for @user do |f| %>
173
+ <p>
174
+ <label>My Avatar</label>
175
+ <%= f.file_field :avatar %>
176
+ <%= f.hidden_field :avatar_cache %>
177
+ </p>
178
+ <% end %>
179
+
180
+ It might be a good idea to show the user that a file has been uploaded, in the
181
+ case of images, a small thumbnail would be a good indicator:
182
+
183
+ <% form_for @user do |f| %>
184
+ <p>
185
+ <label>My Avatar</label>
186
+ <%= image_tag(@user.avatar_url) if @user.avatar? %>
187
+ <%= f.file_field :avatar %>
188
+ <%= f.hidden_field :avatar_cache %>
189
+ </p>
190
+ <% end %>
191
+
192
+ == Removing uploaded files
193
+
194
+ If you want to remove a previously uploaded file on a mounted uploader, you can
195
+ easily add a checkbox to the form which will remove the file when checked.
196
+
197
+ <% form_for @user do |f| %>
198
+ <p>
199
+ <label>My Avatar</label>
200
+ <%= image_tag(@user.avatar_url) if @user.avatar? %>
201
+ <%= f.file_field :avatar %>
202
+ </p>
203
+
204
+ <p>
205
+ <label>
206
+ <%= f.check_box :remove_avatar %>
207
+ Remove avatar
208
+ </label>
209
+ </p>
210
+ <% end %>
211
+
212
+ If you want to remove the file manually, you can call <code>remove_avatar!</code>.
213
+
214
+ == Uploading files from a remote location
215
+
216
+ Your users may find it convenient to upload a file from a location on the Internet
217
+ via a URL. CarrierWave makes this simple, just add the appropriate column to your
218
+ form and you're good to go:
219
+
220
+ <% form_for @user do |f| %>
221
+ <p>
222
+ <label>My Avatar URL:</label>
223
+ <%= image_tag(@user.avatar_url) if @user.avatar? %>
224
+ <%= f.text_field :remote_avatar_url %>
225
+ </p>
226
+ <% end %>
227
+
228
+ == Providing a default URL
229
+
230
+ In many cases, especially when working with images, it might be a good idea to
231
+ provide a default url, a fallback in case no file has been uploaded. You can do
232
+ this easily by overriding the +default_url+ method in your uploader:
233
+
234
+ class MyUploader < CarrierWave::Uploader::Base
235
+ def default_url
236
+ "/images/fallback/" + [version_name, "default.png"].compact.join('_')
237
+ end
238
+ end
239
+
240
+ == Configuring CarrierWave
241
+
242
+ CarrierWave has a broad range of configuration options, which you can configure,
243
+ both globally and on a per-uploader basis:
244
+
245
+ CarrierWave.configure do |config|
246
+ config.permissions = 0666
247
+ config.storage = :s3
248
+ end
249
+
250
+ Or alternatively:
251
+
252
+ class AvatarUploader < CarrierWave::Uploader::Base
253
+ permissions 0777
254
+ end
255
+
256
+ == Testing CarrierWave
257
+
258
+ It's a good idea to test you uploaders in isolation. In order to speed up your
259
+ tests, it's recommended to switch off processing in your tests, and to use the
260
+ file storage. In Rails you could do that by adding an initializer with:
261
+
262
+ if Rails.env.test?
263
+ CarrierWave.configure do |config|
264
+ config.storage = :file
265
+ config.enable_processing = false
266
+ end
267
+ end
268
+
269
+ If you need to test your processing, you should test it in isolation, and enable
270
+ processing only for those tests that need it.
271
+
272
+ CarrierWave comes with some RSpec matchers which you may find useful:
273
+
274
+ require 'carrierwave/test/matchers'
275
+
276
+ describe MyUploader do
277
+ before do
278
+ MyUploader.enable_processing = true
279
+ @uploader = MyUploader.new(@user, :avatar)
280
+ @uploader.store!(File.open(path_to_file))
281
+ end
282
+
283
+ after do
284
+ MyUploader.enable_processing = false
285
+ end
286
+
287
+ context 'the thumb version' do
288
+ it "should scale down a landscape image to be exactly 64 by 64 pixels" do
289
+ @uploader.thumb.should have_dimensions(200, 200)
290
+ end
291
+ end
292
+
293
+ context 'the small version' do
294
+ it "should scale down a landscape image to fit within 200 by 200 pixels" do
295
+ @uploader.small.should be_no_larger_than(200, 200)
296
+ end
297
+ end
298
+
299
+ it "should make the image readable only to the owner and not executable" do
300
+ @uploader.should have_premissions(0600)
301
+ end
302
+ end
303
+
304
+ == Using Amazon S3
305
+
306
+ You'll need to configure a bucket, access id and secret key like this:
307
+
308
+ CarrierWave.configure do |config|
309
+ config.s3_access_key_id = 'xxxxxx'
310
+ config.s3_secret_access_key = 'xxxxxx'
311
+ config.s3_bucket = 'name_of_bucket'
312
+ end
313
+
314
+ Do this in an initializer in Rails, and in a +before_app_loads+ block in Merb.
315
+
316
+ And then in your uploader, set the storage to :s3
317
+
318
+ class AvatarUploader < CarrierWave::Uploader::Base
319
+ storage :s3
320
+ end
321
+
322
+ That's it! You can still use the <code>CarrierWave::Uploader#url</code> method to return
323
+ the url to the file on Amazon S3.
324
+
325
+ Alternatively, and especially if your bucket is located in Europe, you can use the
326
+ RightAWS library by setting the storage to :right_s3
327
+
328
+ class AvatarUploader < CarrierWave::Uploader::Base
329
+ storage :right_s3
330
+ end
331
+
332
+ CarrierWave uses the RightAWS S3 Interface directly, meaning that the performance issues
333
+ mentioned by Jonathan Yurek for paperclip do not apply: http://groups.google.com/group/paperclip-plugin/browse_thread/thread/d4dc166a9a5f0df4#
334
+
335
+ == Using Rackspace Cloud Files
336
+
337
+ Cloud Files support requires a {Rackspace Cloud}[http://rackspacecloud.com] username and API key.
338
+ You must also create a container for Carrierwave to use, and mark it public (publish it to the CDN)
339
+
340
+ CarrierWave.configure do |config|
341
+ config.cloud_files_user_name = 'xxxxxx'
342
+ config.cloud_files_api_key = 'xxxxxxxxxxxxxxxxxxxxx'
343
+ config.cloud_files_container = 'name_of_bucket'
344
+ end
345
+
346
+ Do this in an initializer in Rails, and in a +before_app_loads+ block in Merb.
347
+
348
+ And then in your uploader, set the storage to :cloud_files
349
+
350
+ class AvatarUploader < CarrierWave::Uploader::Base
351
+ storage :cloud_files
352
+ end
353
+
354
+ That's it! You can still use the <code>CarrierWave::Uploader#url</code> method to return
355
+ the url to the file on the Cloud Files CDN.
356
+
357
+ == Using MongoDB's GridFS store
358
+
359
+ You'll need to configure the database and host to use:
360
+
361
+ CarrierWave.configure do |config|
362
+ config.grid_fs_database = 'my_mongo_database'
363
+ config.grid_fs_host = 'mongo.example.com'
364
+ end
365
+
366
+ The defaults are 'carrierwave' and 'localhost'.
367
+
368
+ And then in your uploader, set the storage to <code>:grid_fs</code>:
369
+
370
+ class AvatarUploader < CarrierWave::Uploader::Base
371
+ storage :grid_fs
372
+ end
373
+
374
+ Since GridFS doesn't make the files available via HTTP, you'll need to stream
375
+ them yourself. In Rails for example, you could use the +send_data+ method. You
376
+ can tell CarrierWave the URL you will serve your images from, allowing it to
377
+ generate the correct URL, by setting eg:
378
+
379
+ CarrierWave.configure do |config|
380
+ config.grid_fs_access_url = "/image/show"
381
+ end
382
+
383
+ == Using RMagick
384
+
385
+ If you're uploading images, you'll probably want to manipulate them in some way,
386
+ you might want to create thumbnail images for example. CarrierWave comes with a
387
+ small library to make manipulating images with RMagick easier, you'll need to
388
+ include it in your Uploader:
389
+
390
+ class AvatarUploader < CarrierWave::Uploader::Base
391
+ include CarrierWave::RMagick
392
+ end
393
+
394
+ The RMagick module gives you a few methods, like
395
+ <code>CarrierWave::RMagick#resize_to_fill</code> which manipulate the image file in some
396
+ way. You can set a +process+ callback, which will call that method any time a
397
+ file is uploaded.
398
+
399
+ class AvatarUploader < CarrierWave::Uploader::Base
400
+ include CarrierWave::RMagick
401
+
402
+ process :resize_to_fill => [200, 200]
403
+ process :convert => 'png'
404
+
405
+ def filename
406
+ super + '.png'
407
+ end
408
+ end
409
+
410
+ Check out the manipulate! method, which makes it easy for you to write your own
411
+ manipulation methods.
412
+
413
+ == Using ImageScience
414
+
415
+ ImageScience works the same way as RMagick.
416
+
417
+ class AvatarUploader < CarrierWave::Uploader::Base
418
+ include CarrierWave::ImageScience
419
+
420
+ process :resize_to_fill => [200, 200]
421
+ end
422
+
423
+ == Using MiniMagick
424
+
425
+ MiniMagick is similar to RMagick but performs all the operations using the 'mogrify'
426
+ command which is part of the standard ImageMagick kit. This allows you to have the power
427
+ of ImageMagick without having to worry about installing all the RMagick libraries.
428
+
429
+ See the MiniMagick site for more details:
430
+
431
+ http://github.com/probablycorey/mini_magick
432
+
433
+ And the ImageMagick command line options for more for whats on offer:
434
+
435
+ http://www.imagemagick.org/script/command-line-options.php
436
+
437
+ Currently, the MiniMagick carrierwave processor provides exactly the same methods as
438
+ for the RMagick processor.
439
+
440
+ class AvatarUploader < CarrierWave::Uploader::Base
441
+ include CarrierWave::MiniMagick
442
+
443
+ process :resize_to_fill => [200, 200]
444
+ end
445
+
446
+ == Migrating
447
+
448
+ If you are using Paperclip, you can use the provided compatibility module:
449
+
450
+ class AvatarUploader < CarrierWave::Uploader::Base
451
+ include CarrierWave::Compatibility::Paperclip
452
+ end
453
+
454
+ See the documentation for <code>Paperclip::Compatibility::Paperclip</code> for more
455
+ detaills.
456
+
457
+ Be sure to use mount_on to specify the correct column:
458
+
459
+ mount_uploader :avatar, AvatarUploader, :mount_on => :avatar_file_name
460
+
461
+ Unfortunately AttachmentFoo differs too much in philosophy for there to be a
462
+ sensible compatibility mode. Patches for migrating from other solutions will be
463
+ happily accepted.
464
+
465
+ == i18n
466
+
467
+ The activerecord validations use the Rails i18n framework. Add these keys to
468
+ your translations file:
469
+
470
+ carrierwave:
471
+ errors:
472
+ integrity: 'Not an image.'
473
+ processing: 'Cannot resize image.'
474
+
475
+ == Contributors
476
+
477
+ These people have contributed their time and effort to CarrierWave:
478
+
479
+ * Jonas Nicklas
480
+ * Pavel Kunc
481
+ * Andrew Timberlake
482
+ * Durran Jordan
483
+ * Scott Motte
484
+ * Sho Fukamachi
485
+ * Sam Lown
486
+ * Dave Ott
487
+ * Quin Hoxie
488
+ * H. Wade Minter
489
+ * Trevor Turk
490
+ * Nicklas Ramhöj
491
+ * Matt Hooks
492
+
493
+ == License
494
+
495
+ Copyright (c) 2008 Jonas Nicklas
496
+
497
+ Permission is hereby granted, free of charge, to any person obtaining
498
+ a copy of this software and associated documentation files (the
499
+ "Software"), to deal in the Software without restriction, including
500
+ without limitation the rights to use, copy, modify, merge, publish,
501
+ distribute, sublicense, and/or sell copies of the Software, and to
502
+ permit persons to whom the Software is furnished to do so, subject to
503
+ the following conditions:
504
+
505
+ The above copyright notice and this permission notice shall be
506
+ included in all copies or substantial portions of the Software.
507
+
508
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
509
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
510
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
511
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
512
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
513
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
514
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
515
+
516
+ == Development
517
+
518
+ If you want to run the tests (and you should) it might be convenient to install
519
+ the development dependencies, you can do that with:
520
+
521
+ sudo gem install carrierwave --development
522
+
523
+ CarrierWave is still young, but most of it is pretty well documented. It is also
524
+ extensively specced, and there are cucumber features for some common use cases.
525
+ Just dig in and look at the source for more in-depth explanation of what things
526
+ are doing.
527
+
528
+ Issues are reported on GitHub, pull requests are very welcome!