Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 400 lines (299 sloc) 16.129 kb
cbfaca4 @sikachu Update the travis build image to display the build result from master br...
sikachu authored
1 # Paperclip [![Build Status](https://secure.travis-ci.org/thoughtbot/paperclip.png?branch=master)](http://travis-ci.org/thoughtbot/paperclip)
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
2
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
3 Paperclip is intended as an easy file attachment library for ActiveRecord. The
4 intent behind it was to keep setup as easy as possible and to treat files as
5 much like other attributes as possible. This means they aren't saved to their
6 final locations on disk, nor are they deleted if set to nil, until
7 ActiveRecord::Base#save is called. It manages validations based on size and
8 presence, if required. It can transform its assigned image into thumbnails if
9 needed, and the prerequisites are as simple as installing ImageMagick (which,
10 for most modern Unix-based systems, is as easy as installing the right
11 packages). Attached files are saved to the filesystem and referenced in the
12 browser by an easily understandable specification, which has sensible and
13 useful defaults.
14
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
15 See the documentation for `has_attached_file` in Paperclip::ClassMethods for
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
16 more detailed options.
17
0d395b6 fix the link to rdoc
Chad Pytel authored
18 The complete [RDoc](http://rdoc.info/gems/paperclip) is online.
7150016 @croaky added mailing list, issues queue, and rdoc links to README
croaky authored
19
beff127 @nathanl Made the ImageMagick requirement more prominent
nathanl authored
20 Requirements
21 ------------
22
23 ImageMagick must be installed and Paperclip must have access to it. To ensure
24 that it does, on your command line, run `which convert` (one of the ImageMagick
25 utilities). This will give you the path where that utility is installed. For
26 example, it might return `/usr/local/bin/convert`.
27
81562b0 @monde Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
28 Then, in your environment config file, let Paperclip know to look there by adding that
beff127 @nathanl Made the ImageMagick requirement more prominent
nathanl authored
29 directory to its path.
30
31 In development mode, you might add this line to `config/environments/development.rb)`:
32
33 Paperclip.options[:command_path] = "/usr/local/bin/"
34
6cef277 @nickrivadeneira add homebrew info to readme for test suite
nickrivadeneira authored
35 If you're on Mac OSX, you'll want to run the following with Homebrew:
36
37 brew install imagemagick
38
39 If you are dealing with pdf uploads or running the test suite, also run:
40
41 brew install gs
42
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
43 Installation
44 ------------
6961912 @croaky added twiddle wakka/Gemfile installation instructions to README
croaky authored
45
3dacda3 @jyurek Clarify installation instructions in README
jyurek authored
46 Paperclip is distributed as a gem, which is how it should be used in your app. It's
47 technically still installable as a plugin, but that's discouraged, as Rails plays
48 well with gems.
49
6961912 @croaky added twiddle wakka/Gemfile installation instructions to README
croaky authored
50 Include the gem in your Gemfile:
51
bd9cf24 @sikachu Update version in README to 2.4
sikachu authored
52 gem "paperclip", "~> 2.4"
7150016 @croaky added mailing list, issues queue, and rdoc links to README
croaky authored
53
3dacda3 @jyurek Clarify installation instructions in README
jyurek authored
54 Or, if you don't use Bundler (though you probably should, even in Rails 2), with config.gem
289d9cf @tilsammans include installation instructions
tilsammans authored
55
3dacda3 @jyurek Clarify installation instructions in README
jyurek authored
56 # In config/environment.rb
57 ...
58 Rails::Initializer.run do |config|
59 ...
bd9cf24 @sikachu Update version in README to 2.4
sikachu authored
60 config.gem "paperclip", :version => "~> 2.4"
3dacda3 @jyurek Clarify installation instructions in README
jyurek authored
61 ...
62 end
e4339af @gouthamvel Updated README for non-rails usage.
gouthamvel authored
63 For Non-Rails usage:
64 class ModleName < ActiveRecord::Base
65 include Paperclip::Glue
66 ...
67 end
289d9cf @tilsammans include installation instructions
tilsammans authored
68
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
69 Quick Start
70 -----------
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
71
72 In your model:
73
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
74 class User < ActiveRecord::Base
75 has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
76 end
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
77
78 In your migrations:
79
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
80 class AddAvatarColumnsToUser < ActiveRecord::Migration
81 def self.up
82 add_column :users, :avatar_file_name, :string
83 add_column :users, :avatar_content_type, :string
84 add_column :users, :avatar_file_size, :integer
85 add_column :users, :avatar_updated_at, :datetime
86 end
87
88 def self.down
89 remove_column :users, :avatar_file_name
90 remove_column :users, :avatar_content_type
91 remove_column :users, :avatar_file_size
92 remove_column :users, :avatar_updated_at
93 end
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
94 end
95
96 In your edit and new views:
97
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
98 <% form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
99 <%= form.file_field :avatar %>
100 <% end %>
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
101
102 In your controller:
103
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
104 def create
105 @user = User.create( params[:user] )
106 end
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
107
108 In your show view:
109
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
110 <%= image_tag @user.avatar.url %>
111 <%= image_tag @user.avatar.url(:medium) %>
112 <%= image_tag @user.avatar.url(:thumb) %>
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
113
f71ebb4 @gabebw Typo
gabebw authored
114 To detach a file, simply set the attribute to `nil`:
b2a370e Detaching a file
Harold Giménez authored
115
e365326 Follow the example with #avatar
Harold Giménez authored
116 @user.avatar = nil
b2a370e Detaching a file
Harold Giménez authored
117 @user.save
118
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
119 Usage
120 -----
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
121
122 The basics of paperclip are quite simple: Declare that your model has an
123 attachment with the has_attached_file method, and give it a name. Paperclip
124 will wrap up up to four attributes (all prefixed with that attachment's name,
d64d131 @sikachu Edit README to fix Typo
sikachu authored
125 so you can have multiple attachments per model if you wish) and give them a
249bf0a Revert "fix the <attachment> stuff for markdown"
Chad Pytel authored
126 friendly front end. The attributes are `<attachment>_file_name`,
127 `<attachment>_file_size`, `<attachment>_content_type`, and `<attachment>_updated_at`.
128 Only `<attachment>_file_name` is required for paperclip to operate. More
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
129 information about the options to has_attached_file is available in the
130 documentation of Paperclip::ClassMethods.
131
132 Attachments can be validated with Paperclip's validation methods,
249bf0a Revert "fix the <attachment> stuff for markdown"
Chad Pytel authored
133 validates_attachment_presence, validates_attachment_content_type, and
134 validates_attachment_size.
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
135
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
136 Storage
137 -------
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
138
139 The files that are assigned as attachments are, by default, placed in the
140 directory specified by the :path option to has_attached_file. By default, this
6539e54 @jyurek Updated documentation and gemspec for 2.2.9
jyurek authored
141 location is ":rails_root/public/system/:attachment/:id/:style/:filename". This
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
142 location was chosen because on standard Capistrano deployments, the
143 public/system directory is symlinked to the app's shared directory, meaning it
144 will survive between deployments. For example, using that :path, you may have a
145 file at
146
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
147 /data/myapp/releases/20081229172410/public/system/avatars/13/small/my_pic.png
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
148
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
149 _NOTE: This is a change from previous versions of Paperclip, but is overall a
150 safer choice for the default file store._
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
151
152 You may also choose to store your files using Amazon's S3 service. You can find
153 more information about S3 storage at the description for
154 Paperclip::Storage::S3.
155
156 Files on the local filesystem (and in the Rails app's public directory) will be
157 available to the internet at large. If you require access control, it's
158 possible to place your files in a different location. You will need to change
159 both the :path and :url options in order to make sure the files are unavailable
160 to the public. Both :path and :url allow the same set of interpolated
161 variables.
162
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
163 Post Processing
164 ---------------
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
165
6539e54 @jyurek Updated documentation and gemspec for 2.2.9
jyurek authored
166 Paperclip supports an extensible selection of post-processors. When you define
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
167 a set of styles for an attachment, by default it is expected that those
6539e54 @jyurek Updated documentation and gemspec for 2.2.9
jyurek authored
168 "styles" are actually "thumbnails". However, you can do much more than just
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
169 thumbnail images. By defining a subclass of Paperclip::Processor, you can
170 perform any processing you want on the files that are attached. Any file in
9dd008d @jyurek Doc typo fix thanks to Rymai
jyurek authored
171 your Rails app's lib/paperclip_processors directory is automatically loaded by
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
172 paperclip, allowing you to easily define custom processors. You can specify a
173 processor with the :processors option to has_attached_file:
174
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
175 has_attached_file :scan, :styles => { :text => { :quality => :better } },
176 :processors => [:ocr]
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
177
178 This would load the hypothetical class Paperclip::Ocr, which would have the
179 hash "{ :quality => :better }" passed to it along with the uploaded file. For
180 more information about defining processors, see Paperclip::Processor.
181
182 The default processor is Paperclip::Thumbnail. For backwards compatability
183 reasons, you can pass a single geometry string or an array containing a
184 geometry and a format, which the file will be converted to, like so:
185
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
186 has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
187
188 This will convert the "thumb" style to a 32x32 square in png format, regardless
189 of what was uploaded. If the format is not specified, it is kept the same (i.e.
190 jpgs will remain jpgs).
191
192 Multiple processors can be specified, and they will be invoked in the order
193 they are defined in the :processors array. Each successive processor will
194 be given the result of the previous processor's execution. All processors will
195 receive the same parameters, which are what you define in the :styles hash.
196 For example, assuming we had this definition:
197
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
198 has_attached_file :scan, :styles => { :text => { :quality => :better } },
199 :processors => [:rotator, :ocr]
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
200
3be55fc @joshuaclayton Clean up whitespace
joshuaclayton authored
201 then both the :rotator processor and the :ocr processor would receive the
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
202 options "{ :quality => :better }". This parameter may not mean anything to one
6539e54 @jyurek Updated documentation and gemspec for 2.2.9
jyurek authored
203 or more or the processors, and they are expected to ignore it.
204
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
205 _NOTE: Because processors operate by turning the original attachment into the
206 styles, no processors will be run if there are no styles defined._
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
207
4d843c9 @sikachu Add a comment to mention `attachment_on_the_fly` gem
sikachu authored
208 If you're interested in caching your thumbnail's width, height and size in the
28746ec add a note about paperclip-meta
Chad Pytel authored
209 database, take a look at the [paperclip-meta](https://github.com/y8/paperclip-meta) gem.
210
4d843c9 @sikachu Add a comment to mention `attachment_on_the_fly` gem
sikachu authored
211 Also, if you're interesting to generate the thumbnail on-the-fly, you might want
212 to look into the [attachment_on_the_fly](https://github.com/drpentode/Attachment-on-the-Fly) gem.
213
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
214 Events
215 ------
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
216
217 Before and after the Post Processing step, Paperclip calls back to the model
218 with a few callbacks, allowing the model to change or cancel the processing
32f458a fix <attachment> markup in events section
Chad Pytel authored
219 step. The callbacks are `before_post_process` and `after_post_process` (which
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
220 are called before and after the processing of each attachment), and the
32f458a fix <attachment> markup in events section
Chad Pytel authored
221 attachment-specific `before_<attachment>_post_process` and
222 `after_<attachment>_post_process`. The callbacks are intended to be as close to
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
223 normal ActiveRecord callbacks as possible, so if you return false (specifically
5ec90a5 @jyurek Fixed doc markup that was causing RDoc to ignore part of the README
jyurek authored
224 - returning nil is not the same) in a before_ filter, the post processing step
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
225 will halt. Returning false in an after_ filter will not halt anything, but you
226 can access the model and the attachment if necessary.
227
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
228 _NOTE: Post processing will not even *start* if the attachment is not valid
6539e54 @jyurek Updated documentation and gemspec for 2.2.9
jyurek authored
229 according to the validations. Your callbacks and processors will *only* be
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
230 called with valid attachments._
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
231
693a071 @maxim Add link to the pull request explaining URI-obfuscation with :hash inter...
maxim authored
232 URI Obfuscation
233 ---------------
234
235 Paperclip has an interpolation called `:hash` for obfuscating filenames of publicly-available files. For more on this feature read author's own explanation.
236
237 [https://github.com/thoughtbot/paperclip/pull/416](https://github.com/thoughtbot/paperclip/pull/416)
238
f815b8b @monde Documenting the MD5 checksum fingerprint feature.
monde authored
239 MD5 Checksum / Fingerprint
240 -------
81562b0 @monde Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
241
242 A MD5 checksum of the original file assigned will be placed in the model if it
243 has an attribute named fingerprint. Following the user model migration example
244 above, the migration would look like the following.
f815b8b @monde Documenting the MD5 checksum fingerprint feature.
monde authored
245
246 class AddAvatarFingerprintColumnToUser < ActiveRecord::Migration
247 def self.up
248 add_column :users, :avatar_fingerprint, :string
249 end
250
251 def self.down
252 remove_column :users, :avatar_fingerprint
253 end
254 end
255
81562b0 @monde Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
256 Custom Attachment Processors
257 -------
258
259 Custom attachment processors can be implemented and their only requirement is
260 to inherit from `Paperclip::Processor` (see `lib/paperclip/processor.rb`).
261 For example, when `:styles` are specified for an image attachment, the
262 thumbnail processor (see `lib/paperclip/thumbnail.rb`) is loaded without having
263 to specify it as a `:processor` parameter to `has_attached_file`. When any
264 other processor is defined it must be called out in the `:processors`
265 parameter if it is to be applied to the attachment. The thumbnail processor
266 uses the imagemagick `convert` command to do the work of resizing image
267 thumbnails. It would be easy to create a custom processor that watermarks
268 an image using imagemagick's `composite` command. Following the
269 implementation pattern of the thumbnail processor would be a way to implement a
270 watermark processor. All kinds of attachment processors can be created;
271 a few utility examples would be compression and encryption processors.
272
273
274 Dynamic Configuration
275 ---------------------
276
277 Callable objects (labdas, Procs) can be used in a number of places for dynamic
278 configuration throughout Paperclip. This strategy exists in a number of
279 components of the library but is most significant in the possibilities for
280 allowing custom styles and processors to be applied for specific model
281 instances, rather than applying defined styles and processors across all
282 instances.
283
284 Dynamic Styles:
285
286 Imagine a user model that had different styles based on the role of the user.
287 Perhaps some users are bosses (e.g. a User model instance responds to #boss?)
288 and merit a bigger avatar thumbnail than regular users. The configuration to
289 determine what style parameters are to be used based on the user role might
290 look as follows where a boss will receive a `300x300` thumbnail otherwise a
291 `100x100` thumbnail will be created.
292
293 class User < ActiveRecord::Base
294 has_attached_file :avatar, :styles => lambda { |attachment| { :thumb => (attachment.instance.boss? ? "300x300>" : "100x100>") }
295 end
296
297 Dynamic Processors:
298
299 Another contrived example is a user model that is aware of which file processors
300 should be applied to it (beyond the implied `thumbnail` processor invoked when
301 `:styles` are defined). Perhaps we have a watermark processor available and it is
302 only used on the avatars of certain models. The configuration for this might be
303 where the instance is queried for which processors should be applied to it.
304 Presumably some users might return `[:thumbnail, :watermark]` for its
305 processors, where a defined `watermark` processor is invoked after the
306 `thumbnail` processor already defined by Paperclip.
307
308 class User < ActiveRecord::Base
309 has_attached_file :avatar, :processors => lambda { |instance| instance.processors }
310 attr_accessor :watermark
311 end
312
bb5fde8 @murbanski Updated README with instructions for using missing_styles task
murbanski authored
313 Deploy
314 ------
315
fc0349d @murbanski More readable doc
murbanski authored
316 Paperclip is aware of new attachment styles you have added in previous deploy. The only thing you should do after each deployment is to call
317 `rake paperclip:refresh:missing_styles`. It will store current attachment styles in `RAILS_ROOT/public/system/paperclip_attachments.yml`
318 by default. You can change it by:
bb5fde8 @murbanski Updated README with instructions for using missing_styles task
murbanski authored
319
320 Paperclip.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
321
322 Here is an example for Capistrano:
323
324 namespace :deploy do
325 desc "build missing paperclip styles"
326 task :build_missing_paperclip_styles, :roles => :app do
327 run "cd #{release_path}; RAILS_ENV=production bundle exec rake paperclip:refresh:missing_styles"
328 end
329 end
330
331 after("deploy:update_code", "deploy:build_missing_paperclip_styles")
332
333 Now you don't have to remember to refresh thumbnails in production everytime you add new style.
fc0349d @murbanski More readable doc
murbanski authored
334 Unfortunately it does not work with dynamic styles - it just ignores them.
bb5fde8 @murbanski Updated README with instructions for using missing_styles task
murbanski authored
335
336 If you already have working app and don't want `rake paperclip:refresh:missing_styles` to refresh old pictures, you need to tell
337 Paperclip about existing styles. Simply create paperclip_attachments.yml file by hand. For example:
338
339 class User < ActiveRecord::Base
340 has_attached_file :avatar, :styles => {:thumb => 'x100', :croppable => '600x600>', :big => '1000x1000>'}
341 end
342
343 class Book < ActiveRecord::Base
344 has_attached_file :cover, :styles => {:small => 'x100', :large => '1000x1000>'}
345 has_attached_file :sample, :styles => {:thumb => 'x100'}
346 end
347
348 Then in `RAILS_ROOT/public/system/paperclip_attachments.yml`:
349
350 ---
351 :User:
352 :avatar:
353 - :thumb
354 - :croppable
355 - :big
356 :Book:
357 :cover:
358 - :small
359 - :large
360 :sample:
361 - :thumb
362
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
363 Testing
364 -------
4c6cf39 @jferris Added documentation for rspec matchers
jferris authored
365
366 Paperclip provides rspec-compatible matchers for testing attachments. See the
13d51e3 @qrush Update readme with link to docs for rspec matcher
qrush authored
367 documentation on [Paperclip::Shoulda::Matchers](http://rubydoc.info/gems/paperclip/Paperclip/Shoulda/Matchers)
368 for more information.
4c6cf39 @jferris Added documentation for rspec matchers
jferris authored
369
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
370 Contributing
371 ------------
fd2333e @jyurek Added a Contributing section to the README
jyurek authored
372
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
373 If you'd like to contribute a feature or bugfix: Thanks! To make sure your
374 fix/feature has a high chance of being included, please read the following
375 guidelines:
fd2333e @jyurek Added a Contributing section to the README
jyurek authored
376
81562b0 @monde Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
377 1. Ask on the mailing list[http://groups.google.com/group/paperclip-plugin], or
7150016 @croaky added mailing list, issues queue, and rdoc links to README
croaky authored
378 post a new GitHub Issue[http://github.com/thoughtbot/paperclip/issues].
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
379 2. Make sure there are tests! We will not accept any patch that is not tested.
f748f4f @qrush Updating readme with new contribution guidelines
qrush authored
380 It's a rare time when explicit tests aren't needed. If you have questions
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
381 about writing tests for paperclip, please ask the mailing list.
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
382
6311a68 @mike-burns Add a document describing how to contribute.
mike-burns authored
383 Please see CONTRIBUTING.md for details.
384
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
385 Credits
386 -------
387
388 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
389
390 Paperclip is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
391
aa55b95 @mjankowski thank the contributors
mjankowski authored
392 Thank you to all [the contributors](https://github.com/thoughtbot/paperclip/contributors)!
393
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
394 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
395
396 License
397 -------
398
399 Paperclip is Copyright © 2008-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
Something went wrong with that request. Please try again.