Skip to content
Browse files

convert the readme to markdown and add proper trademark and license info

  • Loading branch information...
1 parent 7a38ef7 commit deff9cf5197a4a60ef0bba357cd7e1592b26a626 Chad Pytel committed Jan 19, 2011
Showing with 76 additions and 55 deletions.
  1. +76 −55 README.rdoc → README.md
View
131 README.rdoc → README.md
@@ -1,4 +1,5 @@
-=Paperclip
+Paperclip
+=========
Paperclip is intended as an easy file attachment library for ActiveRecord. The
intent behind it was to keep setup as easy as possible and to treat files as
@@ -12,84 +13,86 @@ packages). Attached files are saved to the filesystem and referenced in the
browser by an easily understandable specification, which has sensible and
useful defaults.
-See the documentation for +has_attached_file+ in Paperclip::ClassMethods for
+See the documentation for `has_attached_file` in Paperclip::ClassMethods for
more detailed options.
The complete RDoc[http://rdoc.info/gems/paperclip] is online.
-==Installation
+Installation
+------------
Include the gem in your Gemfile:
- gem "paperclip", "~> 2.3"
+ gem "paperclip", "~> 2.3"
-==Installation
-
-As a plugin:
+Or as a plugin:
ruby script/plugin install git://github.com/thoughtbot/paperclip.git
-==Quick Start
+Quick Start
+-----------
In your model:
- class User < ActiveRecord::Base
- has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
- end
+ class User < ActiveRecord::Base
+ has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
+ end
In your migrations:
- class AddAvatarColumnsToUser < ActiveRecord::Migration
- def self.up
- add_column :users, :avatar_file_name, :string
- add_column :users, :avatar_content_type, :string
- add_column :users, :avatar_file_size, :integer
- add_column :users, :avatar_updated_at, :datetime
- end
-
- def self.down
- remove_column :users, :avatar_file_name
- remove_column :users, :avatar_content_type
- remove_column :users, :avatar_file_size
- remove_column :users, :avatar_updated_at
+ class AddAvatarColumnsToUser < ActiveRecord::Migration
+ def self.up
+ add_column :users, :avatar_file_name, :string
+ add_column :users, :avatar_content_type, :string
+ add_column :users, :avatar_file_size, :integer
+ add_column :users, :avatar_updated_at, :datetime
+ end
+
+ def self.down
+ remove_column :users, :avatar_file_name
+ remove_column :users, :avatar_content_type
+ remove_column :users, :avatar_file_size
+ remove_column :users, :avatar_updated_at
+ end
end
- end
In your edit and new views:
- <% form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
- <%= form.file_field :avatar %>
- <% end %>
+ <% form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
+ <%= form.file_field :avatar %>
+ <% end %>
In your controller:
- def create
- @user = User.create( params[:user] )
- end
+ def create
+ @user = User.create( params[:user] )
+ end
In your show view:
- <%= image_tag @user.avatar.url %>
- <%= image_tag @user.avatar.url(:medium) %>
- <%= image_tag @user.avatar.url(:thumb) %>
+ <%= image_tag @user.avatar.url %>
+ <%= image_tag @user.avatar.url(:medium) %>
+ <%= image_tag @user.avatar.url(:thumb) %>
-==Usage
+Usage
+-----
The basics of paperclip are quite simple: Declare that your model has an
attachment with the has_attached_file method, and give it a name. Paperclip
will wrap up up to four attributes (all prefixed with that attachment's name,
so you can have multiple attachments per model if you wish) and give the a
-friendly front end. The attributes are <attachment>_file_name,
-<attachment>_file_size, <attachment>_content_type, and <attachment>_updated_at.
-Only <attachment>_file_name is required for paperclip to operate. More
+friendly front end. The attributes are `<attachment>_file_name`,
+`<attachment>_file_size`, `<attachment>_content_type`, and `<attachment>_updated_at`.
+Only `<attachment>_file_name` is required for paperclip to operate. More
information about the options to has_attached_file is available in the
documentation of Paperclip::ClassMethods.
Attachments can be validated with Paperclip's validation methods,
validates_attachment_presence, validates_attachment_content_type, and
validates_attachment_size.
-==Storage
+Storage
+-------
The files that are assigned as attachments are, by default, placed in the
directory specified by the :path option to has_attached_file. By default, this
@@ -99,10 +102,10 @@ public/system directory is symlinked to the app's shared directory, meaning it
will survive between deployments. For example, using that :path, you may have a
file at
- /data/myapp/releases/20081229172410/public/system/avatars/13/small/my_pic.png
+ /data/myapp/releases/20081229172410/public/system/avatars/13/small/my_pic.png
-NOTE: This is a change from previous versions of Paperclip, but is overall a
-safer choice for the default file store.
+_NOTE: This is a change from previous versions of Paperclip, but is overall a
+safer choice for the default file store._
You may also choose to store your files using Amazon's S3 service. You can find
more information about S3 storage at the description for
@@ -115,7 +118,8 @@ both the :path and :url options in order to make sure the files are unavailable
to the public. Both :path and :url allow the same set of interpolated
variables.
-==Post Processing
+Post Processing
+---------------
Paperclip supports an extensible selection of post-processors. When you define
a set of styles for an attachment, by default it is expected that those
@@ -126,8 +130,8 @@ your Rails app's lib/paperclip_processors directory is automatically loaded by
paperclip, allowing you to easily define custom processors. You can specify a
processor with the :processors option to has_attached_file:
- has_attached_file :scan, :styles => { :text => { :quality => :better } },
- :processors => [:ocr]
+ has_attached_file :scan, :styles => { :text => { :quality => :better } },
+ :processors => [:ocr]
This would load the hypothetical class Paperclip::Ocr, which would have the
hash "{ :quality => :better }" passed to it along with the uploaded file. For
@@ -137,7 +141,7 @@ The default processor is Paperclip::Thumbnail. For backwards compatability
reasons, you can pass a single geometry string or an array containing a
geometry and a format, which the file will be converted to, like so:
- has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
+ has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
This will convert the "thumb" style to a 32x32 square in png format, regardless
of what was uploaded. If the format is not specified, it is kept the same (i.e.
@@ -149,17 +153,18 @@ be given the result of the previous processor's execution. All processors will
receive the same parameters, which are what you define in the :styles hash.
For example, assuming we had this definition:
- has_attached_file :scan, :styles => { :text => { :quality => :better } },
- :processors => [:rotator, :ocr]
+ has_attached_file :scan, :styles => { :text => { :quality => :better } },
+ :processors => [:rotator, :ocr]
then both the :rotator processor and the :ocr processor would receive the
options "{ :quality => :better }". This parameter may not mean anything to one
or more or the processors, and they are expected to ignore it.
-NOTE: Because processors operate by turning the original attachment into the
-styles, no processors will be run if there are no styles defined.
+_NOTE: Because processors operate by turning the original attachment into the
+styles, no processors will be run if there are no styles defined._
-==Events
+Events
+------
Before and after the Post Processing step, Paperclip calls back to the model
with a few callbacks, allowing the model to change or cancel the processing
@@ -172,16 +177,18 @@ normal ActiveRecord callbacks as possible, so if you return false (specifically
will halt. Returning false in an after_ filter will not halt anything, but you
can access the model and the attachment if necessary.
-NOTE: Post processing will not even *start* if the attachment is not valid
+_NOTE: Post processing will not even *start* if the attachment is not valid
according to the validations. Your callbacks and processors will *only* be
-called with valid attachments.
+called with valid attachments._
-==Testing
+Testing
+-------
Paperclip provides rspec-compatible matchers for testing attachments. See the
documentation on Paperclip::Shoulda::Matchers for more information.
-==Contributing
+Contributing
+------------
If you'd like to contribute a feature or bugfix: Thanks! To make sure your
fix/feature has a high chance of being included, please read the following
@@ -192,3 +199,17 @@ guidelines:
2. Make sure there are tests! We will not accept any patch that is not tested.
It's a rare time when explicit tests aren't needed. If you have questions
about writing tests for paperclip, please ask the mailing list.
+
+Credits
+-------
+
+![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
+
+Paperclip is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
+
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+
+License
+-------
+
+Paperclip is Copyright © 2008-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.

0 comments on commit deff9cf

Please sign in to comment.
Something went wrong with that request. Please try again.