It Just Works

Paperclip on Rails 3 now just works.

Back in February 2010, I wrote about how to use Paperclip on an early beta release of Rails 3 — back then, a few small hacks were required to get Paperclip running. Now Rails 3 is at beta 4, and it’s safe to assume that we’re as close as we can be to an official Rails release — minus a few last minute tweaks, of course — and both the framework itself and the Paperclip plugin are more stable and more compatible. The good news, then, is that it’s very easy to use the Rails 3 and Paperclip together.

How To Use Paperclip With Rails 3

These instructions are good for Rails 3 beta 4, and Paperclip 9223a917. They’ll probably work on other versions of Rails and Paperclip, too.

1. Install Rails 3
2. Create a new Rails app
3. Install Paperclip
4. Create a model
5. Create a controller and views
6. Define your routes

You can find the important files (controller, model, views, and routes) in this gist, and the full application code is available on Github.

Install Rails 3

Install the latest prerelease of Rails with the following:

$ gem install rails --pre

Create a new Rails app

The command for creating Rails apps has changed in Rails 3. In the bright new future, everything is done using “rails” ¹:

$ rails new paperclip_example

Install Paperclip

Paperclip’s master branch is now good to go with Rails 3. Install from Github thus:

$ rails plugin install git://github.com/thoughtbot/paperclip.git

Create a model

In order to work with Paperclip, your model needs a few special database columns. In this case, I’m creating a User class which will have an attached avatar image.

$ rails generate model User \
avatar_file_name:string \
avatar_content_type:string \
avatar_file_size:integer \
avatar_updated_at:datetime
$ rake db:migrate

I use Paperclip’s has_attached_file method to define my avatar attachment:

class User < ActiveRecord::Base
  has_attached_file :avatar, :styles => {
    :thumb => '50x'
  }
end

Create a controller and views

I’m setting up a simple UsersController with index, new, and create actions (and corresponding routes). You’ll probably want to go further, but if all you’re interested in is proof-of-concept then this is enough.

$ rails generate controller Users

See this gist for the code in my UsersController, and the HTML in my views.

Define your routes

In config/routes.rb:

PaperclipExample::Application.routes.draw do |map|
  resources :users, :only => [:index, :new, :create]
  root :to => 'users#index'
end

Lastly, if you’re mapping your app’s root to a controller, remember to delete public/index.html.

And You’re Done

That’s really all there is to it. Use rails server to start your app and view the results. Did it work for you?

I got Paperclip working on Rails 3 today. Here’s how.

First, I found (by accident) a branch in the Paperclip repository on Github called “Rails 3″. Call me crazy but I thought that might be worth a try.

Normally you’d install Rails 3 plugins using rails plugin install, but in this case I used git submodule:

These two commands checkout the rails3 branch of Paperclip into vendor/plugins/paperclip, as a Git submodule. If you don’t understand Git submodules, you can read about them here.

I also found that Paperclip wasn’t properly handling image styles; the ‘Paperclip’ section of this post explains how I fixed this (a word of warning: it’s a simple one-line edit which solved my problem but is untested with regard to the rest of Paperclip).

As always, feel free to post questions or feedback in the comments. Good luck!

Bug: the rails command

Failed completely :) Rails my_app fails with “no value provided for required arguments ‘app_path’”. The solution to this is easy, though: first, get a local copy of Rails 3 (I cloned the Rails repo: git clone git://github.com/rails/rails.git) and then use this command instead:

The rubygems require is necessary for Rails 3 to load all the gems it needs to run.

Thoughts

The Rails command

In Rails 3, the rails command replaces script/console, script/server, etc. This is nice: commands are more meaningful (run the rails server with “rails server”), and easier to type.

ActiveRecord’s new finder syntax

ActiveRecord’s new finder syntax is lovely, and has some nice performance gains which you can read about on other blogs. Named scopes look good:

I’m going to write more about this soon.

Speed

Call me crazy but Rails 3 seems faster. Maybe this has something to do with the fact that it uses Erubis instead of ERB, or maybe I’m just easily impressed :)

Paperclip (tiny bug)

Paperclip has a branch called Rails3: I went out on a limb and guessed that was for Rails 3. It almost just worked, except for one thing: custom attachment styles weren’t being created.

If you’ve used paperclip, you’ll know you can do this:

Well, those :medium, :wide, and :small variations weren’t being created. I didn’t have time to investigate properly but this seemed to have something to do with Paperclip’s callbacks (which were returning false even when they shouldn’t be): my one line hack/fix for this:

I freely admit that this might break other parts of Paperclip, but it works for me.

Conclusions

Overall, Rails 3 feels very nice. As you’d expect from a beta it almost just works, and I’ve made a working app with it in a day. Super easy! Next up: deploying to Heroku.

1. Routes are important

The app that I was asked to rebuilt had no routes. Nothing.

That’s not to say that no URLs worked with the app, just that the mappings between URLs and controllers/actions was defined in the code itself — mostly using the old Rails convention:

