Friday, January 19, 2007

Rails 1.2: REST admiration, HTTP lovefest, and UTF-8 celebrations

Posted by David

Get out your party balloons and funny hats because we’re there, baby. Yes, sire, Rails 1.2 is finally available in all it’s glory. It took a little longer than we initially anticipated to get everything lined up (and even then we had a tiny snag that bumped us straight from 1.2.0 to 1.2.1 before this announcement even had time to be written).

So hopefully it’s been worth the wait. Who am I kidding. Of course it’s been worth the wait. We got the RESTful flavor with new encouragement for resource-oriented architectures. We’re taking mime types, HTTP status codes, and multiple representations of the same resource serious. And of course there’s the international pizzazz of multibyte-safe UTF-8 wrangling.

That’s just some of the headliner features. On top of that, there’s an absolutely staggering amount of polish being dished out. The CHANGELOG for Action Pack alone contains some two hundred entries. Active Record has another 170-something on top of that.

All possible due to the amazing work of our wonderful and glorious community. People from all over the world doing their bit, however big or small, to increase the diameter of your smile. That’s love, people.

As always, you get a hold of the latest and greatest through gems:

gem install rails —include-dependencies

…or if you prefer to freeze it straight up, you can:

rake rails:freeze:edge TAG=rel_1-2-1

If you go with the gems, remember to change your version binding in config/environment.rb. Otherwise, you’ll still be tied to whatever old version you were using before.

Do note, though, that this is a massive upgrade. A few major components of Rails were left for scraps and entirely rewritten (routing and auto-loading included). We’ve tried our very best to remain backwards compatible. We’ve run multiple release candidate sessions to everyone help achieve that goal.

But it may not be perfect — heck, what is — so you’d be best advised to give your application a full and thorough work-out before contemplating a deployment. But of course, you’ve been such a good little tester bee that all what is needed is a single “rake” to see if everything passes, right?

How to get started learning all about Rails 1.2

With the fanfare out of the way, I point your attention to a rerun of the RC1 release notes on the new features. This rerun only contains the highlights, though. Real fans will want to peruse the CHANGELOGs themselves from the API.

For everyone else, there’s of course also the much easier path of just picking up the second edition of Agile Web Development with Rails. This edition was written to be spot on with 1.2 and contains a lot more elaborate guidance than you’ll find in the CHANGELOGs.

So it’s no wonder that the 2nd edition sold out the 15,000 copies of the first print run in a mere three weeks. Rest assured, though, the second run should already be available in stores. And for instant gratification, nothing beats picking up the PDF+Book combo off the Pragmatic book site.

REST and Resources

REST, and general HTTP appreciation, is the star of Rails 1.2. The bulk of these features were originally introduced to the general public in my RailsConf keynote on the subject. Give that a play to get into the mindset of why REST matters for Rails.

Then start thinking about how your application could become more RESTful. How you too can transform that 15-action controller into 2-3 new controllers each embracing a single resource with CRUDing love. This is where the biggest benefit is hidden: A clear approach to controller-design that’ll reduce complexity for the implementer and result in an application that behaves as a much better citizen on the general web.

To help the transition along, we have a scaffold generator that’ll create a stub CRUD interface, just like the original scaffolder, but in a RESTful manner. You can try it out with “script/generate scaffold_resource”. Left with no arguments like that, you get a brief introduction to how it works and what’ll create.

The only real API element that binds all this together is the new map.resources, which is used instead of map.connect to wire a resource-based controller for HTTP verb love. Then, once you have a resource-loving controller, you can link with our verb-emulation link link_to "Destroy", post_url(post), :method => :delete. Again, running the resource scaffolder will give you a feel for how it all works.

Formats and respond_to

While respond_to has been with us since Rails 1.1, we’ve added a small tweak in 1.2 that ends up making a big difference for immediate usefulness of the feature. That is the magic of :format. All new applications will have one additional default route: map.connect ':controller/:action/:id.:format'. With this route installed, imagine the following example:

class WeblogController < ActionController::Base def index @posts = Post.find :all respond_to do |format| format.html format.xml { render :xml => @posts.to_xml } format.rss { render :action => “feed.rxml” } end end end

GET /weblog # returns HTML from browser Accept header GET /weblog.xml # returns the XML GET /weblog.rss # returns the RSS

Using the Accept header to accomplish this is no longer necessary. That makes everything a lot easier. You can explore your API in the browser just by adding .xml to an URL. You don’t need a before_filter to look for clues of a newsreader, just use .rss. And all of them automatically works with page and action caching.

