Paperclip is an awesome rails plugin by Jon Yurek at Thoughtbot. It is one of many plugins currently available that cater for file uploading and thumbnailing (see: Attachment_fu, file_column, etc). Now a quick quote from Jon:
For some reason, file attachment is annoying. I don’t know why, and I know a lot of people have attempted to solve the problem in the past, myself included. Yet it still is. Having gotten fed up with gotchas and design decisions that we didn’t agree with, I went and wrote Paperclip on the plane to RailsConf last year. We’ve been using it here in various forms since and IMHO it’s the way to handle uploads, and finally decided that it should be released.
Installing Paperclip
You can install Paperclip using a variety of different methods:
svn export https://svn.thoughtbot.com/plugins/paperclip/tags/rel_2-0-2
piston import https://svn.thoughtbot.com/plugins/paperclip/trunk
You can also grab Paperclip from the git repository.
Quick Note: If you’re a windows user, you’re going to need to go for the trunk version as this contains a fix to a problem that basically meant that Paperclip borked.
Basic Usage
class User < ActiveRecord::Base
# Paperclip
has_attached_file :photo,
:styles => {
:thumb=> "100x100#",
:small => "150x150>" }
endAttached files don’t need to have a seperare model (thank god). Your attachments are treated just like any other atribute. Images aren’t saved until your model is saved. There are a lot of bonus options but I’ll cover them towards the end of the article.
class AddPhotoToUser < ActiveRecord::Migration
def self.up
add_column :users, :photo_file_name, :string # Original filename
add_column :users, :photo_content_type, :string # Mime type
add_column :users, :photo_file_size, :integer # File size in bytes
end
def self.down
remove_column :users, :photo_file_name
remove_column :users, :photo_content_type
remove_column :users, :photo_file_size
end
endDon’t forget to add these columns! Otherwise you’ll end up scratching your head and wondering where the hell you went wrong. The first part of the column names is the same as whatever you’re called your attached file. In our case that’s photo. Now update your database:
rake db:migrateNow that your database is sorted, we can start working on adding some content. In your view you can add a file field like you would normally:
<% form_for :user, :html => { :multipart => true } do |f| %>
<%= f.file_field :photo%>
<% end %>Don’t forget the :multipart => true part or everything will fail. Then you will cry.
Now in your controller, you don’t need to do a thing (hooray).
def create
@user = User.create(params[:user])
endYou should now be able to upload user photos to your hearts content.
To display your user’s photos all you need to do is call:
<%= image_tag @user.photo.url %>
<%= image_tag @user.photo.url(:thumb) %>The first call will display the original image. The second one will display the thumbnail image. Easy, yes?
Paperclip Options
Now that you’ve seen how easy to use and awesome Paperclip is, let’s have a look at some of the additional settings you can use:
has_attached_file :photo, :url => "/:class/:attachment/:id/:style_:basename.:extension"
Using :url you set when your images can be accessed from. The above setting would mean that your files are located at URLs similiar to /user/photo/1/thumb_originalfilename.jpg”
has_attached_file :photo, :default_url => "/:class/:attachment/missing_:style.png"The :default_url option is used if there is no attached file for a model. If a user doesn’t have any uploaded avatar you could use this option to set a default avatar to show.
has_attached_file :photo, :styles => { :normal => "100x100#", :small => ["70x70>", :jpg] }:styles is a hash of thumbnail styles. The styles use the standard ImageMagick geometry rules. Paperclip also adds the ‘#’ option which will create square thumbnails that are nicely cropped.
has_attached_file :photo, :default_style => :thumb:default_style is pretty straight forward. You can select a default style from your style list that will be called, instead of the original file, when you use @user.photo.url
has_attached_file :photo, :path => ":rails_root/public/:class/:attachment/:id/:style_:basename.:extension"
Using :path you can select where the files are saved to on your box. If you change this, make sure to change the :url setting to relate to the new path.
has_attached_file :photo, :whiny_thumbnails => true:whiny_thumbnails will raise an error if there is a problem creating thumbnails. Set to true by default.
Some Waffle
Paperclip is a great plugin. It has a smaller memory footprint than Attachment_fu, it doesn’t require the use of Rmagick (eugh) and it has all the options that I’ve wished that Attachment_fu had. Give it a try and let me know what you think
Again, maximum kudos to Jon Yurek and all the guys over at ThoughtBot.
18 Responses to “Paperclip: Attaching Files in Rails”
Hi!
Nice work, this really takes the hassle of attachment_fu. Also I was wondering if PaperClips would work with ImageScience?
Thanks!
this is AWESOME! been searching for this quite awhile, especially because attachment_fu needs extra models for attachments. will try this asap.
Thanks for the good overview! I’m glad you like it.
I should point out, though, that “:filename” isn’t valid inside of the path and url options anymore. It should be “:basename.:extension”. Also, the project is on git now for all so inclined.
[…] Paperclip: Attaching Files in Rails | Jim Neath (tags: rubyonrails upload plugin) […]
@Harold: To quote Jon: “You just need ImageMagick installed somewhere”.
@Jon: I totally forgot about :filename not being used. I was just going through paperclip.rb to look at the options but :filename still appears in there.
I’ve updated the post to use “:basename.:extension” now, and added the git repos.
Looks great, will plug this in on the next project for sure (not that attachment_fu is particularly horrible or anything). Good to keep finding fellow UK Rails people too, we just seem to keep popping up :)
Does this have a smaller memory footprint than attachment_fu+ImageScience, or attachment_fu+ImageMagick? Just wondering cause i just got through setting up all of that (with ImageScience), and i don’t really see much here that is different other than not needing an extra model for the images, which i kinda like anyhow. It would be cool to add some other effects because you are using imagemagick, maybe some stuff like annotation, round corners, drop-shadows or grayscale and sepia.
[…] Paperclip: Attaching Files in Rails | Jim Neath Paperclip is an awesome rails plugin by Jon Yurek at Thoughtbot. It is one of many plugins currently available that cater for file uploading and thumbnailing (tags: file rails uploads) […]
[…] week two must-read, hands-on posts were published: Import Gmail Contacts using Ruby on Rails and Paperclip: Attaching Files in Rails. Both cover tasks that are extremely common and useful for many web […]
Good day!
I really dig Paper-Clip.
I just have one question: Is there an option liek “has_many_attached_files”, to assign many attachments to any ActiveRecord..
Many tanks in advance!
@Kamran: I’m not entirely sure about the footprint comparisons using attachment_fu with an different image processor than ImageMagick. It would be interesting to see though
@Asis Hallab: There’s not an option to attach many files. Well, you can attach different files. You could have has_attached_file :photo and has_attached_file :doc or something, but I assume you mean attaching multiple instances of the same file type?
Dear Jim,
yes, attaching multiple instances of the same file type is just what I want to do.
Well, I’ll try creating a wrapper like ‘Attachment-Holder’ and assign multiple instances of that wrapper. It’s not truly the crown of coding, but it solves my problem for now. Don’t you think?
[…] Paperclip is a brilliant plugin by Jon Yurek over at ThoughtBot. Paperclip is used for managing file uploads and attaching the files to models. You can read more over at my article: Paperclip: Attaching Files in Rails. […]
I am having a hard time finding a real world usage for this other than your ‘avatar’ examples. More common that wanting an avatar for a user profile is the ability to attach images to a blog post for example. Being that I couldn’t have more than one image per post - it makes the whole thing pretty useless. Correct me if I am wrong (and I hope I am.) But this just seems to me like a glorified way to add images to a user profile.
Ignore my comment above, I didn’t really think that through all the way. I think what I will do is create an Attachment or Bucket Model, attach things to this model and create some special syntax to be able to link or embed them in posts.
Is there a way to incorporate this with acts_as_commentable?
I added has_attached_file to the comment.rb in the vendor/plugins dir and followed directions but its not saving the file. It keeps coming up blank.
How to store the original file name,type of file and size of file in the databse using paperclip
plz is there any one then help me
[…] Paperclip: Attaching Files in Rails | Jim Neath Paperclip is an awesome rails plugin by Jon Yurek at Thoughtbot. It is one of many plugins currently available that cater for file uploading and thumbnailing (see: Attachment_fu, file_column, etc). (tags: activerecord development file forms image photo plugin plugins programming rails ror ruby rubyonrails tutorial tutorials upload paperclip) […]