Beautiful Pixel

SuperImage is deprecated, use FlexImage instead.

SuperImage is a plugin that allows you to put image data in your database And retrieve at any size you like. Combine this with page caching and you have a fast and easy way to manage large numbers of uploaded files.

Installation:

ruby script/plugin install http://beautifulpixel.textdriven.com/svn/plugins/super_image/

Prerequisites

RMagick must be installed

Migration

Usage is simple. First, you must create the table used by SuperImage. At a command prompt in the root of your rails app:

ruby script/generate super_image_migration
rake migrate

This will ceate the a table in your database called super_images.

The reason to keep this in a separate table (rather than a field on your users or products tables) is to keep databse bandwidth down since you rarely need the image data when you are retrieving the images parent object.

Controller

In order to view the image you simply need to include the proper module in your controller. This is done with include SuperImagePlugin::Show

We will also add a method to process an uploaded file, creating a new database row for the image.

class MyControllerNameController < ApplicationController
  include SuperImagePlugin::Show
  caches_page :show_image
  def create
    img = SuperImage.create(:data => params[:image][:data])
    redirect_to :action => 'show_image', :id => img
  end
end

include SuperImagePlugin::Show adds the show_image method to your controller. show_image is the action you use to view the images in your database.

The create method takes advantage of the #data= method defined in the SuperImage model which automatically processes an uploaded file and puts it in the database.

The caches_page :show_image allows the result of the queries for image to becached to the file system. This is a good idea because the bandwidth of pulling image data out of your database is high, and the image resample procedure is much slower than simply loading an image from the filesystem. This way its the image is only processed the first time it is called at a particular size, every request after that will retrieve the cached version at lightning speed.

View

We still need a form to get uploaded images into the database. Create a new html file in app/views/my_controller_name/new.rhtml with the following simple form:

<%= form_tag({:action => 'create'}, {:multipart => true})%>
  <%= file_field 'image', 'data' %>
  <%= submit_tag %>
<%= end_form_tag %>

Upload

Now find a file on your hard drive and upload via the form at /my_controller_name/new. You should be redirected to your image, displayed in the browser.

Using on a page with URL helpers

To include a link to an image in your view, simply use the #show_image action of your images controller:

<%= image_tag(url_for(:controller => 'my_controller_name',
                      :action     => 'show_image',
                      :id         => @img.id,       # The id of the image you want to show.
                      :size       => 175            # The size of the image you want returned.
              ), 
              :alt => "Image #{@img.id}") %>

Or with a route

map.my_image 'user_photos/:id/:size',
  :controller => 'my_images_controller',
  :action => 'show_image',
  :size => nil

<%= image_tag my_image_url(:id => 123), :alt => 'it's an image!' %>
<%= image_tag my_image_url(:id => 12, :size => 100) %>

Or simply navigate to /my_controller_name/show_image/1. And to use the size constraint navigate to /my_controller_name/show_image/1?size=120. You can write custom url routes to make the size parameter prettier, like in the above route which would generate /user_photos/12/100 for the image url.

The size parameter is the size of the largest dimension of the image. For example, a 640×480 image is requested with :size => 100. The image will be rendered at 100×75. Aspect Ratio is always preserved.

Remember that SuperImage inherits from ActiveRecord and works just like every other model in Rails. It simply has a small amount of added functionality. This also means you can base your own models around SuperImage, just inherit form SuperImage instead of ActiveRecord::Base.