Documentation push

We’ve recently decided to put some work into Rails documentation. We’d like to flesh out the existing docs, add documentation for the corners that are lacking and update what may have gone stale.

Kevin Clark is leading up this campaign and would like to get the help of the community at large.

He’s got a write up that goes over how you can help Documenting Rails . It summarizes what we are looking for and gives basic instructions to get those who are interested in helping up and running. The main guidelines are:

  • Write to teach
  • Provide examples
  • Don’t restate the obvious

Good documentation patches are right up there with good code patches. If you’d like to help out Rails while gaining a deeper understanding of how it works, taking part in this documentation project would be a great start.

The Complete Guide to Rails Plugins

Plugins are the official way to bend Rails to do your bidding. Creating a plugin is a great way to share your Rails extensions with others who may find them useful. Until recently though, resources on plugins have been scattered around various blog articles and mailing list posts.

Mr. Rails Podcast Geoffrey Grosenbach has pulled together these various resources and done the homework for you. Presented in several parts, here is Part I of The Complete Guide to Rails Plugins.

This first installment is an introductory overview. He covers how to find and install plugins, lists the various points of entry into your Rails app that plugins can hook into as well as summarizing the parts they generally consist of. He’s got an explanation for each default file and directory that gets generated for a new plugin.

With this primer you’ll be all set for making your own plugin when Part II comes around.

RailsConf Europe: September 14-15 in London

The first RailsConf scheduled for June 22-25 in Chicago sold out so fast it made our heads spin. 550 seats were snatched up before the program was even ready or a week had passed. That left a lot of people from Europe and even the US without much of a chance to participate.

Here comes the remedy: RailsConf Europe. From September 14th to 15th, London will set the stage for the second official Ruby on Rails conference.

The program has yet to be finalized, but a good number of headliners have already been confirmed: Dave Thomas, Jamis Buck, Jim Weirich, and my favorite blogger and thinker on passion, Kathy Sierra. Marcel Molina, David A. Black, Chad Fowler, and yours truly are also lined up. A call for proposals should be going up shortly to fill in the rest.

Bringing over that many speakers from the US and putting them and the conference up in central London ain’t cheap, though. So the sticker might carry a bit of an initial shock. There’s a super-early bird special of £400 and the rates then travel from there to a just-before price of £575.

But none of the speakers are taking home a dime and Chad Fowler has been working his ass off for free through RubyCentral, which is the non-profit organization putting on this show. They have in the past used profits from conferences to fund Ruby hackathons. So at least you know your quid isn’t being blown on white powdery rails. All the hype is 100% home-grown.

To the tune of that violin, let me just remind that as with RailsConf Chicago, there’re a limited number of seats. Roughly 500 spots. When they’re gone, they’re gone. If you want to go to an official Rails conference this year, meet and hear the core team among others speak, this is the last chance.

See you all in London in September!

Radiant released: Content Management Simplified

John Long has announced the initial release of Radiant, the simple and elegant CMS that is planned to eventually power the redesigned reincarnation of the official Ruby website,

You can take a look at some screenshots, check out the demo, read the source, subscribe to the mailing list, and follow along on the weblog.

Underneath the sheets, John is using his custom templating library Radius, on top of which he’s implemented his so called Behaviors. To help you dig into such features, John has provided some starting points for learning Radiant as well as a quickstart for Radius. If you want to jump aboard and help the development, he’s providing some tips on how you can contribute.

svn co

Things called a CMS are notoriously complex. Cheers for keeping it simple.

Agile Web Development with Rails goes second edition

It’s back. Agile Web Development with Rails is now available in a 50%-done beta version of its second edition. Pretty much everything is getting a major overhaul. All the cool stuff we’ve added in Rails 1.1 is covered in the same structure that people so liked from the first version.

It’s wonderful to be able to present a version two of the primary title that has helped so many people get into Rails. And through the wonders of PDFs and agile publishing, to have it available so soon.

So if you’re interested in getting the latest scoop on everything from RJS, to join models, to migrations, to RESTful interfaces, to Capistrano, this is most definitely the book to get.

P.S.: Just so you don’t feel buyers remorse two days after getting a PDF of the first edition, anyone that bought that PDF on or after April 1st gets a free upgrade to the second edition.

Both Dave Thomas and I covered the announcement in additional detail.

Associations aren't :dependent => true anymore

Up until the 1.1 release, the way to automatically destroy has_many associations when the owner was itself destroyed was to either use the :dependent or :exclusively_dependent option when declaring the has_many.

class Account < ActiveRecord::Base
  has_many :members, :dependent => true


class Brand < ActiveRecord::Base
  has_many :products, :exclusively_dependent => true

The :dependent option instantiated all the associated objects and called destroy on each one. Destroy in turn triggers the callbacks defined on that associated model, such as those declared with before_destroy and after_destroy.

The :exclusively_dependent option, on the other hand, did not instantiate all the associated objects. Rather, it just generated a single SQL statement which deleted the associated records without first creating objects for each one. This buys you efficiency when you have no need for the flexibility of triggering model callbacks.

Since 1.1, the API for garbage collecting associated records has been consolidated into the :dependent option. Rather than saying :dependent => true, you now pass one of several symbols to the :dependent option which describes how the association is dependent on the owner.

Declaring the has many as :dependent => :destroy is the same as what used to be declared as :dependent => true. When the owner is destroyed, all the associated records are instantiated and destroyed.

class Account < ActiveRecord::Base
  # Deprecated
  # has_many :members, :dependent => true
  # In favor of
  has_many :members, :dependent => :destroy

The new way to achieve the now deprecated :exclusively_dependent configuration is to use :dependent => :delete_all rather than :dependent => :destroy.

class Brand < ActiveRecord::Base
  # Deprecated
  # has_many :products, :exclusively_dependent => true

  # In favor of
  has_many :products, :dependent => :delete_all

The :destroy and :delete_all option symbols are so named because they correspond with the behavior achieved by calling destroy versus delete on a model object. One triggers callbacks, the other just generates the delete SQL statement.

As an aside, another valid option is :dependent => :nullify which is similar to :dependent => :delete_all except rather than deleting the associated records, it just sets their foreign keys to NULL. This effectively removes the association, without removing the associated records from the database table.

As always, the semantics of :dependent => :destroy and :dependent => :delete_all are mutually exclusive, which this new API makes a bit more apparent.

It should be noted that declaring dependencies is not required when setting up has many associations. It is simply an option for when you desire such functionality.

Keep in mind that for now :dependent => true and :exclusively_dependent => true will still be supported, but they have been marked as deprecated and could be taken out in the future.

New in Rails: Module#alias_method_chain

Though not an outward facing feature, changeset 4276 introduces a nice method to DRY up and encapsulate the common pattern of aliasing a method so that you can build behavior on top of it.

All over the internals of Rails you’ll find code like this in a module:

  module Layout #:nodoc:
    def self.included(base)
      base.class_eval do
        alias_method :render_with_no_layout, :render
        alias_method :render, :render_with_a_layout

  1. … etc

This makes it so that when the module is included into the base class, it adds behavior onto some method in that class without the method having to be aware of the fact that it’s being enhanced. In this case, the render method of ActionController::Base is enhanced to wrap its output in a layout.

The new Module#alias_method_chain wraps up this pattern into a single method call. The above example, once refactored to use Module#alias_method_chain, would simply be:

alias_method_chain :render, :layout

This will be used to refactor quite a bit of Rails internals which may not be of immediate relevance to what you do, but it serves as a nice example of the mechanisms Ruby provides for software organization. Small victories.