This makes it very difficult to discover how a Rails app responds to a particular URL, without hunting through the controllers to find a corresponding action. It also makes working with REST a nightmare!

Lesson learnt: use routes.rb

2. Conventions are important

Rails is all about convention over configuration, of course. But when you’re coding a Rails app — especially if you’re new to Rails — it’s easy to ignore those conventions, or just be plain unaware of them.

This leads to a lot of unnecessary work. I’ve spent a lot of time over the past few months translating unconventional code into code that more closely fits the Rails way of doing things: the result is code that’s easier to test, easier to maintain, and much, much faster.

Lesson learnt: take some time to understand Rails’ conventions

3. Simplicity is important

The more I write code, the more I find myself thinking: complicated code is a Bad Thing. Of course, as a kind pedant once told me, there’s a difference between complicated and complex.

(If you don’t have a dictionary handy, “complicated” roughly means messy, difficult to understand; “complex” means many interconnected parts, or a large system. The key difference is that complex systems can be well designed: complicated systems are not.)

OK, dictionary rant over :) Messy, complicated Rails applications come about when a developer doesn’t take the time to think things through. Simplicity is normally easy if you take some time to plan your work upfront — messy code happens when things are rushed or not thought through.

Lesson learnt: think before you start coding

4. Ruby is important

Obvious, but very true: Ruby is important to Rails applications. If you’re new to coding, or new to Rails, then take some time to learn Ruby first: otherwise, you’ll miss out on the power (and beauty) of a great language and a great framework.

Lesson learnt: learn Ruby and Rails, not just Ruby on Rails!

You are important, too

Conclusions? All of the above (and more) is important when you’re developing a Rails app. And you, the developer, are important too — have fun, keep learning, and don’t work too hard. Rails should be fun :)

Which is where Rails comes in.

It’s possible to clone TinyURL using Sinatra, but I’m more interested in Rails (I think Rails probably scales better). The basic setup is so simple, it doesn’t take long to write the code, and with Rails you can always add extras like an admin interface later without much fuss.

The code

(If you’re feeling lazy, the entire URL-shortening app is available on Github)

My TinyURL-like Rails app — I call it “Shrink” — has three main components: routes, controller, and model. Routes first:

[ruby]
ActionController::Routing::Routes.draw do |map|

map.resources :locations, :only => [:new, :create]

map.with_options :controller => ‘locations’ do |map|
map.root :action => ‘new’
map.preview ‘/:shrunken/preview’, :action => ‘preview’
map.location ‘/:shrunken’, :action => ‘redirect’
end

end
[/ruby]

“Locations” are the web pages we’ll be redirecting people to when they click on a short URL.

As you can probably tell, this routes file gives us RESTful routes for creating new locations, along with a catch-all shrunken route which we’ll use to intercept our short URLs and redirect them. There’s also a preview route (more on this in a bit), and I’ve mapped the root path (‘/’) to the new action on LocationsController — this will expose the form for shortening URLs on our site’s home page.

The Controller

We only need one controller, with just a few short methods:

[ruby]
class LocationsController < ApplicationController

def new
@location = Location.new
end

def preview
@location = Location.find_by_short_url(params[:shrunken])
end

def redirect
@location = Location.find_by_short_url(params[:shrunken])
redirect_to @location.url
end

def create
@location = Location.new(params[:location])

if @location.save
redirect_to preview_path(@location)
else
flash[:notice] = ‘Invalid URL’
render :action => "new"
end
end

end
[/ruby]

That’s simple enough — the only thing to note is that we’re using Location. find_by_short_url instead of Location.find, so we can use slugs like ‘a1b3c’ instead of database record IDs in our URLs.

The preview action, by the way, just renders a view which shows the user the shortened version of their URL so they can copy and paste it into Twitter (or whatever).

The Model

[ruby]
class Location < ActiveRecord::Base

validates_presence_of :url
before_create :validate_url

class << self
def find_by_short_url(shrunk)
find(shrunk.to_i(36))
end
end

def to_param
id.to_s(36)
end

private
def validate_url
false unless url_valid?(URI.parse(self.url))
end

def url_valid?(url)
url.kind_of?(URI::HTTP) || url.kind_of?(URI::HTTPS)
end

end
[/ruby]

The model implements our find_by_short_url method, implements some validations, and overrides Rails’ default to_param to provide TinyURL-like short URLs. to_param is used in url_for; the method normally returns an object’s database ID, for URLs like /people/1, but here we return a short string like ‘a1c’ instead.

Note the calls to to_s(36) and to_i(36): these convert record IDs into shorter URL slugs, and back again, using base 36 numbering. By using base 36, we can keep our URLs as short as possible: 10000 in base 10 is ’7ps’ in base 36. Read more about this useful feature of Ruby at ruby-doc.org.

Putting it all together

The code for this app is open-source and is available on Github; download, run script/server, and go to http://0.0.0.0:3000/ and you’ll see it in action. Proof that you can clone TinyURL using Rails in less than an hour!

