This tutorial is an extension of the paperclip tutorial I put up last week. This time we are going to take advantage of polymorphic paperclip. Polymorphic paperclip utilizes separate tables (an assets table and an attachings table) to track your attachments. This allows for an unlimited number of attachments per item per model. In the first tutorial I showed you how to attach just one item, although you could add more columns to your table to handle additional attachments this way is a lot more flexible. While this plugin is not perfect, there is a lot of room for improvement, its a great starting point. Perhaps a fork is on its way from me…

Project Page: http://github.com/heavysixer/paperclippolymorph/tree/master

First things first, lets install the plugin:

script/plugin git://github.com/heavysixer/paperclippolymorph.git

Lets setup our new migration that is needed. After reading the rdoc, I noticed there was a new generator installed. Great, this makes things even easier. Lets verify that the generator is available for use, first run:

script/generate

This should produce a list of all generators available for use, my list below might vary from yours depending upon what plugins you have installed…

Installed Generators
  Plugins (vendor/plugins): authenticated, forgot_password, open_id_authentication_tables, paperclip, polymorphic_paperclip, roles, rspec, rspec_controller, rspec_model, rspec_scaffold, upgrade_open_id_authentication_tables
  Builtin: controller, integration_test, mailer, migration, model, observer, plugin, resource, scaffold, session_migration

As you will notice there is a polymorphic_paperclip generator, go ahead an run it as follows:

script/generate polymorphic_paperclip

Before you go and run rake db:migrate, open up the migration and modify the assets_count to attachings_count – it seems there is a minor bug. I notified the author of the plugin and will submit a patch via git. Now its OK to run rake db:migrate

Now we have the migration generated and the tables have been added to your database. Next we have to add (or change if you already have paperclip setup) the model where you want to have attachments by adding acts_as_polymorphic_paperclip. As an example, I posted my documents model below.

class Document < ActiveRecord::Base
# Document Belongs To A User
belongs_to :user
# for paperclip (polymorphic)
acts_as_polymorphic_paperclip 
# Validations
...

Note: Ideally I would like to be able to override the styles settings that are set in the plugins assets.rb, however I went ahead and hard coded them there to fit my needs. Example:

class Asset < ActiveRecord::Base
  has_many :attachings, :dependent => :destroy
  has_attached_file :data,
                    :styles => {
                    :thumb=> "100x100#",
                    :small  => "150x150>",
                    :medium => "300x300>",
                    :large =>   "500x500>",
                    :xlarge =>   "600x600>",
                    :xxlarge =>   "800x800>" }

For now, lets move onto the views where you are going to allow attachments. We are just going to have one upload, perhaps in another tutorial we will look at handling multiple uploads.

You need to make sure you put the html => { :multipart => true } in both your edit and new views for the model you are working with. Example in my case:

<% form_for(@document,:html => { :multipart => true }) do |f| %>
  <%= f.error_messages %>
  <%= render :partial => 'form', :locals => { :f => f } %>
<% end %>

Next you need to add the file upload field to your _form or edit/new views.

<p>
  Attach a file or image <br />
  <%= f.file_field :data%>
</p>

Now lets go ahead and make these attachments viewable in the document. For the edit view I added the following:

<p><%= image_tag asset.url(:medium) %></p>
<p>Tiny:  <%= asset.url(:tiny) %><br />
 Small:  <%= asset.url(:small)%><br />
 Medium:  <%= asset.url(:medium)%><br />
 Large:  <%= asset.url(:large)%><br />
 XL:  <%= asset.url(:xlarge)%><br />
 XXL:  <%= asset.url(:xxlarge)%><br />   
 Original:  <%= asset.url %>
</p>

Other Notes:

You can use this to attach an attachment if you were going to use a different view, for example an upload view with @document.assets.attach(@asset)

You can nuke an attachment by either calling @document.assets.detach or @document.assets.detach(@asset) depending upon how you are going about dealing with removing attachments. @document.assets.detach will nuke ALL attachments associated with that document, @document.essay.assets.detach(@asset) will nuke just that asset you are referencing.

I used Paperclip for my latest project, and I figured I would give a brief tutorial on how to use it.

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 much like other attributes as possible. http://github.com/thoughtbot/paperclip/tree/master

In my case, I wanted to allow an attachment to an Event, which will have one photo.

To install:

script/plugin install git://github.com/thoughtbot/paperclip.git

Create your migration, again in my case I was adding the images to my Events model / DB, so I did the following:

script/generate migration AddPhotosToEvents

Open up your newly created migration with your favorite Text editor, and add the following:

class AddPhotoToEvent < ActiveRecord::Migration
  def self.up
    add_column :events, :photo_file_name, :string
    add_column :events, :photo_content_type, :string
    add_column :events, :photo_file_size, :integer
  end
 
  def self.down
    remove_column :events, :photo_file_name
    remove_column :events, :photo_content_type
    remove_column :events, :photo_file_size
  end
end

Then rake your migration so the new columns are added to your database:

rake db:migrate

Next you need to tell your model to use Paperclip, again I am using the Event model as an example, the #Paperclip and below is what you need to add. If you notice below I added 4 options to the :styles. I wanted to have a few different sizes generated when a image was uploaded, i named them appropriately (you can name them whatever you wish). Please note when you put a # on the end it signifies that you want that exact aspect ratio, it will crop your photo automatically. When you use > on the end it will make the largest side the size you specify and keep the aspect ratio uploaded. In addition note that because we specified has_attached_file :photo its going to look for that naming convention we created in the migration above. In addition it uses that name to store your photo in the public folder of your application. So our photo url is going to be as follows: /public/photos/(event#)/(size_name)/image_name

class Event < ActiveRecord::Base
belongs_to :user
validates_presence_of :title, :on => :create, :message => "can't be blank"
validates_presence_of :teaser, :on => :create, :message => "can't be blank"
validates_presence_of :subject, :on => :create, :message => "can't be blank"
# Paperclip
has_attached_file :photo,
  :styles => {
    :thumb=> "100x100#",
    :small  => "150x150>",
    :medium => "300x300>",
    :large =>   "400x400>" }

Next you need to make sure you put the html => { :multipart => true } in both your edit and new views for the model you are working with. Example in my case:

<% form_for(@event,:html => { :multipart => true }) do |f| %>
  <%= f.error_messages %>
  <%= render :partial => 'form', :locals => { :f => f } %>
<% end %>

You then need to add the file_field to your new and edit forms or your _form partial like in my case:

<p>
  <%= f.label 'Photo' %><br />
  <%= f.file_field :photo %>
</p>

Next up is deciding on how you are going to use / view your images. In my case I wanted to show a few different sizes in the Event view. I also wanted to make sure I am only going to show photo’s if one exists. In this example I am just showing the small and medium sizes we generated:

<% if @event.photo.exists? then %>
<p>Small:<%= image_tag @event.photo.url(:small) %></p>
<p>Medium:<%= image_tag @event.photo.url(:medium) %></p>
<% else %>
<p> There are no photo's attached, upload one. </p>
<% end %>

A few other notes…

Calling @event.photo.nil destroys the photo

Also checkout this great tutorial Jim put up here.

Thats all for now, I’ll try to post an update with some more options / features when using the Paperclip plugin in the future.

*** Checkout my other tutorial on polymorphic paperclip if you would like to have multiple image attachments.