Purple Workshops News and Technical Articles

Join Us at Windy City Rails 2009

Jeff Cohen — 24 Jun 2009

Note: For best formatting, you may want to view this article on the web.

PurpleWorkshops will conduct the morning tutorial session at the upcoming Windy City Rails Conference. It's a 3-hour tutorial called REST 101: Best Practices for Rails Developers.

The conference will be held on September 12, 2009 in downtown Chicago. If you register now, you can get the early bird rate of $99 for conference admission or just $199 for the conference with one tutorial session.

Windy City Rails donates all profits to local charities, like the Greater Chicago Food Depository.

If you're getting started with Rails and ready to take the next step, sign up for our tutorial session too. We'll have fun and learn a lot!

Questions? Feel free to email me directly at info@purpleworkshops.com

See you there!

If you're not able to attend the conference, you're also in luck. The tutorial is a shortened version of Rails for Everyone. You can sign up to get an email when registration opens that will also include a discount code.

Rails 101: Grouping Controllers in Subdirectories

Jeff Cohen — 12 Feb 2009

Note: For best formatting, you may want to view this article on the web.

Every Rails application consists of many different Ruby classes. Rails dictates where these classes go. For example, some classes are called models, and Rails will expect to find them in your app/models directory; controllers go in app/controllers; and so on.

For large applications, the list of Ruby files in a directory may grow large, and you might wish to create subdirectories to group related classes together. Rails lets you create subdirectories for your classes, but you need to do more than simply move them into a new subdirectory before Rails can find them and use them properly. In this article, we'll show you how to put a controller into a subdirectory and enable Rails to find it automatically.

Grouping Controllers into an Admin Folder

Even if your application isn't very large, you may still want to group controllers into a subdirectory. It's not uncommon to have two controllers for a particular resource: one that serves public pages, and the other to provide an administrative interface.

Let's pretend our application sells tickets for a large number of venues. The public VenuesController class allows users to select a venue, get directions, view a seating chart, and so on. But our administrative staff has different needs: they want to add new venues, delete others, and change the information pertaining to a given venue.

Let's put our administrative controller into a folder named app/controllers/admin. We can generate our new controller with the generate command:

script/generate controller admin/venues

Now, open up the app/controllers/admin/venues_controller.rb file that was generated:

class Admin::VenuesController < ApplicationController
end

That looks... familiar. But what's with the strange class name? And if we try to browse to /admin/venues, we'll get an error message. Why can't Rails find our controller class?

Grouped Controllers Need Ruby Modules

Here's the first catch: when you move a class into a subdirectory, Rails won't see it unless it is contained inside a lexical scope that corresponds to its physical directory. Our VenuesController is in a subdirectory named Admin, so we must wrap it inside a corresponding Ruby module named Admin as well.

Why does Rails make us do this? To prevent name collisions. We want our public VenuesController to be up in the main app/controllers directory, so their needs to be a way to distinguish the two classes by something other than physical location on disk.

Do do you have to configure what module name will be used in each directory? No. Rails conventions to the rescue. The module name is assumed to be the same as the directory name.

Since our file lives in the admin/ subdirectory, our module name is Admin. There are a couple of ways to specify that your class lives in a directory, but one of the most common ways is to simply put the module name in front of the class name, separated by two colons. That's how we got the class name Admin::VenuesController.

Grouped Controllers Need Namespaced Routes

And now for the second catch. If we were putting our model into a subdirectory, we'd be done as soon as we used the right module and class name combination. But since this is a controller, Rails also needs a way to route admin urls to our admin controllers. To do that, we use the namespace method in our routes file:

ActionController::Routing::Routes.draw do |map|

  # Somewhere inside this block, 
  # just create a namespace for the
  # admin controllers, like this:
  
  map.namespace :admin do |admin|
    admin.resources :venues
  end
  
end

The namespace will expect a path prefix of admin and also creates named routes with the same prefix. For example, to create a link to the Admin::VenuesController's index action, you would do something like this:

link_to "View all venues", admin_venues_path

Summary

To group controllers into a subdirectory, you must do two things:

1. Wrap your controller class inside a Ruby module. The name of the module should be the same as your subdirectory name.

2. Create a routing namespace with the same name as your subdirectory name, and map your controller from inside the namespace.

And presto! You can now browse to /admin/venues and use your new controller.

Agile 101: The Simplest Thing That Could Possibly Work

Jeff Cohen — 3 Dec 2008

Note: For best formatting, you may want to view this article on the web.

The saying, “Do the simplest thing that could possibly work,” has reached legendary status in most agile circles. When I first heard of it, I thought it was a pretty silly statement. After all, what developer in their right mind chooses to do things the hard way?

