Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 259 lines (191 sloc) 10.505 kb
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
1 Paperclip
2 =========
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
3
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
4 Paperclip is intended as an easy file attachment library for ActiveRecord. The
5 intent behind it was to keep setup as easy as possible and to treat files as
6 much like other attributes as possible. This means they aren't saved to their
7 final locations on disk, nor are they deleted if set to nil, until
8 ActiveRecord::Base#save is called. It manages validations based on size and
9 presence, if required. It can transform its assigned image into thumbnails if
10 needed, and the prerequisites are as simple as installing ImageMagick (which,
11 for most modern Unix-based systems, is as easy as installing the right
12 packages). Attached files are saved to the filesystem and referenced in the
13 browser by an easily understandable specification, which has sensible and
14 useful defaults.
15
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
16 See the documentation for `has_attached_file` in Paperclip::ClassMethods for
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
17 more detailed options.
18
0d395b6 fix the link to rdoc
Chad Pytel authored
19 The complete [RDoc](http://rdoc.info/gems/paperclip) is online.
7150016 @croaky added mailing list, issues queue, and rdoc links to README
croaky authored
20
beff127 @nathanl Made the ImageMagick requirement more prominent
nathanl authored
21 Requirements
22 ------------
23
24 ImageMagick must be installed and Paperclip must have access to it. To ensure
25 that it does, on your command line, run `which convert` (one of the ImageMagick
26 utilities). This will give you the path where that utility is installed. For
27 example, it might return `/usr/local/bin/convert`.
28
29 Then, in your environment config file, let Paperclip know to look there by adding that
30 directory to its path.
31
32 In development mode, you might add this line to `config/environments/development.rb)`:
33
34 Paperclip.options[:command_path] = "/usr/local/bin/"
35
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
36 Installation
37 ------------
6961912 @croaky added twiddle wakka/Gemfile installation instructions to README
croaky authored
38
3dacda3 @jyurek Clarify installation instructions in README
jyurek authored
39 Paperclip is distributed as a gem, which is how it should be used in your app. It's
40 technically still installable as a plugin, but that's discouraged, as Rails plays
41 well with gems.
42
6961912 @croaky added twiddle wakka/Gemfile installation instructions to README
croaky authored
43 Include the gem in your Gemfile:
44
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
45 gem "paperclip", "~> 2.3"
7150016 @croaky added mailing list, issues queue, and rdoc links to README
croaky authored
46
3dacda3 @jyurek Clarify installation instructions in README
jyurek authored
47 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
48
3dacda3 @jyurek Clarify installation instructions in README
jyurek authored
49 # In config/environment.rb
50 ...
51 Rails::Initializer.run do |config|
52 ...
53 config.gem "paperclip", :version => "~> 2.3"
54 ...
55 end
289d9cf @tilsammans include installation instructions
tilsammans authored
56
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
57 Quick Start
58 -----------
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
59
60 In your model:
61
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
62 class User < ActiveRecord::Base
63 has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
64 end
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
65
66 In your migrations:
67
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
68 class AddAvatarColumnsToUser < ActiveRecord::Migration
69 def self.up
70 add_column :users, :avatar_file_name, :string
71 add_column :users, :avatar_content_type, :string
72 add_column :users, :avatar_file_size, :integer
73 add_column :users, :avatar_updated_at, :datetime
74 end
75
76 def self.down
77 remove_column :users, :avatar_file_name
78 remove_column :users, :avatar_content_type
79 remove_column :users, :avatar_file_size
80 remove_column :users, :avatar_updated_at
81 end
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
82 end
83
84 In your edit and new views:
85
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
86 <% form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
87 <%= form.file_field :avatar %>
88 <% end %>
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
89
90 In your controller:
91
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
92 def create
93 @user = User.create( params[:user] )
94 end
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
95
96 In your show view:
97
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
98 <%= image_tag @user.avatar.url %>
99 <%= image_tag @user.avatar.url(:medium) %>
100 <%= image_tag @user.avatar.url(:thumb) %>
edfff2f @jyurek Moved README to README.rdoc
jyurek authored
101
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
102 Usage
103 -----
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
104
105 The basics of paperclip are quite simple: Declare that your model has an
106 attachment with the has_attached_file method, and give it a name. Paperclip
107 will wrap up up to four attributes (all prefixed with that attachment's name,
d64d131 @sikachu Edit README to fix Typo
sikachu authored
108 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
109 friendly front end. The attributes are `<attachment>_file_name`,
110 `<attachment>_file_size`, `<attachment>_content_type`, and `<attachment>_updated_at`.
111 Only `<attachment>_file_name` is required for paperclip to operate. More
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
112 information about the options to has_attached_file is available in the
113 documentation of Paperclip::ClassMethods.
114
115 Attachments can be validated with Paperclip's validation methods,
249bf0a Revert "fix the <attachment> stuff for markdown"
Chad Pytel authored
116 validates_attachment_presence, validates_attachment_content_type, and
117 validates_attachment_size.
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
118
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
119 Storage
120 -------
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
121
122 The files that are assigned as attachments are, by default, placed in the
123 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
124 location is ":rails_root/public/system/:attachment/:id/:style/:filename". This
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
125 location was chosen because on standard Capistrano deployments, the
126 public/system directory is symlinked to the app's shared directory, meaning it
127 will survive between deployments. For example, using that :path, you may have a
128 file at
129
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
130 /data/myapp/releases/20081229172410/public/system/avatars/13/small/my_pic.png
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
131
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
132 _NOTE: This is a change from previous versions of Paperclip, but is overall a
133 safer choice for the default file store._
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
134
135 You may also choose to store your files using Amazon's S3 service. You can find
136 more information about S3 storage at the description for
137 Paperclip::Storage::S3.
138
139 Files on the local filesystem (and in the Rails app's public directory) will be
140 available to the internet at large. If you require access control, it's
141 possible to place your files in a different location. You will need to change
142 both the :path and :url options in order to make sure the files are unavailable
143 to the public. Both :path and :url allow the same set of interpolated
144 variables.
145
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
146 Post Processing
147 ---------------
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
148
6539e54 @jyurek Updated documentation and gemspec for 2.2.9
jyurek authored
149 Paperclip supports an extensible selection of post-processors. When you define
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
150 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
151 "styles" are actually "thumbnails". However, you can do much more than just
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
152 thumbnail images. By defining a subclass of Paperclip::Processor, you can
153 perform any processing you want on the files that are attached. Any file in
9dd008d @jyurek Doc typo fix thanks to Rymai
jyurek authored
154 your Rails app's lib/paperclip_processors directory is automatically loaded by
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
155 paperclip, allowing you to easily define custom processors. You can specify a
156 processor with the :processors option to has_attached_file:
157
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
158 has_attached_file :scan, :styles => { :text => { :quality => :better } },
159 :processors => [:ocr]
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
160
161 This would load the hypothetical class Paperclip::Ocr, which would have the
162 hash "{ :quality => :better }" passed to it along with the uploaded file. For
163 more information about defining processors, see Paperclip::Processor.
164
165 The default processor is Paperclip::Thumbnail. For backwards compatability
166 reasons, you can pass a single geometry string or an array containing a
167 geometry and a format, which the file will be converted to, like so:
168
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
169 has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
170
171 This will convert the "thumb" style to a 32x32 square in png format, regardless
172 of what was uploaded. If the format is not specified, it is kept the same (i.e.
173 jpgs will remain jpgs).
174
175 Multiple processors can be specified, and they will be invoked in the order
176 they are defined in the :processors array. Each successive processor will
177 be given the result of the previous processor's execution. All processors will
178 receive the same parameters, which are what you define in the :styles hash.
179 For example, assuming we had this definition:
180
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
181 has_attached_file :scan, :styles => { :text => { :quality => :better } },
182 :processors => [:rotator, :ocr]
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
183
3be55fc @joshuaclayton Clean up whitespace
joshuaclayton authored
184 then both the :rotator processor and the :ocr processor would receive the
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
185 options "{ :quality => :better }". This parameter may not mean anything to one
6539e54 @jyurek Updated documentation and gemspec for 2.2.9
jyurek authored
186 or more or the processors, and they are expected to ignore it.
187
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
188 _NOTE: Because processors operate by turning the original attachment into the
189 styles, no processors will be run if there are no styles defined._
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
190
4d843c9 @sikachu Add a comment to mention `attachment_on_the_fly` gem
sikachu authored
191 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
192 database, take a look at the [paperclip-meta](https://github.com/y8/paperclip-meta) gem.
193
4d843c9 @sikachu Add a comment to mention `attachment_on_the_fly` gem
sikachu authored
194 Also, if you're interesting to generate the thumbnail on-the-fly, you might want
195 to look into the [attachment_on_the_fly](https://github.com/drpentode/Attachment-on-the-Fly) gem.
196
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
197 Events
198 ------
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
199
200 Before and after the Post Processing step, Paperclip calls back to the model
201 with a few callbacks, allowing the model to change or cancel the processing
32f458a fix <attachment> markup in events section
Chad Pytel authored
202 step. The callbacks are `before_post_process` and `after_post_process` (which
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
203 are called before and after the processing of each attachment), and the
32f458a fix <attachment> markup in events section
Chad Pytel authored
204 attachment-specific `before_<attachment>_post_process` and
205 `after_<attachment>_post_process`. The callbacks are intended to be as close to
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
206 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
207 - 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
208 will halt. Returning false in an after_ filter will not halt anything, but you
209 can access the model and the attachment if necessary.
210
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
211 _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
212 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
213 called with valid attachments._
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
214
693a071 @maxim Add link to the pull request explaining URI-obfuscation with :hash in…
maxim authored
215 URI Obfuscation
216 ---------------
217
218 Paperclip has an interpolation called `:hash` for obfuscating filenames of publicly-available files. For more on this feature read author's own explanation.
219
220 [https://github.com/thoughtbot/paperclip/pull/416](https://github.com/thoughtbot/paperclip/pull/416)
221
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
222 Testing
223 -------
4c6cf39 @jferris Added documentation for rspec matchers
jferris authored
224
225 Paperclip provides rspec-compatible matchers for testing attachments. See the
13d51e3 @qrush Update readme with link to docs for rspec matcher
qrush authored
226 documentation on [Paperclip::Shoulda::Matchers](http://rubydoc.info/gems/paperclip/Paperclip/Shoulda/Matchers)
227 for more information.
4c6cf39 @jferris Added documentation for rspec matchers
jferris authored
228
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
229 Contributing
230 ------------
fd2333e @jyurek Added a Contributing section to the README
jyurek authored
231
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
232 If you'd like to contribute a feature or bugfix: Thanks! To make sure your
233 fix/feature has a high chance of being included, please read the following
234 guidelines:
fd2333e @jyurek Added a Contributing section to the README
jyurek authored
235
7150016 @croaky added mailing list, issues queue, and rdoc links to README
croaky authored
236 1. Ask on the mailing list[http://groups.google.com/group/paperclip-plugin], or
237 post a new GitHub Issue[http://github.com/thoughtbot/paperclip/issues].
7212775 @jyurek Lots more documentation, including events and processors
jyurek authored
238 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
239 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
240 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
241
6311a68 @mike-burns Add a document describing how to contribute.
mike-burns authored
242 Please see CONTRIBUTING.md for details.
243
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
244 Credits
245 -------
246
247 ![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
248
249 Paperclip is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
250
aa55b95 @mjankowski thank the contributors
mjankowski authored
251 Thank you to all [the contributors](https://github.com/thoughtbot/paperclip/contributors)!
252
deff9cf convert the readme to markdown and add proper trademark and license info
Chad Pytel authored
253 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
254
255 License
256 -------
257
258 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.