Update: if you’re using the plugin, have questions, or have found this post useful, take a moment to send me a message on Github, or email me (james at this domain). It’s always great to know how people are using my work :)

If you just want to get up and running as fast as possible, skip to the Plugin section at the end of the article. Feedback is always appreciated; if you use the plugin, or have questions, feel free to email me (james at this domain).

If you want to understand how the plugin works, read the full article.

Three Simple Steps

There are basically three steps to serving custom iPhone content from Rails:

1. Register a custom iphone format
2. Tell Rails how to recognize an iPhone request
3. Tell Rails to use the custom format for iPhone requests

Registering a custom iPhone format

Rails already knows about formats like HTML and XML, and all iPhones actually need from a Rails app is plain old HTML — but we need a way to distinguish our iPhone HTML from the HTML we send to other browsers.

To do this, we register a mime type alias — just a way of telling Rails that when we say ‘iphone’, we mean ‘HTML’. This is done in config/initializers/mime_types.rb:

[ruby]
Mime::Type.register_alias “text/html”, :iphone
[/ruby]

Now we can do something like format.iphone and Rails will know we want it to serve our views as HTML.

Tell Rails how to recognize an iPhone request

In order to serve custom views to iPhones, we need a way of recgonizing when someone is viewing our website on an iPhone. This is easy:

[ruby]
class ApplicationController < ActionController::Base

# other code here

private
# detect iphone requests
def iphone_request?
(agent = request.env["HTTP_USER_AGENT"]) &&
agent[/(Mobile\/.+Safari)/]
end
end
[/ruby]

The iphone_request? method looks for MobileSafari’s user agent string in the incoming HTTP request. Because MobileSafari runs on the iPod Touch as well as on the iPhone, this method will ensure that we serve our custom views to both devices.

Now we can identify iPhone requests, we just need to put everything together and…

Tell Rails to use our custom format for iPhone requests

Normally, when Rails receives a request from a browser, it determines what sort of response the browser is looking for (XML, HTTP, JSON, etc). Then it looks for corresponding templates — index.html.erb, index.xml.erb, etc. This behaviour is customizable using ActionController’s respond_to method.

In order to serve custom views to the iPhone, we need to tell Rails to switch to our custom :iphone format whenever an iPhone visits our website. This sounds complicated, but is easy:

[ruby]
class ApplicationController < ActionController::Base

before_filter :adjust_format_for_iphone_requests

private
def adjust_format_for_iphone_requests
request.format = :iphone if iphone_request?
end
end
[/ruby]

This little snippet calls our iphone_request? method and tells Rails to use our iphone format where appropriate.

That’s really all there is to it. You can now create index.iphone.erb, show.iphone.erb, etc, alongside your standard HTML views and layouts, and Rails will serve them up to iPhone users. Bon appetit!

The Plugin

Serving custom iPhone content is something I want to do from many Rails apps, so I wrapped the functionality outlined above into a plugin for quick and easy iphoneification. Install thus:

[bash]
script/plugin install git://github.com/jameswilding/iphoneification.git
[/bash]

To use the plugin, just add one line to your application controller:

[ruby]
class ApplicationController
responds_to_iphone
end
[/ruby]

If there’s a particular controller or action that you don’t want to serve iPhone content from, use

[ruby]
class NotAnIPhoneController
skip_iphone_response
end
[/ruby]

The plugin does most of the work: all you need to do is name your custom iPhone template {template_name}.iphone.erb.

As you may know, Rails 3 is a major re-working of the Rails internals — and ‘internals’ is the important word. Rails 3 will not introduce any major changes the the way Rails works for the normal Rails developer. If you compare Rails 3 application code to Rails 2 application code, you won’t see much difference.

Where you will see differences is in the Rails framework code – the stuff that implements features like routes, respond_to, render, and resources. Its fair to say that this code has undergone major changes — the guts have been ripped out and the whole framework has been put back together in a new way.

Of course it’s a testament to Rail’s strengths as a framework that a major refactoring of its code base is possible. It’s also testament to the skill of the people who are working on the code — the original Rails core team, plus new members from Merb. I’ve been following Yehuda Katz’s blog (he’s one of the guys who developed Merb) and the things he’s written about his work on Rails 3 have been really interesting.

In particular, Katz’s approach focuses more on the benefits of a well-organised Rails code base, and less on the pragmatic “make it cool as fast as possible” approach which seems to have characterised Rails up to now. That’s not to knock the later — Rails wouldn’t be where it is today if people hadn’t been willing to turn a blind eye to overly-complicated code or poor internal structures.

But these new changes are good: Rails will be as easy and as fun to use for serious developers (of plugins, for instance) as it always has been for front-end designers and application builders. It really feels like we’re getting the best of both worlds.

If you’re interested in learning more about the philosophy behind Rails 3, I recommend the following:

• Yehuda Katz’s posts about his work refactoring Rails
• DHH’s RailsConf keynote
• This presentation from a London Rails conference, which explains more about the thinking behind the Rails refactor. Treat the video like a radio show, because the picture quality is pretty bad.