Rails-doc.org is an fairly ambitious project to create a community driven Rails documentation site. Basically they let users sign up and contribute notes to the existing Rails documentation. This certainly has the potential to be very useful, especially for new Rails hackers because sometimes the people who have been around the framework for a while just take things for granted.

Take the documentation for strftime in the Date class for example. There is no documentation listed for that method. Despite the fact that you clearly need documentation of the strftime options in order to use that method. Instead you have to know to look under strftime in the Time class for the documentation. While this is an example specific to Ruby documentation, these are the kinds of obvious problems that a community documentation website can help solve.

Right now Rails-doc.org has only been live for a month the so amount of community documentation feels very low. In the mean time I’ll be using the site for the official documentation that is already in place. Plus its the best looking rendering of the Rails documentation site out there. The Nodeta guys did a good job with the design. They also have a nice looking blog.

It will be interested to see how many of the notes contributed to Rails-doc get ported to the official Rails documentation. This certainly feels like the easiest and most straightforward way to contribute to Rails documentation and I can see it becoming a testing ground for future contributions to the official docs.

I am actually going to show two ways to do this. The first is the way that Evan Weaver, the creator of Ultrasphinx, recommends and the second way is the create a simple plugin that extends the Ultrasphinx plugin. The second way is my favorite because it provides the cleanest integration in my opinion but I’m going to demonstrate both methods so you can choose for yourself.

Method 1

To begin we need to make a class method that performs the eager loading in the model. Something like this:

## app/models/course.rb
class Course
  ...
 
  def self.find_with_includes(id)
    find(id, :include => [:professors])
  end
end

Notice how I’m using the familiar ActiveRecord include option to perform the eager loading like we would normally. The next and last step is to add the method to client_options[:finder_methods] in your environment.rb.

## config/environment.rb  
Ultrasphinx::Search.client_options[:finder_methods].unshift(:find_with_includes)

That’s it. Now to the second method.

Method 2

As I mentioned before, in this method we are going to create a simple plugin that will add functionality to Ultrasphinx. The code for this plugin was written by Henrik N.

Create a new folder in vendor/plugins/ called ultrasphinx_customizations. The name can be anything you like as long as it starts with “ultrasphinx”. This is so our customizations are loaded after the actual Ultrasphinx plugin. Inside the folder create init.rb and place this line in it.

## vendor/plugins/ultrasphinx_customizations/init.rb
Dir[File.dirname(__FILE__) + '/lib/*.rb'].each {|file| require file }

Now for the part of the plugin that actually does the work. Create a lib folder in ultrasphinx_customizations and create a new file in it called eager_loading.rb with the following contents.

## vendor/plugins/ultrasphinx_customizations/lib/eager_loading.rb
 
# Allows specifying eager loading options as e.g.
# Ultrasphinx::Search.client_options[:include]['MyKlass'] => [:user]
# or directly in is_indexed like
# is_indexed ..., :eagerly_load => [:user]
 
Ultrasphinx::Search.client_options.merge!(HashWithIndifferentAccess.new({
  :finder_methods => ['find_all_by_id_with_eager_loading'],
  :include => {}
}))
 
 
class ActiveRecord::Base
 
  def self.find_all_by_id_with_eager_loading(*ids)
    includes = Ultrasphinx::Search.client_options['include'][self.name]
    args = ids + [:include => includes]
    find_all_by_id(*args)
  end
 
  def self.is_indexed_with_include_option(options)
    Ultrasphinx::Search.client_options['include'][self.name] = options.delete(:eagerly_load)
    is_indexed_without_include_option(options)
  end
  class << self; alias_method_chain :is_indexed, :include_option; end
 
end

Sweet we’re done with the plugin. Now for the fun part. Remember in the model where we have our Ultrasphinx is_indexed :fields => [...] declaration? Thanks to our new customization we can add an :eagerly_loaded key and it will behave like an ActiveRecord find(:include => …). Here is what mine looks like.

## app/models/course.rb
 
is_indexed  :fields => ['course_number', 'title', 'term'],
            :eagerly_load => [:professors]

That’s all you have to do! I really enjoy the second method because it provides a seamless integration with the is_indexed call which seems to help me sleep at night.

Huge thanks to Henrik N for writing the ultrasphinx_customization code and Evan Weaver for writing Ultrasphinx.

Updated 04/17/2008: Fixed incorrect statement about plugin names.

Ruby on Rails is often (incorrectly) billed as the framework that makes web development easy. Unfortunately a lot of people take this to mean “Anyone can make a web site with Rails” or “You can get started with Rails in 15 minutes“. Unfortunately neither is the case but regardless hundreds of thousands of people¹ are flocking to Rails to start making a web app for everything under the sun.

These people learn in hurry that Rails is actually quite a large beast² and jump right into working with Rails without taking time to learn the programming language that Rails uses… Ruby. Almost like Ruby doesn’t exist. If I had to guess I would say people coding Rails apps without actually knowing Ruby has inevitably lead to the Rails community’s pseudo status as a ghetto.

I must confess, I was one of the Rails coders who didn’t know Ruby when I first started with Rails. Very few people who come to Rails known Ruby due to Ruby’s limited popularity before Rails came along. For about the past 7 months I have been trudging along, learning more about Ruby every day³ and the code I write for Rails projects now is much better. Ruby programming constructs like blocks, lamba, proc, etc are fairly advanced topics that I am probably only beginning to comprehend.

Most people might think it is obvious that you would need to know a framework’s programming language before you started using the framework. Certainly you would not attempt J2EE development without first knowing Java. For some reason this has not always been the case with Rails.