A related, albeit slightly less famous agile phrase is, “Solve today's problems today.” In other words, don't design a solution to a problem that doesn't really exist, based solely on a guess that it might be a problem tomorrow. Just solve today's problems.

It wasn't until much later that I began to understand what this simple phrase was really talking about.

If you're new to “Do the simplest thing that could possibly work,” and even if you think your understand what it means, read on. I'm going to show you how we implemented a feature on the PurpleWorkshops site that followed this advice to such an extreme, that you might think I'm crazy.

The Problem

Potential customers can get in touch with us by filling out a very simple form (you can see it here). Although we don't get a lot of traffic, we were getting a significant amount of spam submitted through that form before we implemented a simple Captcha system, that you now see at the bottom of the form. Each spam submission would add rows to our database that would require cleaning out, and each would alert me - falsely - that a potential customer was contacting us.

A Not-So-Simple Solution

Now, I really wanted to avoid a complicated, TicketMaster-style-can-barely-see-those-stupid-letters experience that I hate so much. But I finally couldn't avoid it any longer, and started looking into captcha strategies.

The general idea of a captcha is you present something that automated scripts probably won't understand - like a word or number sequence contained in an .png or .jpg file - and require the user to enter that word or sequence into the form. This raises the level of confidence that whoever - or whatever - is submitting the form is a real, human person, and therefore is probably a legitimate potential customer.

There are many solutions available. Most of them generate images on the fly, requiring you to install something like RMagick on your server. All of the solutions I looked at were fine, but… complicated. Yes, installing a plugin and following a few directions is complicated for me. Maybe I'm just getting old.

First Attempt At Being Simple

Or maybe I'm just too agile. It occurred to me, out of the blue, that I don't really need all that complexity that most captcha solutions give me. I have a relatively low-trafic site. The spambots are probably not going to think it worthwhile to really target my site. So I don't need something super deluxe. Just something to stop the simple bots.

So rather than install RMagick and generate images on the fly with some randomly-generated word pulled from a dictionary each time the page loads, maybe I could just generate a set of images and randomly present one of them using a simple image tag.

Doesn't that sounds simpler?

Wait, it gets even better. Instead of using RMagick to generate these images, I'm just going to use (drum roll…) Skitch. Yes, I'm going to generate them by hand, say 20 of them.

I just have to give them filenames like captcha_1.png, captcha_2.png, and so on. Then, to choose an image at random, I need to do something like this in my new action:

# Show form to user
def new
  random_key = rand(20) + 1
  @captcha_filename = "captcha_#{random_key}.png" 
end

Later in the create action, I can verify that the word they enter is the same as what's shown in the image.

Of course, somewhere I'm going to have to store the correct answer. This could be kept in the session (say, as an MD5 of the answer) or on the server.

Hmmm, this is starting to feel… I don't know, not complicated exactly, but more hassle than I wanted.

Time to simplify again.

The Simplest Thing That Could Possibly... you know...

This may sound absurd at first, but I thought, what would happen if I really just did the simplest thing that could possibly work. At least as a first pass, before I go implementing the whole solution.

What would that be? I think the simplest thing would be to have just one image that is shown every time, and one correct, hard-coded answer.

And that's exactly the solution you see now: the user must correctly type the word they see in the image before our Rails app will accept the inquiry.

