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