Skip to content

HTTPS clone URL

Subversion checkout URL

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