But now you know the secret (whoa, I hope you don't program spambots for a living).

The Benefits

I created the image in about 3 minutes, added an image tag and a new text field to the inquiry form in about 3 minutes, added model validation (using the correct answer as a hardcoded string) in about 1 minute. 7 minutes, and two weeks later, no spam. Zero.

I suppose one day, maybe even tomorrow, some spambot will figure out the answer, and this solution won't work anymore. I'll have to make things a little more complex, and maybe use the 20-image solution. When that happens, that will become the simplest thing that could possibly work.

But remember, that's tomorrow's problem. We agile developers only solve today's problems today.

Crazy?

Does my solution sound crazy too you? Ok, maybe you wouldn't say it's crazy - but naive? Do you think a “real” solution to the problem would involve a more rigorous solution?

If so, I have one question for you.

Did I mention we haven't gotten any spam yet?

Rails Internals: named_scope Refactored

Jeff Cohen — 19 Nov 2008

Note: For best formatting, you may want to view this article on the web.

You've probably heard that reading someone else's code is one way to learn more Ruby, and it's true. If you're a Rails developer, you already have a large quantity of reading material at your disposal: the Rails source itself. Reading the Rails source code is a great way to learn about Ruby idioms and techniques that you may not be using in your own applications.

Not familiar with named_scope? Check the API documentation or read about it in the official Rails guide.

Some Rails code is bread-and-butter Ruby, that most developers can readily understand. Other parts use more advanced idioms or a more densely-packed style, which might dissuade the casual developer from being able to understand the code. That's a shame, because valuable concepts and techniques can go unnoticed and unlearned.

We're going to take a look at the implementation of named_scope, a very popular feature of ActiveRecord that first appeared in Rails 2.1.

1. What is Refactoring?

Refactoring is an essential coding discipline for every agile developer. Refactoring is the process of taking existing code, and morphing into new code that exhibits the exact same behavior on the outside, but is cleaner, simpler, and better designed on the inside.

Martin Fowler, author of the well-known Refactoring book, identifies many kinds of refactoring patterns. One of the most common techniques - extract method - can help simplify a method that's trying to do too much, or whenever the _intent_ of the code isn't clear enough.

To demonstrate, we're going to take a look at the implementation of one of the most popular features in Rails 2.1: named_scope.

2. The 10-Second Rule

No, I'm not talking about the bagel you dropped on the floor. Take a look at the following code. It's taken directly from the Rails 2.1 source code. Can you understand it in 10 seconds or less?

# Implementation of named_scope in Rails 2.1
def named_scope(name, options = {}, &block)
  name = name.to_sym
  
  scopes[name] = lambda do |parent_scope, *args|
    Scope.new(parent_scope, case options
      when Hash
        options
      when Proc
        options.call(*args)
    end, &block)
  end
  
  (class << self; self end).instance_eval do
    define_method name do |*args|
      scopes[name].call(self, *args)
    end
  end
end

Unless you're comfortable with some advanced Ruby concepts, this code may be pretty hard to understand.

There are several things going on here that make this code harder to read than it ought to be. Let's walk through them one at a time. We'll refactor as we go, leaving us with code that will behave the same, but will be make the named_scope method more readable and its intent more transparent.

The method starts innocently enough, by coercing the name parameter into a symbol.

Then we go over the cliff pretty fast. Line 5 looks like it's going to assign a key-value pair into a hash named scopes. The key for the pair is name, but the value is... well, something complicated:

scopes[name] = lambda do |parent_scope, *args|
  Scope.new(parent_scope, case options
    when Hash
      options
    when Proc
      options.call(*args)
  end, &block)
end

It's a lambda that takes multiple parameters, and which will return a new Scope object. We don't know yet what the Scope class does, but we don't need to worry about that for now. Furthermore, creating this Scope instance seems to require three parameters, although it may not be immediately obvious.

The first parameter is simply the parent_scope value that was received by the lambda. The second, however, requires a case statement to determine, and the author of this code has chosen to put the case statement inline with the rest of the code. The third parameter is the &block parameter that the named_scope method originally received.

After some digging into the Scope class, and researching where the scopes hash is used, I determined that the scopes hash maps the name of your named scope to a lambda expression that will be executed later.

3. Refactoring, Part 1

Let's refactor this code segment out to a well-named method that more clearly describes the author's original intent.

def save_scope_definition_for_later(options, &block)
  scopes[name] = lambda do |parent_scope, *args|
    Scope.new(parent_scope, case options
      when Hash
        options
      when Proc
        options.call(*args)
    end, &block)
  end
end

Now we can simplify the original code a little bit:

# New implementation after one round of refactoring
def named_scope(name, options = {}, &block)
  name = name.to_sym
  
  save_scope_definition_for_later(options, &block)
  
  (class << self; self end).instance_eval do
    define_method name do |*args|
      scopes[name].call(self, *args)
    end
  end
end

Wow, that helped a lot. Less code, more transparency. It feels a lot better already.

4. Refactoring, Part 2

We now have less code in the named_scope method. But the code that remains still feels a bit funny. Ruby methods should contain code at the same level of abstraction. The nice-looking call to save away the scope definition is followed several lines of very detailed-looking code.

Let's take a closer look at the remaining code:

(class << self; self end).instance_eval do
  define_method name do |*args|
    scopes[name].call(self, *args)
  end
end

There are actually two advanced Ruby idioms in use here. Suffice to say, this code will generate a new method in your model class. The name of this new method is made to be the same as your named scope; and the implementation is actually quite simple: it first finds the appropriate scope definition that had previously been saved away, and executes it.

Let's again factor this out to a well-named method:

def create_method_with_same_name_as_scope(name)
  (class << self; self end).instance_eval do
    define_method name do |*args|
      scopes[name].call(self, *args)
    end
  end
end

And now, the named_scope method has been reduced to this:

# Clearer code
def named_scope(name, options = {}, &block)
  name = name.to_sym 
  save_scope_definition_for_later(options, &block)
  create_method_with_same_name_as_scope(name)
end

We can even do away with that reassignment of the name variable as well, and perform the conversion on the fly:

# Refactored version
def named_scope(name, options = {}, &block)
  save_scope_definition_for_later(options, &block)
  create_method_with_same_name_as_scope(name.to_sym)
end

5. What Did We Learn?

Imagine if our final version of the named_scope was the _first_ version you saw. You'd probably have a much easier time understanding how it works because there are two methods, each descriptively named, that provide insight into their intent.

Refactoring is great way to learn code that you don't understand. Begin slowly, and work to understand what the code does. As you gain understanding, you may find that extracting out the more complicated segments into well-named methods will bring a level of clarity that you did not have when you started.

For a complete introduction to the practice of refactoring, we recommend Martin Fowler's seminal work, Refactoring: Improving the Design of Existing Code.

Ruby 101: Method Definitions

Jeff Cohen — 18 Nov 2008

Note: For best formatting, you may want to view this article on the web.

Objects manage state, and they also exhibit behavior. In this article, we'll be learning how to add behavior to classes that we write in Ruby.

By "behavior" we mean, what the class, or an instance of the class, can "do." While variables allow an object to store data, Ruby objects can define methods that execute code. This is an essential concept in object-oriented programming. Objects don't just encapsulate data, they also perform actions and can have responsibilities assigned to them.

1. The Basics

Sometimes the best way to learn is to dive right in. Take a look at this Ruby code.

1 2	class Telephone end

This Ruby code defines our Telephone class. A class is a blueprint for how to make objects of that class. We can create a new Telephone object by calling the new method on our class:

1	my_phone = Telephone.new

my_phone is now an instance of a Telephone. What can our instance variable do that a plain Object can't do? Well... nothing yet. Let's teach a Telephone how to dial a phone number:

class Telephone

  def dial(number)
    puts "Dialing #{number}..."
  end
  
end

my_phone = Telephone.new
my_phone.dial '1-800-555-1212'

Here on line 3, we've defined an instance method by using the def keyword. Save this code into a file named phone.rb, and run it:

c:\> ruby phone.rb
Dialing 1-800-555-1212...

We can define as many instance methods as we'd like. Let's teach our object to hang up the phone.

class Telephone

  def dial(number)
    puts "Dialing #{number}..."
  end

  def hang_up
    puts "Hung up."
  end
end

my_phone = Telephone.new
my_phone.dial '1-800-555-1212'
my_phone.hang_up

We'll get this:

c:\> ruby phone.rb
Dialing 1-800-555-1212...
Hung up.

There is one special instance method you should know about, called the initializer. We don't have to define this method, but if we do, Ruby will call it for us automatically every time a new instance is created. Here's an example:

class Telephone

  def initialize
    puts "New telephone created!"
  end
  
  def dial(number)
    puts "Dialing #{number}..."
  end

  def hang_up
    puts "Hung up."
  end
end

my_phone = Telephone.new
my_phone.dial '1-800-555-1212'
my_phone.hang_up

Let's run it again:

c:\> ruby phone.rb
New telephone created!
Dialing 1-800-555-1212...
Hung up.

Initializers can take arguments, just like our dial method did. We pass the actual argument values when we call new to create instances of our object. If we change our initializer to this:

def initialize(home_area_code)
  puts "New telephone created!"
  @area_code = home_area_code
  puts "Our home area code is #{@area_code}."
end

Now we are required to provide the phone's home area code when we construct a Telephone instance:

my_phone = Telephone.new('312')

And now we'll get output like this:

c:\> ruby phone.rb
New telephone created!
Our home area code is 312.
Dialing 1-800-555-1212...
Hung up.

Class Methods vs. Instance Methods

Java and C# static methods are the same as class methods in Ruby. (Switching from .NET to Rails? Buy the book).

So far we've learned how to create instance methods. They're called that because we have to first create an instance of our class before we can call them.

Sometimes we have functionality that seems appropriate to all telephones, regardless of _which_ telephone we might use. We can create class methods - methods that apply to the whole class, and not any specific instance.

Since all of our telephones have one thing in common - their manufacturer - we can create a class method to report the name of the manufacturer:

class Telephone

  def self.manufacturer
    return "Purple Telco"
  end
  
  # Rest of class definition goes here
  # ...
  
end

puts Telephone.manufacturer

Notice how we prefix the self keyword in front of the method name to indicate that it's a class method, instead of an instance method. Let's run it:

c:\> ruby phone.rb
Purple Telco

Notice how we didn't need to create any instances first. manufacturer is a class method: all we needed was the name of the class.

Congratulations! You now know the basics of instance and class methods in Ruby.