Of course, this format-goodness plays extra well together with map.resources, which automatically makes sure everything Just Works. The resource-scaffold generator even includes an example for this using format.xml, so /posts/5.xml is automatically wired up. Very nifty!

Multibyte

Unicode ahoy! While Rails has always been able to store and display unicode with no beef, it’s been a little more complicated to truncate, reverse, or get the exact length of a UTF-8 string. You needed to fool around with KCODE yourself and while plenty of people made it work, it wasn’t as plug’n’play easy as you could have hoped (or perhaps even expected).

So since Ruby won’t be multibyte-aware until this time next year, Rails 1.2 introduces ActiveSupport::Multibyte for working with Unicode strings. Call the chars method on your string to start working with characters instead of bytes.

Imagine the string ‘€2.99’. If we manipulate it at a byte-level, it’s easy to get broken dreams:

‘€2.99’[0,1] # => “\342” ‘€2.99’[0,2] # => “?” ‘€2.99’[0,3] # => “€”

The € character takes three bytes. So not only can’t you easily byte-manipulate it, but String#first and TextHelper#truncate used to choke too. In the old days, this would happen:

‘€2.99’.first # => ‘\342’ truncate(‘€2.99’, 2) # => ‘?’

With Rails 1.2, you of course get:

‘€2.99’.first # => ‘€’ truncate(‘€2.99’, 2) # => ‘€2’

TextHelper#truncate/excerpt and String#at/from/to/first/last automatically does the .chars conversion, but if when you need to manipulate or display length yourself, be sure to call .chars. Like:

You’ve written <%= @post.body.chars.length %> characters.

With Rails 1.2, we’re assuming that you want to play well with unicode out the gates. The default charset for action renderings is therefore also UTF-8 (you can set another with ActionController::Base.default_charset=(encoding)). KCODE is automatically set to UTF-8 as well.

Watch the screencast. (but note that manually setting the KCODE is no longer necessary)

Unicode was in greatest demand, but Multibyte is ready handle other encodings (say, Shift-JIS) as they are implemented. Please extend Multibyte for the encodings you use.

Thanks to Manfred Stienstra, Julian Tarkhanov, Thijs van der Vossen, Jan Behrens, and (others?) for creating this library.

Routes

Action Pack has an all new implementation of Routes that’s both faster and more secure, but it’s also a little stricter. Semicolons and periods are separators, so a /download/:file route which used to match /download/history.txt doesn’t work any more. Use :requirements => { :file => /.*/ } to match the period.

Auto-loading

We’ve fixed a bug that allowed libraries from Ruby’s standard library to be auto-loaded on reference. Before, if you merely reference the Pathname constant, we’d autoload pathname.rb. No more, you’ll need to manually require 'pathname' now.

We’ve also improved the handling of module loading, which means that a reference for Accounting::Subscription will look for app/models/accounting/subscription.rb. At the same time, that means that merely referencing Subscription will not look for subscription.rb in any subdir of app/models. Only app/models/subscription.rb will be tried. If you for some reason depended on this, you can still get it back by adding app/models/accounting to config.load_paths in config/environment.rb.

Prototype

To better comply with the HTML spec, Prototype’s Ajax-based forms no longer serialize disabled form elements. Update your code if you rely on disabled field submission.

For consistency Prototype’s Element and Field methods no longer take an arbitrary number of arguments. This means you need to update your code if you use Element.toggle, Element.show, Element.hide, Field.clear, and Field.present in hand-written JavaScript (the Prototype helpers have been updated to automatically generate the correct thing).


// if you have code that looks like this
Element.show('page', 'sidebar', 'content');
// you need to replace it with code like this
['page', 'sidebar', 'content'].each(Element.show);

Action Mailer

All emails are MIME version 1.0 by default, so you’ll have to update your mailer unit tests: @expected.mime_version = '1.0'

Deprecation

Since Rails 1.0 we’ve kept a stable, backward-compatible API, so your apps can move to new releases without much work. Some of that API now feels like our freshman 15 so we’re going on a diet to trim the fat. Rails 1.2 deprecates a handful of features which now have superior alternatives or are better suited as plugins.

Deprecation isn’t a threat, it’s a promise! These features will be entirely gone in Rails 2.0. You can keep using them in 1.2, but you’ll get a wag of the finger every time: look for unsightly deprecation warnings in your test results and in your log files.

Treat your 1.0-era code to some modern style. To get started, just run your tests and tend to the warnings.