Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 621 lines (459 sloc) 21.971 kb
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
1 Paperclip
2 =========
edfff2f Jon Yurek Moved README to README.rdoc
jyurek authored
3
53c8dde Bryan Helmkamp Add Code Climate badge
brynary authored
4 [![Build Status](https://secure.travis-ci.org/thoughtbot/paperclip.png?branch=master)](http://travis-ci.org/thoughtbot/paperclip) [![Dependency Status](https://gemnasium.com/thoughtbot/paperclip.png?travis)](https://gemnasium.com/thoughtbot/paperclip) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/thoughtbot/paperclip)
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
5
6 Paperclip is intended as an easy file attachment library for Active Record. The
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
7 intent behind it was to keep setup as easy as possible and to treat files as
8 much like other attributes as possible. This means they aren't saved to their
9 final locations on disk, nor are they deleted if set to nil, until
10 ActiveRecord::Base#save is called. It manages validations based on size and
11 presence, if required. It can transform its assigned image into thumbnails if
12 needed, and the prerequisites are as simple as installing ImageMagick (which,
13 for most modern Unix-based systems, is as easy as installing the right
14 packages). Attached files are saved to the filesystem and referenced in the
15 browser by an easily understandable specification, which has sensible and
16 useful defaults.
17
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
18 See the documentation for `has_attached_file` in [`Paperclip::ClassMethods`](http://rubydoc.info/gems/paperclip/Paperclip/ClassMethods) for
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
19 more detailed options.
20
0d395b6 fix the link to rdoc
Chad Pytel authored
21 The complete [RDoc](http://rdoc.info/gems/paperclip) is online.
7150016 Dan Croak added mailing list, issues queue, and rdoc links to README
croaky authored
22
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
23
beff127 Nathan Long Made the ImageMagick requirement more prominent
nathanl authored
24 Requirements
25 ------------
26
8e80310 Prem Sichanugrist Update README file mentioning new changes
sikachu authored
27 ### Ruby and Rails
28
29 Paperclip now requires Ruby version **>= 1.9.2** and Rails version **>= 3.0** (Only if you're going to use Paperclip with Ruby on Rails.)
30
31 If you're still on Ruby 1.8.7 or Ruby on Rails 2.3.x, you can still use Paperclip 2.7.x with your project. Also, everything in this README might not apply to your version of Paperclip, and you should read [the README for version 2.7](http://rubydoc.info/gems/paperclip/2.7.0) instead.
32
33 ### Image Processor
34
35 [ImageMagick](http://www.imagemagick.org) must be installed and Paperclip must have access to it. To ensure
beff127 Nathan Long Made the ImageMagick requirement more prominent
nathanl authored
36 that it does, on your command line, run `which convert` (one of the ImageMagick
37 utilities). This will give you the path where that utility is installed. For
38 example, it might return `/usr/local/bin/convert`.
39
81562b0 Mike Mondragon Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
40 Then, in your environment config file, let Paperclip know to look there by adding that
beff127 Nathan Long Made the ImageMagick requirement more prominent
nathanl authored
41 directory to its path.
42
43 In development mode, you might add this line to `config/environments/development.rb)`:
44
45 Paperclip.options[:command_path] = "/usr/local/bin/"
46
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
47 If you're on Mac OS X, you'll want to run the following with Homebrew:
6cef277 Nick Rivadeneira add homebrew info to readme for test suite
nickrivadeneira authored
48
49 brew install imagemagick
50
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
51 If you are dealing with pdf uploads or running the test suite, you'll also need
52 GhostScript to be installed. On Mac OS X, you can also install that using Homebrew:
6cef277 Nick Rivadeneira add homebrew info to readme for test suite
nickrivadeneira authored
53
54 brew install gs
55
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
56
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
57 Installation
58 ------------
6961912 Dan Croak added twiddle wakka/Gemfile installation instructions to README
croaky authored
59
d081085 Prem Sichanugrist Stop saying that Paperclip is a Rails plugin
sikachu authored
60 Paperclip is distributed as a gem, which is how it should be used in your app.
3dacda3 Jon Yurek Clarify installation instructions in README
jyurek authored
61
6961912 Dan Croak added twiddle wakka/Gemfile installation instructions to README
croaky authored
62 Include the gem in your Gemfile:
63
8e80310 Prem Sichanugrist Update README file mentioning new changes
sikachu authored
64 gem "paperclip", "~> 3.0"
65
66 If you're still using Rails 2.3.x, you should do this instead:
67
5dba614 Prem Sichanugrist Update README
sikachu authored
68 gem "paperclip", "~> 2.7"
7150016 Dan Croak added mailing list, issues queue, and rdoc links to README
croaky authored
69
c34a9fb Jon Yurek Update README to let people know master is ahead of the latest gem relea...
jyurek authored
70 Or, if you want to get the latest, you can get master from the main paperclip repository:
71
72 gem "paperclip", :git => "git://github.com/thoughtbot/paperclip.git"
22a2a85 Prem Sichanugrist Lock `aws-sdk` version in the readme
sikachu authored
73
c34a9fb Jon Yurek Update README to let people know master is ahead of the latest gem relea...
jyurek authored
74 If you're trying to use features that don't seem to be in the latest released gem, but are
75 mentioned in this README, then you probably need to specify the master branch if you want to
76 use them. This README is probably ahead of the latest released version, if you're reading it
77 on GitHub.
78
e4339af goutham Updated README for non-rails usage.
gouthamvel authored
79 For Non-Rails usage:
487ab74 goutham fixes the markedown formating
gouthamvel authored
80
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
81 ```ruby
82 class ModuleName < ActiveRecord::Base
83 include Paperclip::Glue
84 ...
85 end
86 ```
289d9cf Joost Baaij include installation instructions
tilsammans authored
87
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
88 Quick Start
89 -----------
edfff2f Jon Yurek Moved README to README.rdoc
jyurek authored
90
91 In your model:
92
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
93 ```ruby
94 class User < ActiveRecord::Base
95 attr_accessible :avatar
96 has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
97 end
98 ```
edfff2f Jon Yurek Moved README to README.rdoc
jyurek authored
99
100 In your migrations:
101
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
102 ```ruby
103 class AddAvatarColumnsToUsers < ActiveRecord::Migration
104 def self.up
105 add_attachment :users, :avatar
106 end
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
107
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
108 def self.down
109 remove_attachment :users, :avatar
110 end
111 end
112 ```
edfff2f Jon Yurek Moved README to README.rdoc
jyurek authored
113
5dba614 Prem Sichanugrist Update README
sikachu authored
114 (Or you can use migration generator: `rails generate paperclip user avatar`)
115
edfff2f Jon Yurek Moved README to README.rdoc
jyurek authored
116 In your edit and new views:
117
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
118 ```erb
119 <%= form_for @user, :url => users_path, :html => { :multipart => true } do |form| %>
120 <%= form.file_field :avatar %>
121 <% end %>
122 ```
edfff2f Jon Yurek Moved README to README.rdoc
jyurek authored
123
124 In your controller:
125
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
126 ```ruby
127 def create
128 @user = User.create( params[:user] )
129 end
130 ```
edfff2f Jon Yurek Moved README to README.rdoc
jyurek authored
131
132 In your show view:
133
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
134 ```erb
135 <%= image_tag @user.avatar.url %>
136 <%= image_tag @user.avatar.url(:medium) %>
137 <%= image_tag @user.avatar.url(:thumb) %>
138 ```
edfff2f Jon Yurek Moved README to README.rdoc
jyurek authored
139
f71ebb4 Gabe Berke-Williams Typo
gabebw authored
140 To detach a file, simply set the attribute to `nil`:
b2a370e Detaching a file
Harold Giménez authored
141
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
142 ```ruby
143 @user.avatar = nil
144 @user.save
145 ```
b2a370e Detaching a file
Harold Giménez authored
146
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
147 Usage
148 -----
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
149
150 The basics of paperclip are quite simple: Declare that your model has an
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
151 attachment with the `has_attached_file` method, and give it a name.
152
153 Paperclip will wrap up up to four attributes (all prefixed with that attachment's name,
d64d131 Prem Sichanugrist Edit README to fix Typo
sikachu authored
154 so you can have multiple attachments per model if you wish) and give them a
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
155 friendly front end. These attributes are:
156
157 * `<attachment>_file_name`
158 * `<attachment>_file_size`
159 * `<attachment>_content_type`
160 * `<attachment>_updated_at`
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
161
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
162 By default, only `<attachment>_file_name` is required for paperclip to operate.
163 You'll need to add `<attachment>_content_type` in case you want to use content type
164 validation.
165
166 More information about the options to `has_attached_file` is available in the
167 documentation of [`Paperclip::ClassMethods`](http://rubydoc.info/gems/paperclip/Paperclip/ClassMethods).
168
8e80310 Prem Sichanugrist Update README file mentioning new changes
sikachu authored
169 For validations, Paperclip introduces several validators to validate your attachment:
170
171 * `AttachmentContentTypeValidator`
172 * `AttachmentPresenceValidator`
173 * `AttachmentSizeValidator`
174
175 Example Usage:
176
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
177 ```ruby
178 validates :avatar, :attachment_presence => true
179 validates_with AttachmentPresenceValidator, :attributes => :avatar
180 ```
8e80310 Prem Sichanugrist Update README file mentioning new changes
sikachu authored
181
182 Validators can also be defined using the old helper style:
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
183
184 * `validates_attachment_presence`
185 * `validates_attachment_content_type`
186 * `validates_attachment_size`
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
187
8e80310 Prem Sichanugrist Update README file mentioning new changes
sikachu authored
188 Example Usage:
189
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
190 ```ruby
191 validates_attachment_presence :avatar
192 ```
8e80310 Prem Sichanugrist Update README file mentioning new changes
sikachu authored
193
194 Lastly, you can also define multiple validations on a single attachment using `validates_attachment`:
195
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
196 ```ruby
197 validates_attachment :avatar, :presence => true,
198 :content_type => { :content_type => "image/jpg" },
199 :size => { :in => 0..10.kilobytes }
200 ```
8e80310 Prem Sichanugrist Update README file mentioning new changes
sikachu authored
201
efead1a Mark Kremer Specify default options in Rails 3.x configuration, README updated
mkremer authored
202 Defaults
203 --------
204 Global defaults for all your paperclip attachments can be defined by changing the Paperclip::Attachment.default_options Hash, this can be useful for setting your default storage settings per example so you won't have to define them in every has_attached_file definition.
205
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
206 If you're using Rails you can define a Hash with default options in config/application.rb or in any of the config/environments/*.rb files on config.paperclip_defaults, these well get merged into Paperclip::Attachment.default_options as your Rails app boots. An example:
efead1a Mark Kremer Specify default options in Rails 3.x configuration, README updated
mkremer authored
207
208 ```ruby
209 module YourApp
210 class Application < Rails::Application
211 # Other code...
212
213 config.paperclip_defaults = {:storage => :fog, :fog_credentials => {:provider => "Local", :local_root => "#{Rails.root}/public"}, :fog_directory => "", :fog_host => "localhost"}
214 end
215 end
216 ```
217
0354f66 Mark Kremer Updated README
mkremer authored
218 Another option is to directly modify the Paperclip::Attachment.default_options Hash, this method works for non-Rails applications or is an option if you prefer to place the Paperclip default settings in an initializer.
efead1a Mark Kremer Specify default options in Rails 3.x configuration, README updated
mkremer authored
219
220 An example Rails initializer would look something like this:
221
222 ```ruby
223 Paperclip::Attachment.default_options[:storage] = :fog
224 Paperclip::Attachment.default_options[:fog_credentials] = {:provider => "Local", :local_root => "#{Rails.root}/public"}
225 Paperclip::Attachment.default_options[:fog_directory] = ""
1abcbba Nick DeSteffen Rails initializer typo fix
nick-desteffen authored
226 Paperclip::Attachment.default_options[:fog_host] = "http://localhost:3000"
efead1a Mark Kremer Specify default options in Rails 3.x configuration, README updated
mkremer authored
227 ```
228
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
229 Migrations
230 ----------
231
232 Paperclip defines several migration methods which can be used to create necessary columns in your
233 model. There are two types of method:
234
235 ### Table Definition
236
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
237 ```ruby
238 class AddAttachmentToUsers < ActiveRecord::Migration
239 def self.up
240 create_table :users do |t|
241 t.attachment :avatar
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
242 end
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
243 end
244 end
245 ```
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
246
247 If you're using Rails 3.2 or newer, this method works in `change` method as well:
248
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
249 ```ruby
250 class AddAttachmentToUsers < ActiveRecord::Migration
251 def change
252 create_table :users do |t|
253 t.attachment :avatar
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
254 end
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
255 end
256 end
257 ```
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
258
259 ### Schema Definition
260
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
261 ```ruby
262 class AddAttachmentToUsers < ActiveRecord::Migration
263 def self.up
264 add_attachment :users, :avatar
265 end
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
266
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
267 def self.down
268 remove_attachment :users, :avatar
269 end
270 end
271 ```
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
272
273 If you're using Rails 3.2 or newer, you only need `add_attachment` in your `change` method:
274
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
275 ```ruby
276 class AddAttachmentToUsers < ActiveRecord::Migration
277 def change
278 add_attachment :users, :avatar
279 end
280 end
281 ```
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
282
283 ### Vintage syntax
284
f30f9cb groe Fix typo in README
groe authored
285 Vintage syntax (such as `t.has_attached_file` and `drop_attached_file`) are still supported in
3a7a93d Prem Sichanugrist Update Readme to mention sexy migration
sikachu authored
286 Paperclip 3.x, but you're advised to update those migration files to use this new syntax.
287
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
288 Storage
289 -------
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
290
635f34e Prem Sichanugrist Add note about Windows Azure and new style default
sikachu authored
291 Paperclip ships with 3 storage adapters:
292
293 * File Storage
294 * S3 Storage (via `aws-sdk`)
295 * Fog Storage
296
297 If you would like to use Paperclip with another storage, you can install these
298 gems along side with Paperclip:
299
ad83b1d Janko Marohnić Link to paperclip-dropbox gem in the readme
janko-m authored
300 * [paperclip-azure-storage](https://github.com/gmontard/paperclip-azure-storage)
301 * [paperclip-dropbox](https://github.com/janko-m/paperclip-dropbox)
635f34e Prem Sichanugrist Add note about Windows Azure and new style default
sikachu authored
302
303 ### Understanding Storage
304
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
305 The files that are assigned as attachments are, by default, placed in the
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
306 directory specified by the `:path` option to `has_attached_file`. By default, this
878622c Brandon Wright Update default path documentation
developish authored
307 location is `:rails_root/public/system/:class/:attachment/:id_partition/:style/:filename`.
308 This location was chosen because on standard Capistrano deployments, the
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
309 `public/system` directory is symlinked to the app's shared directory, meaning it
310 will survive between deployments. For example, using that `:path`, you may have a
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
311 file at
312
39717c6 Aditya Sanghi Fix typo in README
asanghi authored
313 /data/myapp/releases/20081229172410/public/system/users/avatar/000/000/013/small/my_pic.png
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
314
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
315 _**NOTE**: This is a change from previous versions of Paperclip, but is overall a
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
316 safer choice for the default file store._
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
317
308f1a0 John Bachir documentation for including aws-sdk in Gemfile
jjb authored
318 You may also choose to store your files using Amazon's S3 service. To do so, include
319 the `aws-sdk` gem in your Gemfile:
320
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
321 ```ruby
322 gem 'aws-sdk', '~> 1.3.4'
323 ```
308f1a0 John Bachir documentation for including aws-sdk in Gemfile
jjb authored
324
22a2a85 Prem Sichanugrist Lock `aws-sdk` version in the readme
sikachu authored
325 And then you can specify using S3 from `has_attached_file`.
308f1a0 John Bachir documentation for including aws-sdk in Gemfile
jjb authored
326 You can find more information about configuring and using S3 storage in
327 [the `Paperclip::Storage::S3` documentation](http://rubydoc.info/gems/paperclip/Paperclip/Storage/S3).
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
328
329 Files on the local filesystem (and in the Rails app's public directory) will be
330 available to the internet at large. If you require access control, it's
331 possible to place your files in a different location. You will need to change
adcd03c Prem Sichanugrist First pass on editing the README for more readability.
sikachu authored
332 both the `:path` and `:url` options in order to make sure the files are unavailable
333 to the public. Both `:path` and `:url` allow the same set of interpolated
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
334 variables.
335
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
336 Post Processing
337 ---------------
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
338
6539e54 Jon Yurek Updated documentation and gemspec for 2.2.9
jyurek authored
339 Paperclip supports an extensible selection of post-processors. When you define
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
340 a set of styles for an attachment, by default it is expected that those
6539e54 Jon Yurek Updated documentation and gemspec for 2.2.9
jyurek authored
341 "styles" are actually "thumbnails". However, you can do much more than just
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
342 thumbnail images. By defining a subclass of Paperclip::Processor, you can
343 perform any processing you want on the files that are attached. Any file in
227d6a4 Gabe Berke-Williams Escape underscores.
gabebw authored
344 your Rails app's lib/paperclip\_processors directory is automatically loaded by
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
345 paperclip, allowing you to easily define custom processors. You can specify a
5dba614 Prem Sichanugrist Update README
sikachu authored
346 processor with the :processors option to `has_attached_file`:
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
347
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
348 ```ruby
349 has_attached_file :scan, :styles => { :text => { :quality => :better } },
350 :processors => [:ocr]
351 ```
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
352
353 This would load the hypothetical class Paperclip::Ocr, which would have the
354 hash "{ :quality => :better }" passed to it along with the uploaded file. For
355 more information about defining processors, see Paperclip::Processor.
356
34f4499 Chris Houhoulis Correct typo, grammar, formatting in README.md
houhoulis authored
357 The default processor is Paperclip::Thumbnail. For backwards compatibility
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
358 reasons, you can pass a single geometry string or an array containing a
359 geometry and a format, which the file will be converted to, like so:
360
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
361 ```ruby
362 has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
363 ```
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
364
365 This will convert the "thumb" style to a 32x32 square in png format, regardless
366 of what was uploaded. If the format is not specified, it is kept the same (i.e.
093a14a Gabe Berke-Williams Add info on how geometry formats work.
gabebw authored
367 jpgs will remain jpgs). For more information on the accepted style formats, see
853595a Preston Guillory Fixed a typo in README.md.
pguillory authored
368 [here](http://www.imagemagick.org/script/command-line-processing.php#geometry).
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
369
370 Multiple processors can be specified, and they will be invoked in the order
371 they are defined in the :processors array. Each successive processor will
372 be given the result of the previous processor's execution. All processors will
373 receive the same parameters, which are what you define in the :styles hash.
374 For example, assuming we had this definition:
375
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
376 ```ruby
377 has_attached_file :scan, :styles => { :text => { :quality => :better } },
378 :processors => [:rotator, :ocr]
379 ```
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
380
3be55fc Joshua Clayton Clean up whitespace
joshuaclayton authored
381 then both the :rotator processor and the :ocr processor would receive the
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
382 options "{ :quality => :better }". This parameter may not mean anything to one
6539e54 Jon Yurek Updated documentation and gemspec for 2.2.9
jyurek authored
383 or more or the processors, and they are expected to ignore it.
384
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
385 _NOTE: Because processors operate by turning the original attachment into the
386 styles, no processors will be run if there are no styles defined._
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
387
4d843c9 Prem Sichanugrist Add a comment to mention `attachment_on_the_fly` gem
sikachu authored
388 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
389 database, take a look at the [paperclip-meta](https://github.com/y8/paperclip-meta) gem.
390
f12e2e8 Gabe Berke-Williams Whitespace and typos.
gabebw authored
391 Also, if you're interested in generating the thumbnail on-the-fly, you might want
4d843c9 Prem Sichanugrist Add a comment to mention `attachment_on_the_fly` gem
sikachu authored
392 to look into the [attachment_on_the_fly](https://github.com/drpentode/Attachment-on-the-Fly) gem.
393
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
394 Events
395 ------
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
396
397 Before and after the Post Processing step, Paperclip calls back to the model
398 with a few callbacks, allowing the model to change or cancel the processing
32f458a fix <attachment> markup in events section
Chad Pytel authored
399 step. The callbacks are `before_post_process` and `after_post_process` (which
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
400 are called before and after the processing of each attachment), and the
32f458a fix <attachment> markup in events section
Chad Pytel authored
401 attachment-specific `before_<attachment>_post_process` and
402 `after_<attachment>_post_process`. The callbacks are intended to be as close to
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
403 normal ActiveRecord callbacks as possible, so if you return false (specifically
5dba614 Prem Sichanugrist Update README
sikachu authored
404 \- returning nil is not the same) in a `before_filter`, the post processing step
4e4fa9d Gabe Berke-Williams Update README.md
gabebw authored
405 will halt. Returning false in an `after_filter` will not halt anything, but you
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
406 can access the model and the attachment if necessary.
407
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
408 _NOTE: Post processing will not even *start* if the attachment is not valid
6539e54 Jon Yurek Updated documentation and gemspec for 2.2.9
jyurek authored
409 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
410 called with valid attachments._
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
411
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
412 ```ruby
413 class Message < ActiveRecord::Base
414 has_attached_file :asset, styles: {thumb: "100x100#"}
5dba614 Prem Sichanugrist Update README
sikachu authored
415
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
416 before_post_process :skip_for_audio
5dba614 Prem Sichanugrist Update README
sikachu authored
417
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
418 def skip_for_audio
419 ! %w(audio/ogg application/ogg).include?(asset_content_type)
420 end
421 end
422 ```
49ddd12 Robert Pankowecki Updated "Events" section in README to include example of hook for skippi...
paneq authored
423
693a071 Maxim Chernyak aka hakunin Add link to the pull request explaining URI-obfuscation with :hash inter...
maxim authored
424 URI Obfuscation
425 ---------------
426
f12e2e8 Gabe Berke-Williams Whitespace and typos.
gabebw authored
427 Paperclip has an interpolation called `:hash` for obfuscating filenames of
2b8526b Expanded URI Obfuscation documentation.
trafnar authored
428 publicly-available files.
693a071 Maxim Chernyak aka hakunin Add link to the pull request explaining URI-obfuscation with :hash inter...
maxim authored
429
2b8526b Expanded URI Obfuscation documentation.
trafnar authored
430 Example Usage:
431
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
432 ```ruby
433 has_attached_file :avatar, {
434 :url => "/system/:hash.:extension",
435 :hash_secret => "longSecretString"
436 }
437 ```
2b8526b Expanded URI Obfuscation documentation.
trafnar authored
438
439
440 The `:hash` interpolation will be replaced with a unique hash made up of whatever
441 is specified in `:hash_data`. The default value for `:hash_data` is `":class/:attachment/:id/:style/:updated_at"`.
442
443 `:hash_secret` is required, an exception will be raised if `:hash` is used without `:hash_secret` present.
444
445 For more on this feature read the author's own explanation. [https://github.com/thoughtbot/paperclip/pull/416](https://github.com/thoughtbot/paperclip/pull/416)
693a071 Maxim Chernyak aka hakunin Add link to the pull request explaining URI-obfuscation with :hash inter...
maxim authored
446
f815b8b Mike Mondragon Documenting the MD5 checksum fingerprint feature.
monde authored
447 MD5 Checksum / Fingerprint
448 -------
81562b0 Mike Mondragon Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
449
450 A MD5 checksum of the original file assigned will be placed in the model if it
451 has an attribute named fingerprint. Following the user model migration example
452 above, the migration would look like the following.
f815b8b Mike Mondragon Documenting the MD5 checksum fingerprint feature.
monde authored
453
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
454 ```ruby
455 class AddAvatarFingerprintColumnToUser < ActiveRecord::Migration
456 def self.up
457 add_column :users, :avatar_fingerprint, :string
458 end
f815b8b Mike Mondragon Documenting the MD5 checksum fingerprint feature.
monde authored
459
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
460 def self.down
461 remove_column :users, :avatar_fingerprint
462 end
463 end
464 ```
f815b8b Mike Mondragon Documenting the MD5 checksum fingerprint feature.
monde authored
465
81562b0 Mike Mondragon Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
466 Custom Attachment Processors
467 -------
468
469 Custom attachment processors can be implemented and their only requirement is
470 to inherit from `Paperclip::Processor` (see `lib/paperclip/processor.rb`).
471 For example, when `:styles` are specified for an image attachment, the
472 thumbnail processor (see `lib/paperclip/thumbnail.rb`) is loaded without having
473 to specify it as a `:processor` parameter to `has_attached_file`. When any
474 other processor is defined it must be called out in the `:processors`
475 parameter if it is to be applied to the attachment. The thumbnail processor
476 uses the imagemagick `convert` command to do the work of resizing image
477 thumbnails. It would be easy to create a custom processor that watermarks
478 an image using imagemagick's `composite` command. Following the
479 implementation pattern of the thumbnail processor would be a way to implement a
480 watermark processor. All kinds of attachment processors can be created;
481 a few utility examples would be compression and encryption processors.
482
483
484 Dynamic Configuration
485 ---------------------
486
f12e2e8 Gabe Berke-Williams Whitespace and typos.
gabebw authored
487 Callable objects (lambdas, Procs) can be used in a number of places for dynamic
81562b0 Mike Mondragon Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
488 configuration throughout Paperclip. This strategy exists in a number of
489 components of the library but is most significant in the possibilities for
490 allowing custom styles and processors to be applied for specific model
491 instances, rather than applying defined styles and processors across all
492 instances.
493
3d55695 Prem Sichanugrist Add some h3 to the heading to make it stands out
sikachu authored
494 ### Dynamic Styles:
81562b0 Mike Mondragon Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
495
496 Imagine a user model that had different styles based on the role of the user.
497 Perhaps some users are bosses (e.g. a User model instance responds to #boss?)
498 and merit a bigger avatar thumbnail than regular users. The configuration to
499 determine what style parameters are to be used based on the user role might
500 look as follows where a boss will receive a `300x300` thumbnail otherwise a
501 `100x100` thumbnail will be created.
502
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
503 ```ruby
504 class User < ActiveRecord::Base
505 has_attached_file :avatar, :styles => lambda { |attachment| { :thumb => (attachment.instance.boss? ? "300x300>" : "100x100>") }
506 end
507 ```
81562b0 Mike Mondragon Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
508
3d55695 Prem Sichanugrist Add some h3 to the heading to make it stands out
sikachu authored
509 ### Dynamic Processors:
81562b0 Mike Mondragon Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
510
511 Another contrived example is a user model that is aware of which file processors
512 should be applied to it (beyond the implied `thumbnail` processor invoked when
513 `:styles` are defined). Perhaps we have a watermark processor available and it is
514 only used on the avatars of certain models. The configuration for this might be
515 where the instance is queried for which processors should be applied to it.
516 Presumably some users might return `[:thumbnail, :watermark]` for its
517 processors, where a defined `watermark` processor is invoked after the
518 `thumbnail` processor already defined by Paperclip.
519
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
520 ```ruby
521 class User < ActiveRecord::Base
522 has_attached_file :avatar, :processors => lambda { |instance| instance.processors }
523 attr_accessor :watermark
524 end
525 ```
81562b0 Mike Mondragon Documentation for custom processors, dynamic styles, and dynamic process...
monde authored
526
34f4499 Chris Houhoulis Correct typo, grammar, formatting in README.md
houhoulis authored
527 Deployment
528 ----------
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
529
34f4499 Chris Houhoulis Correct typo, grammar, formatting in README.md
houhoulis authored
530 Paperclip is aware of new attachment styles you have added in previous deploys. The only thing you should do after each deployment is to call
fc0349d Marcin Urbański More readable doc
murbanski authored
531 `rake paperclip:refresh:missing_styles`. It will store current attachment styles in `RAILS_ROOT/public/system/paperclip_attachments.yml`
532 by default. You can change it by:
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
533
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
534 ```ruby
535 Paperclip.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
536 ```
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
537
538 Here is an example for Capistrano:
539
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
540 ```ruby
541 namespace :deploy do
542 desc "build missing paperclip styles"
543 task :build_missing_paperclip_styles, :roles => :app do
544 run "cd #{release_path}; RAILS_ENV=production bundle exec rake paperclip:refresh:missing_styles"
545 end
546 end
f12e2e8 Gabe Berke-Williams Whitespace and typos.
gabebw authored
547
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
548 after("deploy:update_code", "deploy:build_missing_paperclip_styles")
549 ```
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
550
34f4499 Chris Houhoulis Correct typo, grammar, formatting in README.md
houhoulis authored
551 Now you don't have to remember to refresh thumbnails in production every time you add a new style.
fc0349d Marcin Urbański More readable doc
murbanski authored
552 Unfortunately it does not work with dynamic styles - it just ignores them.
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
553
34f4499 Chris Houhoulis Correct typo, grammar, formatting in README.md
houhoulis authored
554 If you already have a working app and don't want `rake paperclip:refresh:missing_styles` to refresh old pictures, you need to tell
555 Paperclip about existing styles. Simply create a `paperclip_attachments.yml` file by hand. For example:
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
556
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
557 ```ruby
558 class User < ActiveRecord::Base
559 has_attached_file :avatar, :styles => {:thumb => 'x100', :croppable => '600x600>', :big => '1000x1000>'}
560 end
f12e2e8 Gabe Berke-Williams Whitespace and typos.
gabebw authored
561
45bf52a Janko Marohnić Syntax highlight all the code in the readme
janko-m authored
562 class Book < ActiveRecord::Base
563 has_attached_file :cover, :styles => {:small => 'x100', :large => '1000x1000>'}
564 has_attached_file :sample, :styles => {:thumb => 'x100'}
565 end
566 ```
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
567
568 Then in `RAILS_ROOT/public/system/paperclip_attachments.yml`:
569
f12e2e8 Gabe Berke-Williams Whitespace and typos.
gabebw authored
570 ---
571 :User:
572 :avatar:
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
573 - :thumb
574 - :croppable
575 - :big
f12e2e8 Gabe Berke-Williams Whitespace and typos.
gabebw authored
576 :Book:
577 :cover:
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
578 - :small
579 - :large
f12e2e8 Gabe Berke-Williams Whitespace and typos.
gabebw authored
580 :sample:
bb5fde8 Marcin Urbański Updated README with instructions for using missing_styles task
murbanski authored
581 - :thumb
582
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
583 Testing
584 -------
4c6cf39 Joe Ferris Added documentation for rspec matchers
jferris authored
585
586 Paperclip provides rspec-compatible matchers for testing attachments. See the
13d51e3 Nick Quaranto Update readme with link to docs for rspec matcher
qrush authored
587 documentation on [Paperclip::Shoulda::Matchers](http://rubydoc.info/gems/paperclip/Paperclip/Shoulda/Matchers)
588 for more information.
4c6cf39 Joe Ferris Added documentation for rspec matchers
jferris authored
589
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
590 Contributing
591 ------------
fd2333e Jon Yurek Added a Contributing section to the README
jyurek authored
592
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
593 If you'd like to contribute a feature or bugfix: Thanks! To make sure your
594 fix/feature has a high chance of being included, please read the following
595 guidelines:
fd2333e Jon Yurek Added a Contributing section to the README
jyurek authored
596
4326a3d Prem Sichanugrist Update documentation regarding running test
sikachu authored
597 1. Ask on the [mailing list](http://groups.google.com/group/paperclip-plugin), or
598 post a new [GitHub Issue](http://github.com/thoughtbot/paperclip/issues).
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
599 2. Make sure there are tests! We will not accept any patch that is not tested.
f748f4f Nick Quaranto Updating readme with new contribution guidelines
qrush authored
600 It's a rare time when explicit tests aren't needed. If you have questions
7212775 Jon Yurek Lots more documentation, including events and processors
jyurek authored
601 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
602
4326a3d Prem Sichanugrist Update documentation regarding running test
sikachu authored
603 Please see `CONTRIBUTING.md` for more details on contributing and running test.
6311a68 Mike Burns Add a document describing how to contribute.
mike-burns authored
604
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
605 Credits
606 -------
607
608 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
609
610 Paperclip is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
611
aa55b95 Matt Jankowski thank the contributors
mjankowski authored
612 Thank you to all [the contributors](https://github.com/thoughtbot/paperclip/contributors)!
613
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
614 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
615
616 License
617 -------
618
4326a3d Prem Sichanugrist Update documentation regarding running test
sikachu authored
619 Paperclip is Copyright © 2008-2011 thoughtbot. It is free software, and may be
620 redistributed under the terms specified in the MIT-LICENSE file.
Something went wrong with that request. Please try again.