HasImage – Image attachment gem/plugin for Ruby on Rails

HasImage was created as a smaller, simpler, lighter alternative to attachment_fu for applications that need to handle uploaded images.

It creates only one database record per image, requires only one column in your model, and creates great-looking fixed-dimension thumbnails by using ImageMagick’s resize, crop and gravity functions.

Some typical use cases are: websites that want to create photo galleries with fixed-dimension thumbnails, or that want to store user profile pictures without creating a separate model for the images.

It supports only filesystem storage, and uses only MiniMagick to process images. However, the codebase is very small, simple, readable, and hackable. So it should be easy to modify or enhance its functionality with different storage or processor options.

Another image attachment library? Why?

The three chief virtues of a programmer are: Laziness, Impatience and Hubris. - Larry Wall

Attachment_fu is too large and general for some of the places I want to use images. I sometimes found myself writing more code to hack attachment_fu than it took to create this gem. In fact, most of the code here has been plucked from my various projects that use attachment_fu.

The other image attachment libraries I found fell short of my needs for various other reasons, so I decided to roll my own.

Examples

Point-and-drool use case. It’s probably not what you want, but it may be useful for bootstrapping.

class Member < ActiveRecord::Base
  has_image
end

Single image, no thumbnails, with some size limits:

class Picture < ActiveRecord::Base
  has_image :resize_to => "200x200",
    :max_size => 3.megabytes,
    :min_size => 4.kilobytes
end

Image with some thumbnails:

class Photo < ActiveRecord::Base
  has_image :resize_to => "640x480",
    :thumbnails => {
      :square => "200x200",
      :medium => "320x240"
    },
    :max_size => 3.megabytes,
    :min_size => 4.kilobytes
end

It also provides a view helper to make displaying the images extremely simple:

<%= image_tag_for(@photo) # show the full-sized image %>
<%= image_tag_for(@photo, :thumb => :square) # show the square thumbnail %>

The image_tag_for helper calls Rails’ image_tag, so you can pass in all the regular options to set the alt property, CSS class, etc:

<%= image_tag_for(@photo, :alt => "my cool picture", :class => "photo") %>

Setting up forms for has_image is simple, too:

<% form_for(@photo, :html => {:multipart => true}) do |f| %>
  <p>
    <%= f.label :image_data %>
    <%= f.file_field :image_data %>
  </p>
  <p>
    <%= f.submit %>
  </p>
<% end %>

Getting it

Has image can be installed as a gem, or as a Rails plugin. Gem installation is easiest, and recommended:

gem install has_image

and add

require 'has_image'

to your environment.rb file.

Alternatively, you can install it as a Rails plugin:

./script plugin install git://github.com/norman/has_image.git

Rails versions before 2.1 do not support plugin installation using Git, so if you’re on 2.0 (or earlier), then please install the gem rather than the plugin.

Then, make sure the model has a column named “has_image_file.”

Git repository:

git://github.com/norman/has_image.git

Hacking it

Don’t like the way it makes images? Want to pipe the images through some crazy fast seam carving library written in OCaml, or watermark them with your corporate logo? Happiness is just a monkey-patch away:

module HasImage
  class Processor
    def resize_image(size)
      # your new-and-improved thumbnailer code goes here.
    end
  end
end

HasImage follows a philosophy of “skinny model, fat plugin.” This means that it tries to pollute your ActiveRecord model with as little functionality as possible, so that in a sense, the model is acts like a “controller” and the plugin like a “model” as regards the image handling functionality. This makes it easier to test, hack, and reuse, because the storage and processing functionality is largely independent of your model, and of Rails.

My goal for HasImage is to keep it very small. If you need *a lot* of functionality that’s not here, instead of patching this code, you will likely be better off using attachment_fu, which is much more powerful, but also more complex.

Bugs

Please report them on Lighthouse.