Objects on Rails

This is the complete text of Objects on Rails, a "developer's notebook" documenting some guidelines, techniques, and ideas for applying classic object-oriented thought to Ruby on Rails applications. This book is aimed at the working Rails developer who is looking to grow and evolve Rails projects while keeping them flexible, maintainable, and robust. The focus is on pragmatic solutions which tread a "middle way" between the expedience of the Rails "golden path", and rigid OO purity.

I'm Avdi Grimm. I've been doing large-scale object-oriented software development my entire programming career, first in aerospace and networking systems, and later on for web applications. I've been hacking in Ruby for over a decade, and I still love how fun and effortless it makes the job of building programs out of objects. I've spoken at a few conferences about Ruby code construction, I'm a co-host of the Ruby Rogues podcast, and I blog about software at Virtuous Code. If you like, you can follow me on Twitter.

I'm also a freelance consultant working with the Code Benders collective. If you have a software project and you want to move fast without sacrificing quality, you should get in touch with us.

Got questions, comments, errata—or just want to discuss object-oriented programming with other Rubyists? Come on over to the book's email discussion group.

This is not a Rails tutorial

Familiarity with Rails and Ruby is assumed.

This is not a Rails critique

This is not all about how "Rails is wrong". Rails is a terrifically powerful framework for quickly assembling web applications. I'm interested in how to better use the tools Rails provides, not so much in how to subvert or replace them.

This is not comprehensive

This text is effectively a snapshot of some of my Rails development preferences and ideas circa late 2011/early 2012. It doesn't capture every possible application of OO patterns or SOLID principles to Rails development.

This is not a rule book or a "best-practices" manual

The last thing I want anyone to do is follow the approach shown here as a book of rules for how to build a Rails application "right". I hope that you'll consider the patterns and idioms presented here, and select the ones that speak to you and make sense for your application. If nothing else, I hope to give you some food for thought.

This text takes the form of a walkthrough. We'll build an app step-by-step using Test-Driven Design (TDD), at most steps presenting test code followed by implementation code.

However, while we will use TDD at the unit test level to drive development, there is a major piece missing from our TDD stack. Ordinarily, when building a "real" app, I would drive each feature from the outside in using acceptance tests, typically written using Cucumber. However, in the interests of brevity, I omit the acceptance testing component in this document. For the curious, I've included the Cucumber acceptance tests in Appendix B.

With a few exceptions, all the code samples are from the working demo codebase I built as I wrote the text. If you have the "deluxe edition" you have access to a full copy of the source code, including revision history. I've taken the liberty of eliding some of the code samples in the text to show only the bits that are interesting or relevant to the discussion; this means, for instance, that some require statements have been omitted.

This text uses Ruby 1.9. Among other things, I make extensive use of the new "stabby lambda" syntax:

# Ruby 1.8
lambda{|x,y| x + y}
# Ruby 1.9
->(x,y){ x + y}

If you're not familiar with the changes from 1.8 to 1.9, I highly recommend Peter Cooper's comprehensive walkthrough on the subject.

Also note that I use the "Weirich convention" for choosing between {} and do...end delimiters around blocks. So blocks which are evaluated for their result value, I surround with braces ({}); whereas blocks which are evaluated for their side-effects get do...end.

The challenge in writing about code patterns is to come up with examples that are simple and clear enough that the supporting code doesn't get in the way of understanding the specific technique being demonstrated–while still hopefully avoiding examples that feel completely contrived. Unfortunately, if you succeed in that, you are often confronted with a new problem: the example problems you carefully distilled down to their essence now seem so simple, so trivial that whatever refactoring or abstraction you're trying to illustrate seems superfluous and a waste of effort.

The application I work through in these pages is a deliberately simple one, and many of the techniques I demonstrate may seem like massive overkill for the task at hand. Please understand, as you read through the examples, that these are patterns and idioms intended to make the development and evolution of large-scale applications more tractable. While they may seem less than compelling in the context of a "toy" app, hopefully you can visualize how they might be helpful for larger-scale development.

Why bother with these techniques? What's wrong with the way we've always written Rails applications?

The biggest reason—scratch that, the only reason—is to make our apps easier to change. The only constant in life is change, and that goes double for software projects. Markets change, requirements change, external dependencies change, and platforms change. As I've written about at length elsewhere, Rails is reaching a point at the time of writing where a lot of projects are starting to mature, and a lot of developers are realizing their projects aren't nearly as easy to modify as they used to be.

It's risky for me to give some specific example, e.g. "by following these guidelines, you'll be able to easily change to MongoDB in the future!". Inevitably someone will say "hah, my app will never need to switch to MongoDB, therefore I don't need these techniques!"

Attempts to predict which parts of a codebase will need to change, and to structure it accordingly, have ended badly more often than not. Part of the nature of change is that you often don't know beforehand what is going to need change. In this text I'm not going to attempt to say "using such and so technique will make such and so component easier to change". In fact, I would encourage you not to spend too much time thinking about what is most likely to change. Much like premature optimization, premature change management usually misses the mark.

Amongst all this uncertainty, there are some basic principles that have proven, over decades of Object-Oriented software development, to make software generally more flexible and amenable to change. Principles such as:

• Small objects with a single, well-defined responsibility.
• Small methods that do only one thing.
• Limiting the number of types an object collaborates with.
• Strictly limiting the use of global state and singletons (that includes limiting the use of class-level methods).
• Small object interfaces with simple method signatures.
• Preferring composition over inheritance.

These rules of thumb, practiced habitually, tend to lead to more flexible codebases which can adapt to any type of change adroitly; whether the change is a data model which better resembles the problem domain; a new data storage backend; or a re-structuring of the app into a half-dozen mini-apps.

So the answer to why, in the end, is "because things change". Some good habits and sound architectural guidance early on in a project can save a lot of headaches down the road.

With that intent in mind, let's jump in!

OK, now we have an entries attribute on Blog, but there's nothing in it. Let's add some temporary example blog posts in the BlogController.

def index
  @blog = Blog.new
  post1 = @blog.new_post
  post1.title = "Paint just applied"
  post1.body = "Paint just applied. It's a lovely orangey-purple!"
  post1.publish
  post2 = @blog.new_post(title: "Still wet")
  post2.body = "Paint is still quite wet. No bubbling yet!"
  post2.publish
end

You may have noticed that we're calling a #new_post method which doesn't exist yet, followed by some other methods on the return value which also don't exist. Now that we know what code we need, let's make it exist.

First, let's specify that #new_post method. Clearly it needs to return some kind of blog post object which is associated with the Blog object. However, we want to keep our tests isolated, and we only want to test one model at a time. So we'll make the process by which new posts are created easy to swap out:

class Blog
  # ...
  attr_writer :post_source
  # ...
  private
  def post_source
    @post_source ||= Post.public_method(:new)
  end
end

#public_method, if you're unfamiliar with it, instantiates a call-able Method object. When the object's #call method is invoked it will be as if we called the named method on the original object. The "public" in the name refers to the fact that unlike #method, #public_method respects public/private boundaries and will not generate a Method object for a private method.

In this case, Post.public_method grabs a reference to a Method object representing the (not yet written) Post.new method. During normal operation, Blog will use this method reference (the equivalent of calling Post.new) to generate post objects. But we can substitute any call-able object when testing the class.

Now we'll make some assertions about how Blog#new_post should behave:

# spec/models/blog_spec.rb
require 'ostruct'
describe Blog do
  # ...
  describe "#new_post" do
    before do
      @new_post = OpenStruct.new
      @it.post_source = ->{ @new_post }
    end
    it "returns a new post" do
      @it.new_post.must_equal @new_post
    end
    it "sets the post's blog reference to itself" do
      @it.new_post.blog.must_equal(@it)
    end
  end
end

Here, we substitute a lambda which simply returns an OpenStruct for the #post_source.

Making these pass is straightforward:

class Blog
  # ...
  def new_post
    post_source.call.tap do |p|
      p.blog = self
    end
  end
end

Hold on a sec. Aren't we getting our terms confused here? First we said a Blog has "entries". But then we started talking about "posts". Shouldn't we pick one or the other?

In fact, this choice to use multiple terms is deliberate. The dark side of having sensible framework conventions is that after a while, those conventions turn into assumptions. In this case, if we called the entries collection posts instead, there's a good chance we'd start mentally conflating it with the Post class. Anything in blog.posts is a Post object, end of story.

This is one of those subtle assumptions that can lead to big problems. For instance, if we assume blog.new_post is equivalent to Post.new, we might start to just skip the Blog part and write Post.new(...) or Post.create(...) whenever we want a new blog entry.

Now imagine some time passes, and we add the ability for a Blog to have many different types of posts—photos, embedded videos, etc, each represented by different classes such as PhotoPost and VideoPost. A call to Blog.new_post(...) looks at the arguments arguments and chooses the right type of object to instantiate. Unfortunately, we hard-coded references to Post everywhere, and now we have to go back and change them all.

These kinds of assumptions don't just lead to extra work; they can introduce security holes. Let's say we made the "blog entries are Posts" assumption, and as a result we coded various controller actions to look like this:

def update
  @post = Post.find(params[:id])
  # ...
end

Then one day we decide to add the ability to host multiple blogs. Instead of a singleton Blog instance, there are multiple blogs, each owned by a different user. The controllers are all updated to make sure that actions modifying a Blog can only be made by the user who owns that blog.

The upgrade goes easily, and everything is working great. Then one day a clever user realizes that if he can guess the ID of someone else'spost, he can modify its content! Why is this possible? Because all those calls to Post.find() bypassed any scope constraints imposed by accessing posts from a Blog instance instead of fetching them directly.

These are not hypothetical issues; I've seen them in production codebases. Using different terms for "the blog's entries" and "a Post object" doesn't automatically fix the problem. But if they mentally trip us up a bit, that might just be the nudge we need to remember that the entries managed by a blog are not necessarily equivalent to the set of all Post records. The topic of this text is looking at Rails projects with a fresh perspective, and playing with naming is one way to do that.

It's pretty obvious that our next step needs to be creating a Post class. Let's specify its behavior.

# spec/models/post_spec.rb

require 'minitest/autorun'
require_relative '../../app/models/post'

describe Post do
  before do
    @it = Post.new
  end

  it "starts with blank attributes" do
    @it.title.must_be_nil
    @it.body.must_be_nil
  end

  it "supports reading and writing a title" do
    @it.title = "foo"
    @it.title.must_equal "foo"
  end

  it "supports reading and writing a post body" do
    @it.body = "foo"
    @it.body.must_equal "foo"
  end

  it "supports reading and writing a blog reference" do
    blog = Object.new
    @it.blog = blog
    @it.blog.must_equal blog
  end

  describe "#publish" do
    before do
      @blog = MiniTest::Mock.new
      @it.blog = @blog
    end

    after do
      @blog.verify
    end

    it "adds the post to the blog" do
      @blog.expect :add_entry, nil, [@it]
      @it.publish
    end
  end
end

Next we satisfy the specification:

# app/models/post.rb
class Post
  attr_accessor :blog, :title, :body
  def publish
    blog.add_entry(self)
  end
end

If you've written a few Rails apps you may be wondering why we're calling the method which makes a new blog entry #publish instead of #save.

One of the central elements of object-oriented design is capturing the language of the domain in our models. Think for a minute about the language of blogging. No one says "I saved a blog post the other day". They say "I published a blog post" or maybe "I posted a blog entry". By calling the method #publish, we are continuing to build a system which echoes our mental model of the domain.

Consider how we might extend this program in the future. We might add scheduled posts, which appear some period of days later than they are first saved. We might also add a draft state for posts, where they are saved but they are only visible to the blog owner.

Our choice of the verb #publish fits right into this extended workflow:

post.save_draft
# followed by ...
post.schedule
# or...
post.publish

This is not a coincidence. Choosing appropriate domain language for program elements often means we don't need to rename as many things as we add more features down the road.

Driving out Post has revealed that we need one more method on Blog, one which will actually add the post to the blog. We'll quickly spec it out and add it.

describe Blog do
  describe "#add_entry" do
    it "adds the entry to the blog" do
      entry = Object.new
      @it.add_entry(entry)
      @it.entries.must_include(entry)
    end
  end
end

class Blog
  # ...
  def add_entry(entry)
    entries << entry
  end
  # ...
end

Looking back at our demo code in the BlogController, we remember that in making a second post, we changed things up a little and passed in the title as an argument:

post2 = @blog.new_post(title: "Still wet")

Let's modify Blog#new_post to support this syntax. First, the spec:

# ...
it "accepts an attribute hash on behalf of the post maker" do
  post_source = MiniTest::Mock.new
  post_source.expect(:call, @new_post, [{x: 42, y: 'z'}])
  @it.post_source = post_source
  @it.new_post(x: 42, y: 'z')
  post_source.verify
end
# ...

And then the implementation:

# ...
def new_post(*args)
  post_source.call(*args).tap do |p|
    p.blog = self
  end
end
# ...

Now we're passing the arguments along, but we still need to implement keyword arguments on the Post initializer.

describe Post do
  # ...
  it "supports setting attributes in the initializer" do
    it = Post.new(title: "mytitle", body: "mybody")
    it.title.must_equal "mytitle"
    it.body.must_equal "mybody"
  end
  # ...
end

class Post
  # ...
  def initialize(attrs={})
    attrs.each do |k,v| send("#{k}=",v) end 
  end
  # ...
end

Now we just need to update the views to show our posts.

<!-- app/views/blog/index.html.erb -->
<h1><%= @blog.title %></h1>
<h2><%= @blog.subtitle %></h2>
<%= render partial: "entry", collection: @blog.entries %>

<!-- app/views/blog/_entry.html.erb -->
<article>
  <header>
    <h3><%= entry.title %></h3>
  </header>
  <p><%= entry.body %></p>
</article>

Reloading the page, we can see our demo entries.

Showing entries

We're almost there, but in order to construct paths and render forms, Rails has certain expectations about the protocols that a model object will respond to—protocols that our basic Post class doesn't know about. The easiest way to make it compliant is to add a couple of modules from ActiveModel. We also need to implement one method ourselves: #persisted?. For now, it's sufficient to just return false.

class Post
  extend ActiveModel::Naming
  include ActiveModel::Conversion

  # ...

  def persisted?
    false
  end

  # ...
end

With that change, we can click on our "New post…" link and see a new post form.

New post form

So far so good. Now let's make submitting the form work. We need to add a PostsController#create action.

class PostsController
  # ...
  def create
    @post = @blog.new_post(params[:post])
    @post.publish
    redirect_to root_path, notice: "Post added!"
  end
  # ...
end

We can get rid of the demo posts in BlogController now.

class BlogController < ApplicationController
  def index
  end
end

There's just one little problem remaining: a new blog object—and hence a new, blank list of posts!—is created with every request. We need to make a single blog object last across requests.

Our app only supports a single blog at the moment, so we'll just store an instance to an app-wide Blog object using an initializer.

# config/initializers/blog.rb
THE_BLOG = Blog.new

Now we change the before filter which sets the @blog variable to use that constant:

class ApplicationController < ActionController::Base
  # ...
  def init_blog
    @blog = THE_BLOG
  end
end

And now we can submit new posts!

New post added

Let's take one last look at our controller action for submitting new posts.

def create
  @post = @blog.new_post(params[:post])
  @post.publish
  redirect_to root_path, notice: "Post added!"
end

Notably absent from this action is any direct reference to the Post class. We talked about this a little already in Posts vs. Entries. But I want to look at this from one more angle before moving on.

Object-oriented programs tend, more often than not, to evolve into a roughly tree-shaped structure. This is not surprising, since it mimics how we tend to think of the world around us as well as the world inside our programs. A website has a blog, a blog has categories, categories contain entries, an entry has tags and comments, and so on.

It's easy to go nuts with this, of course. When I first learned about OOP there was a huge emphasis on using it to break the world down into hierarchical ontologies which made for pretty UML diagrams. The problem with this view of OOP is that most complex systems don't have a single natural hierarchy to them. To use the blog example, we could also say a blog has authors, authors have entries, and the entries might have categories associated with them. This is no more "correct" than the version where categories are the concept which "contain" entries.

But the point is that we naturally break our systems into hierarchies, which practically speaking means trees of objects. In a tree of objects, each object mediates access to its "leaf" or "branch" objects. So you might access a blog object from a site object, a category from the blog object, and an article from the category object.

(I should probably clarify something at this point: I'm talking here about "trees" in the sense of "has-many" and "belongs-to", not in the sense of "is-a" inheritance trees.)

This pattern has some attractive properties. Having "parent" (I use the term loosely) objects mediate access to "child" objects gives us a natural "seam" in our design. At the seam, we can do a number of things:

1. Control access based on authorization information—as we saw in "*Posts vs. Entries.
2. Pre-load child objects with a reference back to their parent. The #new_post method above does this, enabling the post object to publish itself.
3. Save a reference to the child object in the parent. ActiveRecord's autosave facility does this. When we are careful to access child objects from the parent, ActiveRecord is able to persist all new, modified, or deleted child objects automatically when the parent object is saved.
4. Decide the actual class of the object to be instantiated, based on the parameters or the state of the parent.

And the great thing about having the seam is that we don't have to think about any of those concerns at the beginning. We can add them in at the seam point transparently, as the need arises.

Every time we put in an explicit reference to a class, rather than creating or accessing the object via its "parent" in the tree, we are implicitly rejecting all of these advantages. Sometimes this may be what we want. More often, it's a mistake.

Consider these common, seemingly innocuous lines:

@post = Post.new(params[:post])
@post = Post.create(params[:post])
@post = Post.find(params[:id])

Every one of these creates an object which is a "lone wolf". It's an object with no family, no ties to its community. If this object was arrested and had a bail hearing, it would be considered a flight risk. It is an object which believes it will never be part of something bigger than itself.

It's also an object which makes our tests more painful. How many times have you seen test setup that looks like this:

# RSpec
post = stub(:post)
Post.stub(:new).and_return(:post)

Or:

# Mocha
Post.any_instance_stubs(:foo)

These lines just add extra work and noise to tests. Having to stub #new, or override a method on every instance of an object, is a hamfisted, shotgun-blast approach to testing. And it is usually made necessary as a result of of "lone wolf" object creation.

Seams are useful things to have in growing programs. Rejecting them has serious implications for extensibility, as well as for security and correctness. That's why I regard any bare references to a class as a red flag, especially in Rails controller actions. I feel a lot more comfortable when I can clearly see the tree structure—trunk to limb, limb to branches, branches to twigs, twigs to leaves.

What we really need is a way to conditionally create empty or "stub" modules only if a) they are not already defined; and b) they are not auto-loadable. Here's a method which does just that.

# spec/spec_helper_lite.rb
def stub_module(full_name)
  full_name.to_s.split(/::/).inject(Object) do |context, name|
    begin
      context.const_get(name)
    rescue NameError
      context.const_set(name, Module.new)
    end
  end
end

This method uses #const_get to attempt to reference the given module. If the module is defined, or if calling #const_get causes it to be auto-loaded, the method does nothing more. But if #const_get fails to turn up the module, it defines an anonymous empty module to act as a placeholder.

Here it is being used to stub out modules in our Post spec:

# ...
require_relative '../spec_helper_lite'
stub_module 'ActiveModel::Conversion'
stub_module 'ActiveModel::Naming'
require_relative '../../app/models/post'
# ...

The tests are once again passing:

$ ruby spec/models/post_spec.rb                            
Loaded suite spec/models/post_spec
Started
......
Finished in 0.000530 seconds.
6 tests, 7 assertions, 0 failures, 0 errors, 0 skips

Wait a second… does this mean the app will always have to pass a clock object in to Post#publish now? Won't this break our other tests where we pass nothing to #publish?

Sensible defaults to the rescue! Let's update the Post#publish method to make this test pass:

# ...
def publish(clock=DateTime)
  self.pubdate = clock.now
  blog.add_entry(self)
end
# ...

We add a clock parameter, and make it default to DateTime. That way in the absence of any parameter, the method will just take its timestamp from the system clock via DateTime.

Why make it possible to pass the clock in? We might turn the question around: our tests up until now have been very careful to isolate our System Under Test (SUT) from any external dependencies, why make an exception for the system clock? By making it possible to pass a clock object in, we make it very easy to test the behavior of #publish deterministically, without resorting to heavy-handed clock-overriding libraries such as Timecop. To quote Growing Object Oriented Software, Guided by Tests:

we've seen so many systems that are impossible to test because the developers did not isolate the concept of time.

But there are other advantages to passing the clock in, which we'll discuss in the next section.

You might have wondered why we inject a callable @post_source instead of simply having a @post_class variable which defaults to Post.

For one thing, it makes our test setup easier. If we injected a "post class" mock, we'd have to do one of two things:

1. Stub .new on the real Post class, which would override the method globally and potentially interfere with any test code which also calls Post.new.
2. Create a @post_class stub and a @post stub, and stub the former to return the latter.

By contrast, all we need to do to stub the callable version is this:

blog.post_source = ->{ new_post }

As usual with mocks and stubs however, the ease of passing in a callable over injecting a .new method is pointing out a deeper design decision. When we say that Blog calls Post.new, we are implying that Blog has Post as a collaborator, and may potentially call any method on Post. The destinies of these two classes are now entwined.

By saying, instead, that Blog#new_post depends only on "some callable which will return a post when called", we are explicitly holding off from binding Blog to the Post class interface. We are choosing to make the minimum necessary connection between the two classes. If, down the road, we add a call to another Post class method, say, Post.find, our isolated tests will flag it and remind us to make a conscious choice about adding the new dependency.

Oh by the way, that post_source? It's a factory, as in "the Factory pattern". I didn't want to scare you off with big pattern talk, so I snuck it in under an assumed name ;-)

To satisfy our need for an object which mates a model and a view, we'll use what I've taken to calling an Exhibit object. If the Model is concerned with storing and manipulating business data, and the View is concerned with displaying it, you can think of the Exhibit as standing between them deciding which data to show, and in what order. It may also provide some extra presentation-specific information (such as the specific URLs for related resources) which the business model has no knowledge of by itself.

The Exhibit object is so named because it is like a museum display case for an artifact or a work of art. It does not obscure any of the features of the object being presented. Rather, it tries showcase the object in the best light to a human audience, while also presenting meta-information about the object and cross-references to other objects in the museum's collection.

Technically, exhibit objects are a type of Decorator specialized for presenting models to an end user. In fact, I briefly considered calling them "Presenter Decorators", but that term is a bit unwieldy, as well as being a little too easy to confuse with other "Presenter" terms (on which more later).

We write a spec for the exhibit we need:

# spec/exhibits/picture_post_exhibit_spec.rb
require_relative '../spec_helper_lite'
require_relative '../../app/exhibits/picture_post_exhibit'

describe PicturePostExhibit do
  before do
    @post = OpenStruct.new(
      title:   "TITLE", 
      body:    "BODY", 
      pubdate: "PUBDATE")
    @context = stub!
    @it = PicturePostExhibit.new(@post, @context)
  end

  it "delegates method calls to the post" do
    @it.title.must_equal "TITLE"
    @it.body.must_equal "BODY"
    @it.pubdate.must_equal "PUBDATE"
  end

  it "renders itself with the appropriate partial" do
    mock(@context).render(
      partial: "/posts/picture_body", locals: {post: @it}){
      "THE_HTML"
    }
    @it.render_body.must_equal "THE_HTML"
  end
end

We define stubs for both a "post" object, and a "context" object. The @post stub stands in for a Post instance. The @context object stands in for the Rails template object which is the context that all views are rendered in. When you call helpers like #render or #form_for in a Rails view, you're calling them on the template object.

Then we specify that the exhibit must 1) act as a "pass-through" object, forwarding any methods it doesn't know about on to the model object; and 2) that it must know how to use the context to render an appropriate post body partial. The pass-through property satisfies the "transparency" requirement of the Decorator pattern, of which Exhibit is a subset.

Next we write an implementation which satisfies this spec.

# app/exhibits/picture_post_exhibit.rb
require 'delegate'
class PicturePostExhibit < SimpleDelegator
  def initialize(model, context)
    @context = context
    super(model)
  end

  def render_body
    @context.render(partial: "/posts/picture_body", locals: {post: self})
  end
end

We've defined a new directory, app/exhibits, for Exhibit objects. In it, we've created a PicturePostExhibit class.

This class inherits from SimpleDelegator. SimpleDelegator is Ruby standard library class which has a very simple job: forward all calls to an underlying object. Not very useful in and of itself; but as a basis for defining Decorator objects it is quite handy.

In the exhibit initializer, we save the view context in an instance variable. Then we call the SimpleDelegator initializer with super, to set up delegation to the model object.

In the #render_body method, we use the saved @context to render a partial for a picture-type post.

The exhibit for text-only posts is nearly identical. Because it's so similar, I'll omit the spec for it and just show the implementation:

# exhibits/text_post_exhibit.rb
require 'delegate'
class TextPostExhibit < SimpleDelegator
  def initialize(model, context)
    @context = context
    super(model)
  end

  def render_body
    @context.render(partial: "/posts/text_body", locals: {post: self})
  end
end

The only difference here is a different partial being rendered.

Now we need an easy way to wrap a model object in the appropriate exhibits (if any). Let's spec out a helper to do that:

# spec/helpers/exhibits_helper_spec.rb
require_relative '../spec_helper_lite'
require_relative '../../app/helpers/exhibits_helper'

stub_class 'PicturePostExhibit'
stub_class 'TextPostExhibit'
stub_class 'Post'

describe ExhibitsHelper do
  before do
    @it = Object.new
    @it.extend ExhibitsHelper
    @context = stub!
  end

  it "decorates picture posts with a PicturePostExhibit" do
    post = Post.new
    stub(post).picture?{true}
    @it.exhibit(post, @context).must_be_kind_of(PicturePostExhibit)
  end

  it "decorates text posts with a TextPostExhibit" do
    post = Post.new
    stub(post).picture?{false}
    @it.exhibit(post, @context).must_be_kind_of(TextPostExhibit)
  end

  it "leaves objects it doesn't know about alone" do
    model = Object.new
    @it.exhibit(model, @context).must_be_same_as(model)
  end
end

By its nature, ExhibitsHelper is a piece of code which will have to reference a lot of different classes, both model classes and exhibit classes. In order to avoid having test dependencies on all those class definitions, we define and use a #stub_class test helper which is almost identical in definition to the #stub_module method we wrote before.

Here's helper code which satisfies the spec:

# app/helpers/exhibits_helper.rb
module ExhibitsHelper
  def exhibit(model, context)
    # Doing a string comparison because of Rails class-reloading weirdness
    case model.class.name
    when 'Post'
      if model.picture?
        PicturePostExhibit.new(model, context)
      else
        TextPostExhibit.new(model, context)
      end
    else
      model
    end
  end
end

Hey, I thought we were getting *rid* of conditionals! That's just a giant mass of conditionals! This is true. Unfortunately, it's not always possible to completely eliminate type-based conditionals. What we can do is isolate the conditionals to a single place, rather than scattering them all over our view code. That's exactly what we're trying to do here. Anywhere we might have done an if...then...else in a view template based on an object's class or traits, we can instead add an exhibit to handle the conditional behavior polymorphically. All the conditionals are consolidated on this one helper method, which decides which exhibit(s) to apply to a given object.

The helper code above uses a #picture? predicate method on Post objects. Let's quickly implement that.

Spec:

# ...
describe "#picture?" do
  it "is true when the post has a picture URL" do
    @it.image_url = "http://example.org/foo.png"
    assert(@it.picture?)
  end
  it "is false when the post has no picture URL" do
    @it.image_url = ""
    refute(@it.picture?)
  end
end
# ...

Implementation:

# ...
def picture?
  image_url.present?
end
# ...

Because we'll probably be using the #exhibit helper method all over the place in the future, we'll put it in our ApplicationController:

class ApplicationController < ActionController::Base
  # ...
  helper :exhibits
  # ...
end

Now, with our tiny homegrown exhibit framework in place, we rewrite the blog entry partial.

<% entry = exhibit(entry, self) %>
<article>
  <header>
    <p><time pubdate="pubdate"><%= entry.pubdate %></time></p>
    <h3><%= entry.title %></h3>
  </header>
  <%= entry.render_body %>
</article>

No more conditionals in the view! Just a simple method call to #render_body which Does The Right Thing.

Here's how it looks when we post a picture:

Posting a picture

Now, if you follow trends in the Rails community at all, right about now you're probably exclaiming "hang on, aren't you talking about Presenters?".

The truth is, in the first few drafts this whole section was about Presenters. Then I started researching the history of the Presenter concept in Ruby and Rails. And the more I read, the less certain I became about my terminology.

The idea of a Presenter was first introduced to the Rails community by Jay Fields in a series of blog articles in 2006 and 2007. Fields summarizes the Presenter pattern as follows:

The Presenter pattern addresses bloated controllers and views containing logic in concert by creating a class representation of the state of the view. An architecture that uses the Presenter pattern provides view specific data as attributes of an instance of the Presenter. The Presenter's state is an aggregation of model and user entered data.

The Presenter as described by Fields is reminiscent of the intermediate representation in the "Two Step View" pattern:

…a logical screen structure that is suggestive of the display elements yet contains no HTML.

The canonical example for this Presenter is a report or summary, where a number of disparate elements from different models need to be brought together on a single page. Rather than have the controller fetch each element individually, it instead instantiates a Presenter object which aggregates the separate elements into a single unit customized for that particular view.

Over time Fields and others elaborated and extended the Presenter concept, to include view-specific attributes (such as a list of possible values for a <select> tag); non-persisted fields (such as the "confirm password" field on an account creation page); validations and error messages (thereby keeping user-facing error strings out of the models); and, in some versions, the ability to accept updated data and save the new values back to their respective tables.

More recently, various programmers, including your author, have evolved a more granular variation on the Presenter idea, where individual model instances are wrapped with an object whose responsibility is to adapt the model for presentation. Often (but not always) these wrappers are proper Decorators, passing through any un-overridden method to the underlying model instance.

At first these differences seemed like minor variations on a theme; but the more I thought about it the more I realized they are two largely orthogonal concepts.

"Classic" presenters are oriented towards a particular view; they are, in Jay Fields' words, "class versions of your views". They have names like ReportPresenter or OrderCompletionPresenter. In contrast, this second generation of presenters are oriented primarily towards specific models. They have names like UserPresenter or PicturePostPresenter. They enable a particular model instance to render itself to a page.

Taking all this into consideration, I realized that if I persisted in calling these things "Presenters", I'd be—at best—further muddying the semantic waters. As I mentioned earlier, I considered calling them "Presenter Decorators", but that still seemed like it could lead to confusion. At the same time I didn't want to simply call them "Decorators" because I think they are a sufficiently specialized kind of Decorator to deserve their own designation. Eventually I settled on "Exhibit", a term which as far as I know is unencumbered by previous pattern associations.

When we tease these two concepts of "Presenter" and "Exhibit" into separate entities, we realize that they are complementary patterns that could easily work together in an application. This text deals mainly with Exhibits, but it's easy to imagine an app in which Exhibits are aggregated together under a combined Presenter for a particular page.

Note: By introducing the "Exhibit" terminology, my intention is not to impose my own naming on anyone else's work. I simply want to keep my ideas from further polluting the already overburdened "Presenter" namespace. Others are welcome to use the "Exhibit" term if they find it helpful, but in the context of this text I am only applying the term to the presentational decorators described here.

For the purposes of clarity, here's a rundown of the essential characteristics of an Exhibit object.

An Exhibit object:

• Wraps a single model instance.
• Is a true Decorator. All unrecognized messages are passed through to the underlying object. This facilitates a gradual migration to the use of Exhibits to encapsulate presentation knowledge, since they can be layered onto models without any change to the existing views. It also enables multiple Exhibits to be layered onto an object, each handling different aspects of presentation.
• Brings together a model and a context. Exhibits need a reference to a "context" object—either a controller or a view context—in order to be able to render templates as well as construct URLs for the object or related resources.
• Encapsulates decisions about how to render an object. The tell-tale of an Exhibit is telling an object "render yourself", rather than explicitly rendering a template and passing the object in as an argument.
• May modify the behavior of an object. For instance, an Exhibit might impose a scope on a Blog#entries association which only returns entries that are visible to the current user (as determined from the Exhibit's controller context). Or it might reformat the return value of a #social_security_number method to include dashes and have all but the last four digits obscured: ***-**-5678.

The two exhibits we defined earlier are nearly identical. Clearly, they are ripe for refactoring. Let's take care of that. We'll move the commonalities into a Exhibit base class:

# app/exhibits/exhibit.rb
require 'delegate'
class Exhibit < SimpleDelegator  
  def initialize(model, context)
    @context = context
    super(model)
  end
end

Now our exhibits are are a lot slimmer:

require_relative 'exhibit'
class PicturePostExhibit < Exhibit
  def render_body
    @context.render(partial: "/posts/picture_body", locals: {post: self})
  end
end

The specs we wrote earlier help ensure that we haven't broken anything by performing this refactoring.

Before we move on, let's add a couple of extras to the Exhibit base class.

class Exhibit < SimpleDelegator  
  # ...
  def to_model
    __getobj__
  end
  def class
    __getobj__.class
  end
end

We don't have time to demonstrate it here, but these will help prevent certain "gotchas" down the road. The first one defines #to_model to return the wrapped model (the strange #__getobj__ method is how SimpleDelegator refers to its underlying object). The second one is a flat-out fib: it redefines #class to return the class of the original model, instead of the class of the exhibit. Together, these methods will help ensure that Rails helpers such as #form_for don't get confused when they encounter models wrapped in exhibits.

A little while ago we wrote this:

# app/helpers/exhibits_helper.rb
module ExhibitsHelper
  def exhibit(model, context)
    # Doing a string comparison because of Rails class-reloading weirdness
    case model.class.name
    when 'Post'
      if model.picture?
        PicturePostExhibit.new(model, context)
      else
        TextPostExhibit.new(model, context)
      end
    else
      model
    end
  end
end

On one hand, this code makes it very easy to see, in one place, what exhibits will be applied to a given object. On the other hand, even with just three exhibits it's already a nasty nested conditional. We wouldn't want to keep adding to it without refactoring it somehow.

Let's look at one possible refactoring. First, we rewrite the ExhibitsHelper#exhibit method to delegate to a class method on the Exhibit base class.

# ...
def exhibit(model, context)
  Exhibit.exhibit(model, context)
end
# ...

Next we implement Exhibit.exhibit to iterate through a list of exhibits, giving each one an opportunity to wrap the provided object.

class Exhibit < SimpleDelegator
  # ...
  def self.exhibit(object, context)
    exhibits.inject(object) do |object, exhibit|
      exhibit.exhibit_if_applicable(object, context)
    end
  end
  # ...
end

This code bears a strong resemblance to the Chain of Responsibility pattern. It differs from the traditional version of that pattern in that it doesn't return as soon as the first exhibit capable of wrapping the object is found.

We define Exhibit.exhibit_if_applicable to query a .applicable_to? predicate against the given object, and instantiate itself if the result is affirmative.

class Exhibit < SimpleDelegator
  # ...
  def self.exhibit_if_applicable(object, context)
    if applicable_to?(object)
      new(object, context)
    else
      object
    end
  end
  # ...
end

Note that .exhibit_if_applicable is an example of "Tell, Don't Ask". This keeps the .exhibit logic nicely focused on one and only one thing: giving each exhibit an opportunity to apply itself to the object at hand.

In Exhibit, .applicable_to? will simply return false. Subclasses will have to implement it to match applicable objects.

def self.applicable_to?(object)
  false
end

We add a .applicable_to? predicate to each concrete Exhibit subclass, implementing the appropriate matching semantics for that exhibit. For instance, the PicturePostExhibit.applicable_to? method checks to see if the given object is a picture Post.

class PicturePostExhibit < Exhibit
  def self.applicable_to?(object)
    object.is_a?(Post) && object.picture?
  end
  # ...
end

Likewise for the other two exhibits:

class TextPostExhibit < Exhibit
  def self.applicable_to?(object)
    object.is_a?(Post) && (!object.picture?)
  end
  # ...
end
class LinkExhibit < Exhibit
  # ...
  def self.applicable_to?(object)
    object.is_a?(Post)
  end
  # ...
end

Finally, we define Exhibit.exhibits to return a hard-coded list of exhibits to try.

class Exhibit < SimpleDelegator
  def self.exhibits
    [
     TextPostExhibit,
     PicturePostExhibit,
     LinkExhibit
    ]
  end
  # ...
end

Hard-coding this list is a little non-DRY. We could instead define an .inherited callback on Exhibit which would automatically add exhibits to an internal list as they are loaded.

The advantage of hard-coding the list is that it ensures a consistent and obvious ordering of exhibits. We know which exhibits may be applied, and we know the order in which they will be tried. There are advantages to both approaches, but personally, based on experience debugging auto-generated lists of classes, I lean towards the explicit list. Even though it duplicates a little bit of knowledge.

Our original #exhibit helper and our new refactored version share a common property which might not be immediately obvious: They both enable a many-to-many relationship between business models and exhibits. That is, some model objects may have no exhibits which apply to them. Other models may have multiple exhibits "stacked" on them. Some exhibits may be applicable only to a single model class, whereas others might be common across many types of model.

This is an important point. A big part of the power of the Exhibit pattern is being able to freely vary both sides of the Exhibit/Model relationship. It gives us two independent "axes" of change—one for business decisions, one for presentation decisions.

This is why we haven't implemented any kind of convention-based exhibit discovery—e.g. we don't automatically look up a PostExhibit for a Post object. The strength of the pattern lies in the ability to independently vary the business model and the view model, so we don't want to arbitrarily constrain ourselves by binding business models and exhibits in a one-to-one, lockstep relationship.

Our use of exhibits raises the question: what do we need view helpers for? Anything?

In my experience helpers in Rails apps tend to devolve into large, disorganized bags of unrelated methods. Often these methods repeat the same conditional business logic over and over again. For instance, how many times have you seen helper code like this:

if current_user.logged_in?
  # ...
else
  # ...
end

Thinning out helpers by taking some of their presentation responsibilities away is not a bad thing, in my view.

That said, I don't think helpers are completely useless. They are a good place to put general rendering methods which aren't tied to any particular model. For instance, we could write a helper for displaying HTML5-style images with captions:

module FigureHelper
  def figure(image_path, caption)
    content_tag(:figure) do 
      image_tag(image_path) +
        content_tag(:figcaption, caption)
    end
  end
end

This helper generates markup that looks like this:

<figure>
  <img alt="freshpaint.jpg" src="http://example.org/f.jpg" />
  <figcaption>Fresh paint</figcaption>
</figure>

This is pretty generic code, and I think it works well in a helper.

ActiveRecord is an Object-Relational Mapper (ORM) based on the Active Record pattern from Patterns of Enterprise Application Architecture. As an ORM, it is semi-orthogonal to the business logic of your application. ORMs handle the loading and saving of objects to records in a database. The behavior of those objects, apart from persistence, is (theoretically) outside of the ORM's responsibilities.

In practice, real world Rails-based projects tend to be almost inextricably coupled to the ActiveRecord library. And not just to ActiveRecord; ActiveRecord-based apps also tend to have very tight inter-coupling between the various models in the system. In pathological cases, controllers and even views are also closely married to the details of ActiveRecord and database schema.

Part of this is doubtless due to the way ActiveRecord integrates with models. By declaring an is-a relationship between ActiveRecord and model classes, your models are no longer just domain models; they effectively are ActiveRecord. One result of this tight coupling is that novice and intermediate Rails developers are often surprised to find out that it's even permissible to have model objects which do not inherit from ActiveRecord::Base. And even after they learn this they sometimes still exile their non-ActiveRecord models to the lib/ ghetto, denying them their true place in app/models.

Looking at our models, it's pretty clear that we need a "posts" table to hold blog posts. So we'll start by creating a migration to create that table.

class CreatePosts < ActiveRecord::Migration
  def self.up
    create_table :posts do |t|
      t.datetime :pubdate
      t.string :title
      t.text :body
      t.string :image_url
      t.timestamps
    end
  end
  def self.down
    drop_table :posts
  end
end

Once we run this migration, we have a place to keep our blog posts. Now we need to make the Post model store itself there.

We need to make several changes to the Post and Blog code.

require 'date'
require 'active_record'
class Post < ActiveRecord::Base
  validates :title, presence: true
  attr_accessor :blog
  def picture?
    image_url.present?
  end
  def publish(clock=DateTime)
    return false unless valid?
    self.pubdate = clock.now
    @blog.add_entry(self)
  end
end

• Post now inherits from ActiveRecord::Base. We require active_record for when we are running tests in isolation.
• The various individual ActiveModel mixins are gone, subsumed into ActiveRecord::Base.
• No more attribute accessors for title, body, and image_url. Those are handled by ActiveRecord now.
• No more initializer. Its former functionality is rendered redundant by the AR initializer.
• #persisted? is gone too, for the same reason.

Moving on to Blog:

class Blog
  # ...

  def initialize(entry_fetcher=Post.public_method(:all))
    @entry_fetcher = entry_fetcher
  end

  # ...

  def entries
    fetch_entries.sort_by{|e| e.pubdate}.reverse.take(10)
  end

  # ...

  def add_entry(entry)
    entry.save
  end

  private

  def fetch_entries
    @entry_fetcher.()
  end

  # ...
end

• The @entries instance variable, which used to point to an array of entries, is gone. In it's place is an @entry_fetcher variable. We're using this variable to make the strategy for finding blog entries an inject-able dependency. This will make testing the class easier.
• Since posts live in the database now, the default method for fetching a list of entries is to call Post.all.
• Apart from using the entry fetcher instead of referencing the @entries list directly, the entries method has changed surprisingly little. Because the result of ActiveRecord's #all is Enumerable, we can still use the same sorting and filtering methods we used before. It's not efficient, but it works for now.
• #add_entry, instead of adding the post to an internal list, now calls #save on the passed entry.

That last item warrants some more discussion. Originally, Blog#add_entry was needed because Blog maintained an internal list of entries. But now that posts are stored in the DB, can't we just call #save on them directly from Post#publish, and do away with Blog#add_entry?

Here's the thing: while the data storage strategy has changed, the conceptual model of the application ought to stay the same. And that model is that a Blog is currently the top-level object in the app, and it is responsible for creating and maintaining a list of blog entries.

Does it really matter who does the saving? Consider this: supposing one day we decide to add a feature where our blog will send notifications to our social networking accounts (Twitter, Facebook, etc.) whenever a new post is published. This is publishing of notifications should probably be accessible from the top-level blog object, since it will presumably have references to the needed account information objects. Let's say there's a Blog#spam_social_networks(entry) method.

If Posts are responsible for saving themselves, the Blog object will have no way of knowing when a new post goes up, and therefore needs to be broadcast. Which means we'd probably wind up adding an after_save hook in Post, something like this:

class Post < ActiveRecord::Base
  # ...
  after_save :broadcast_entry
  # ...
  private

  def broadcast_entry
    blog.spam_social_networks(self)
  end
end

The trouble is, spamming social networks is almost entirely orthogonal to a Post's primary responsibility of representing a blog post. The origins of many a bloated model can be traced back to this kind of gradual responsibility creep.

When we keep the conceptual responsibility of adding a new post on the Blog, there's no need for callbacks:

# ...
def add_entry(entry)
  entry.save
  spam_social_networks(entry)
end
# ...

That's shorter and (I'd argue) a better place for the code. The larger point here is that by first building up our domain models divorced from persistence concerns, we came up with a design that closely matches our mental picture of the problem. As a result, new features that are still consistent with our original conception of the problem space tend to slot in neatly.

(You might be objecting "but wait! Now Blog has two responsibilities!" This is true, and a fair point. We can optimistically imagine that #spam_social_networks is only an entry point to a third object whose sole responsibility is sending out notifications.)

As you might imagine, we need to make a number of changes to the Post and Blog specs to adapt them to these changes. We'll start with Blog.

First of all, in creating a Blog instance to test, we now supply our own entries list instead of letting it reach out to Post for the list.

# ...
before do
  @entries = []
  @it = Blog.new(->{@entries})
end
# ...

And instead of asserting that #add_entry adds an item to an internal list, we now assert that it calls #save to add the entry:

# ...
describe "#add_entry" do
  it "adds the entry to the blog" do
    entry = stub!
    mock(entry).save
    @it.add_entry(entry)
  end
end
# ...

If you recall, the tests for Blog also specify that it must return only 10 entries from #entries, and they must be sorted in reverse-chronological order. We could inject a fake entries collection into the object and continue to test it as we did before. But this would make for a fragile test. We probably want to change the Enumerable code to native ActiveRecord filtering/limiting calls at some point in the future. At that point our specs would break.

One option is that we simply remove the specs when that happens, since we trust that ActiveRecord will implement sorting and filtering correctly. But do we trust ourselves to call ActiveRecord correctly?

Instead, what we'll do is move these specs from the current isolated unit test into a separate Blog integration test suite. This suite will hit the actual database.

# spec/models/blog_integration_spec.rb
require_relative '../spec_helper_full'

describe Blog do
  include SpecHelpers
  before do
    setup_database
    @it = Blog.new
  end

  after do
    teardown_database
  end

  describe "#entries" do
    def make_entry_with_date(date)
      @it.new_post(pubdate: DateTime.parse(date), title: date)
    end

    it "is sorted in reverse-chronological order" do
      oldest = make_entry_with_date("2011-09-09")
      newest = make_entry_with_date("2011-09-11")
      middle = make_entry_with_date("2011-09-10")

      @it.add_entry(oldest)
      @it.add_entry(newest)
      @it.add_entry(middle)
      @it.entries.must_equal([newest, middle, oldest])
    end

    it "is limited to 10 items" do
      10.times do |i|
        @it.add_entry(make_entry_with_date("2011-09-#{i+1}"))
      end
      oldest = make_entry_with_date("2011-08-30")
      @it.add_entry(oldest)
      @it.entries.size.must_equal(10)
      @it.entries.wont_include(oldest)
    end
  end
end

This spec will continue to specify the expected order and collection size regardless of how the selection is accomplished inside Blog.

This is a technique I often use in the apps I work on. Separating unit tests from integration tests puts a clear divider between the tests that verify that our database interactions are doing what we think they are doing, from the tests that specify what logic our models should implement.

It also makes it very easy to run only the fast, isolated tests; or only the slow, DB-bound tests. Keeping as many of our tests as possible in super-fast isolation means we can complete the red-green-refactor cycle in seconds rather than minutes.

You may have noticed some new methods being called in the before and after blocks. These ensure that the database contents is blown away before and after test runs. Here are the definitions:

# spec/spec_helper_full.rb
require_relative 'spec_helper_lite'
require_relative '../config/environment.rb'
module SpecHelpers
  def setup_database
    DatabaseCleaner.strategy = :transaction
    DatabaseCleaner.clean_with(:truncation)
    DatabaseCleaner.start
  end
  def teardown_database
    DatabaseCleaner.clean
  end
end

The majority of changes we make to the Post tests are removals. For instance, this test asserts that we can pass attributes into Post#new:

it "supports setting attributes in the initializer" do
  it = Post.new(title: "mytitle", body: "mybody")
  it.title.must_equal "mytitle"
  it.body.must_equal "mybody"
end

We are reasonably confident that this functionality Just Works in ActiveRecord, so we trash the test.

Throwing away tests… does this mean that the test was a waste of time? No, it served its purpose. We're using tests primarily for the sake of driving design, so even if we threw them all out right now they would still have played their part. Of course, it's also nice to have them around to catch regressions; but deleting the odd test should not be cause for consternation.

Post is now an ActiveRecord::Base derivative, which means it's going to be trying to talk to the database all the time. How can we continue to test it in isolation? We'll use a couple of strategies to make that work.

First, remember how we said we were going to treat ActiveRecord as an implementation detail rather than as an essential part of the model? Now we put those words into action. Here's the top-level setup block for Post tests:

before do
  # ...
  @it = Post.new(title: "TITLE")
  @ar = @it
  # ...
end

In this setup block, we take a second reference to the object being tested and call it @ar. It's actually the same object, but we'll use it for creating mocks and stubs of ActiveRecord-provided methods. We want to treat ActiveRecord as just another collaborator, and the @ar alias helps us make that delineation more "real".

Here's an example where we use the alias:

# ...
before do
  stub(@ar).valid?{false}
end

it "wont add the post to the blog" do
  dont_allow(@blog).add_entry
  @it.publish
end
# ...

We want to simulate the case where the object is invalid. Since validity checking is provided by ActiveRecord, we treat it as an external dependency and stub it out with stub(@ar).valid?{false}. Then we attempt to publish the post, and verify that in an invalid state the post will not be added to the blog.

Secondly, in order to avoid the overhead of connecting to a real database, we use NullDB to set up a do-nothing database connection before running the specs.

# ...
before do
  setup_nulldb
  # ...
end

after do
  teardown_nulldb
end
# ...

These helpers are defined in spec_helper_lite.rb:

module SpecHelpers
  def setup_nulldb
    schema_path = File.expand_path('../db/schema.rb', 
                                   File.dirname(__FILE__))
    NullDB.nullify(schema: schema_path)
  end

  def teardown_nulldb
    NullDB.restore
  end
end

Now that we have both isolated unit tests and integration tests, it seems like a good time to set up some Rake tasks for running them. We want shortcuts for running just the unit tests, just the integration tests, or all of the above.

# lib/tasks/test.rake
require 'rake/testtask'
namespace 'test' do |ns|
  test_files             = FileList['spec/**/*_spec.rb']
  integration_test_files = FileList['spec/**/*_integration_spec.rb']
  unit_test_files        = test_files - integration_test_files
  desc "Run unit tests"
  Rake::TestTask.new('unit') do |t|
    t.libs.push "lib"
    t.test_files = unit_test_files
    t.verbose = true
  end
  desc "Run integration tests"
  Rake::TestTask.new('integration') do |t|
    t.libs.push "lib"
    t.test_files = integration_test_files
    t.verbose = true
  end
end
# Clear out the default Rails dependencies
Rake::Task['test'].clear
desc "Run all tests"
task 'test' => %w[test:unit test:integration]

We define a FileList, test_files, which expands to all of the project's tests. Then we define a subset which expands to only the integration tests. Remember, we kept them in separate files ending in _integration_spec.rb, making them easy to match. Finally, we subtract the integration tests from the full set of tests to get a list of unit_test_files.

Once we have our file lists, it's a straightforward matter of declaring some Rake::TestTask tasks for each set, and a top-level test task which depends on both of them.

In the code above we constructed a chinese wall between the bits of the model that ActiveRecord provides, and the bits that we provide. Some Rails practitioners prefer to set up a stricter division between business logic and storage logic.

In order to accomplish this, they create separate business model objects which keep an internal reference to an ActiveRecord object. The ActiveRecord object is kept intentionally "skinny", containing only associations, scopes, and validations. The business model object delegates its storage to the AR object, but handles everything else internally. The ActiveRecord object becomes a way to get at the stored data, and nothing more.

Piotr Solnica has a great post about this pattern. Personally, I think this is a promising technique for separating concerns. But I also think it may be a bit heavyweight for some apps. In the code above I've tried to strike a middle ground, using convention more than hard object divisions to separate the concerns, and not straying too far from Rails norms. A little later on, once we get into tagging, we'll revisit this idea of using ActiveRecord as just a thin layer over database rows.

The FigLeaf technique demonstrated above is an incremental approach to partitioning business logic from the persistence mechanism. It's an aid to help you think about the two concerns separately, without departing too far from Rails conventions.

If you and your app are ready for a bigger step towards true separation of concerns, you may want to look into the Data Mapper pattern, as described in "Patterns of Enterprise Application Architecture". Note that this is not the same as the DataMapper project. Just as ActiveRecord is an implementation of the Active Record pattern in Ruby, so the DataMapper gem is a (partial) implementation of the Data Mapper pattern.

The Data Mapper pattern completely separates business models from persistence concerns. In it business models have no knowledge of how to save themselves; instead, mapper objects map model properties to database columns. This separation gives you the ability to make substantial changes to your persistence strategy without affecting your business logic, and vice-versa.

To my knowledge, there is no complete library implementation of the Data Mapper pattern in Ruby. The Ruby DataMapper project does not yet enable full separation of business objects and mapper objects. That said, it is still a fantastic library which in many ways exceeds ActiveRecord. Given the choice, I'll always pick DataMapper over ActiveRecord for a new project. The only reason I didn't pick it for this text is that I didn't want to introduce too many new concepts at one time. And the future of DataMapper is bright: the developers are making steady progress towards a 2.0 release which promises to finally give the Ruby world a full-fledged Data Mapper pattern implementation.

I include this example because of a tendency I've noticed for Rails models to overuse hooks. ActiveRecord hooks are a variation on the Observer pattern, and the point of Observer is to enable other objects to be notified on an object's lifecycle events. Not so that the object can stare at itself in the mirror all day.

If we need to intercept an ActiveRecord-provided method, we can just intercept it. There are some exceptions, like after_find, which let us hook into Rails machinery that might otherwise be difficult to override. But for simple cases, we can do the simple thing and override the method we want to change. Following a few rules will keep us from inadvertently breaking things in the process:

1. Unless you care about the value of arguments, use a single * as the method parameters so that the override doesn't interfere with the original method's protocol.
2. Always call super, unless you are intentionally canceling the default behavior.
3. Always call super without parentheses, unless you want to explicitly change the arguments going to the parent method. Leaving out the parentheses tells Ruby to re-use the arguments which were passed into the current method.
4. Remember to return the result of =super=, by either making super the last call in the method, writing return super, or saving the return value in a local variable and then returning the local at the end. If you need to do some processing after the call to super, but you don't want to save the return value in a local, you can use #tap:

   def foo(*)
     super.tap do
       # ... after-super processing
     end
   end
   
   

Looking at the list of use cases, it seems clear that we'll need some kind of object that represents a list of tags. Let's start with that.

describe TagList do
  # ...
end

The most basic behavior we can specify is how the TagList will behave with no tags in it.

describe "given a blank string" do
  before do
    @it = TagList.new("")
  end

  it "is empty" do
    @it.must_be_empty
  end

  it "stringifies to the empty string" do
    @it.to_s.must_equal ""
  end

  it "arrayifies to the empty array" do
    @it.to_a.must_equal []
  end
end

TagList should assist us in converting from the space- or comma-separated strings that users type in.

describe "given tags separated by commas or whitespace" do
  before do 
    @it = TagList.new("barley, hops water, yeast")
  end

  it "is not empty" do
    @it.wont_be_empty
  end

  it "stringifies to a comma separated list" do
    @it.to_s.must_equal "barley, hops, water, yeast"
  end

  it "arrayifies to a list of strings" do
    @it.to_a.must_equal %w[barley hops water yeast]
  end
end

It should also eliminate any duplicates.

describe "given duplicate tags" do
  before do
    @it = TagList.new("barley, hops, barley")
  end

  it "eliminates duplicates" do
    @it.to_a.must_equal %w(barley hops)
  end
end

describe "given duplicate mixed case tags" do
 before do
   @it = TagList.new("barley, hops, BarlEy")
 end

 it "eliminates duplicates ignoring case" do
   @it.to_a.must_equal %w(barley hops)
 end
end

It should normalize the tags to lowercase.

describe "given mixed-case tags" do
  before do 
    @it = TagList.new("Barley, hOps, YEAST")
  end

  it "lowercases the tags" do
    @it.to_a.must_equal %w(barley hops yeast)
  end
end

It shouldn't be tripped up by being instantiated with nil.

describe "given nil" do
  before do 
    @it = TagList.new(nil)
  end
  it "is empty" do
    @it.must_be_empty
  end
end

We'll need to be able to combine tag lists together if we're going to show an overview of all tags in use on the blog.

describe "#+" do
  it "combines tag lists into one" do
    result = TagList.new("foo, bar") + TagList.new("baz, buz")
    result.must_equal(TagList.new("foo, bar, baz, buz"))
  end
end

That tag overview should probably be in alphabetical order, so we'll want the tag list to be able to return a sorted version of itself.

describe "#alphabetical" do
  before do
    @it = TagList.new("foo, bar, baz, fuz")
    @result = @it.alphabetical
  end
  it "returns the tags in alpha order" do
    @result.to_a.must_equal %w(bar baz foo fuz)
  end
  it "returns another tag list" do
    @result.must_be_kind_of TagList
    @result.wont_be_same_as @it
  end
end

Finally, we'll specify a handy conversion method to quickly turn things that aren't tag lists into tag lists.

describe "TagList()" do
  describe "given a TagList" do
    it "returns the same tag list" do
      list = TagList.new("")
      TagList(list).must_be_same_as(list)
    end
  end
  describe "given an array" do
    before do
      @it = TagList(%w[foo bar])
    end
    it "returns a tag list" do
      @it.must_be_kind_of(TagList)
    end
    it "contains the given tags" do
      @it.to_a.must_equal(%w[foo bar])
    end
  end
end

The converter has a similar look and feel to Ruby's built-in conversion methods such as String, Array, and Integer.

Implementing these requirements takes considerably less space than we needed to spec them out:

require 'forwardable'
module Conversions
  private
  def TagList(value)
    return value if value.is_a?(TagList)
    TagList.new(value)
  end
end
class TagList
  extend Forwardable
  include Enumerable
  attr_reader :tags
  def_delegators :tags, :empty?, :to_a, :each
  def initialize(tags)
    case tags
    when Array
      @tags = tags
    else
      @tags = tags.to_s.split(/\W+/)
    end
    @tags.each(&:downcase!)
    @tags.uniq!
  end
  def to_s
    tags.join(", ")
  end
  def to_ary
    @tags
  end
  def +(other)
    self.class.new(to_a + other.to_a)
  end
  def ==(other)
    to_a == Array(other)
  end
  def alphabetical
    self.class.new(tags.sort)
  end
end

Our TagList implementation behaves much like an Array, and in fact it is built on top of an internal Array called @tags which holds the actual tag strings. Some of its Array-style methods, like empty? and :each, don't need any special treatment, so TagList passes them straight on to the underlying Array using the Forwardable library. Other methods have more tag-specific behavior, and are explicitly implemented.

You may have noticed a funny little module named Conversion in the code above. We anticipate that we will want access to the TagList() converter method from more than one class or module. But adding it to the global namespace would be bad form. So instead we define a module to act as a namespace for conversion methods. We'll reopen this module and add other converter methods to it as our codebase expands. Any class needing access to conversions will then be able to include the Conversion module and have access to all defined converter methods.

Now how do we attach our tag list class to a Post object? We'll start out with a naive solution which just serializes the tags to a column in the posts table. In order to do that, we create a migration for a new tags column.

class AddTagsToPosts < ActiveRecord::Migration
  def self.up
    add_column :posts, :tags, :string
  end
  def self.down
    remove_column :posts, :tags, :string
  end
end

Now we need to tell Post to represent its new tags attribute as a TagList instead of as a raw string. We do that using ActiveRecord's composed_of facility:

composed_of :tags, class_name: 'TagList', mapping: %w(tags tags),
                   converter: ->(value) { TagList(value) }

This incantation tells ActiveRecord to mediate access to the tags attribute using a TagList. When a new Post is created, ActiveRecord will initialize a TagList object, passing it the raw tags data. When it comes time to write the record back to the database, ActiveRecord will use the TagList's own tags attribute as the new value of the tags field. Recall that in TagList, #tags is an accessor to the underlying Array instance.

The :converter option tells ActiveRecord what to do when some code calls post.tags= with a new value. In this case, it will convert the given value into a TagList.

TagList represents itself internally using an array, but the tags column we just created is a simple string field. In order to safely write an array into a string field and get it out again as an array, we need to tell ActiveRecord to serialize the field:

serialize :tags

Now whenever the tags field is written to the database, the value (an array provided by TagList) will first be serialized into YAML format. When it is read out again, it will be parsed from the YAML back into an array, and the array will be fed back into a new TagList.

We could have serialized the TagList object itself to the tags column. But serializing application objects to YAML can lead to headaches down the road. We have to ensure that the TagList code is loaded before accessing that field, something that can be surprisingly tricky when running in development mode with Rails' class autoloading enabled. And if we ever changed the representation of TagList, we could find ourselves in versioning hell as we try to load TagList objects which were serialized before the change. It's all-around easier to only serialize Ruby built-ins like Arrays and Hashes.

Now we can attach tags to an individual post, but we also need to be able to get a list of all the tags in use, and to find all posts with a given tag. In order to drive out this functionality, we create a new integration spec suite for the Post class, to complement its existing unit-level spec suite.

describe Post do
  include SpecHelpers
  before do
    setup_database
    @blog = Blog.new
  end
  after do
    teardown_database
  end
  def make_post(attrs)
    attrs[:title] ||= "Post #{attrs.hash}"
    post = @blog.new_post(attrs)
    post.publish.must_equal(true)
    post
  end
  describe ".all_tags_alphabetical" do
    before do
      @post_tags = [
                    nil,        # make sure nils are handled
                    %w(barley yeast),
                    %w(yeast hops),
                    %w(water)
                   ]
      @post_tags.each do |tags|
        make_post(title: tags.inspect, tags: tags)
      end
      @it = Post.all_tags_alphabetical
    end
    it "returns a unique, alphabetized list of all tags" do
      @it.must_equal TagList(%w(barley hops water yeast))
    end
  end
  describe ".tagged" do
    it "filters the collection by tag" do
      duck  = make_post tags: %w[billed feathered]
      robin = make_post tags: %w[reddish feathered]
      fox   = make_post tags: %w[reddish furred]
      platypus = make_post tags: %w[billed furred]

      reddish = Post.tagged("reddish")
      reddish.size.must_equal 2
      reddish.must_include(robin)
      reddish.must_include(fox)
      furred = Post.tagged("furred")
      furred.size.must_equal 2
      furred.must_include(fox)
      furred.must_include(platypus)
    end
  end
end

These new specs are satisfied with a trio of new class-level methods on Post:

class Post
  LIMIT_DEFAULT=10
  # ...
  def self.most_recent(limit=LIMIT_DEFAULT)
    order("pubdate DESC").limit(limit)
  end

  def self.all_tags_alphabetical
    all_tags.alphabetical
  end

  def self.all_tags
    except(:limit).map(&:tags).reduce(TagList.new([]), &:+)
  end
  # ...
end

That last method is worth a second look. Remember that we defined the + operator on TagList to combine two tag lists into one. That comes in handy now, as we are able to use #reduce to very succinctly combine an arbitrary number of tag lists into one master list.

Oh, and if you're wondering about except(:limit), that's a bit of a kludge. In our master layout, in the blog sidebar, we want to show all tags in the database even when only a subset of posts (say, the ten most recent) are currently being shown. except(:limit) simply throws away any LIMIT clause in the current scope, so as to retrieve the tags of all posts in the database.

In order to add tags to posts we need a place to enter them. We add a new field to the "new post" form:

<%= label :tags, "Tags:" %>
<%= f.text_field :tags %>

We also update the blog entry partial to display any tags that are associated with a blog post.

<p class="entry_tags">Tags: 
  <span class="tags"><%= entry.tags %></span>
</p>

Remember that entry.tags will return a TagList, and TagList.to_s is defined to format the tags separated by commas. So this should look fine when rendered.

We also want to show a top-level list of tags that shows all tags in use on the blog. We add a new section to the sidebar in the main application layout:

<!-- ... -->
<h4>Tags</h4>
<nav>
  <ul>
    <%= render partial: "/tags/tag_item",
               collection: @blog.tags %>
  </ul>
</nav>
<!-- ... -->

The tags/tag_item partial is just a thin wrapper around the tags/tag partial:

<li><%= render partial: "/tags/tag", object: tag_item %></li>

The tags/tag partial renders a link to a tag-filtered view of the blog:

<%= link_to tag.to_s, root_path(tag: tag.to_s) %>

To make this work, we make a small addition to the BlogController.

class BlogController < ApplicationController
  def index
    if params[:tag].present?
      @blog = @blog.filter_by_tag(params[:tag])
    end
  end
end

If a :tag parameter is supplied to the index action, it puts a filtered version of the blog into @blog. We define Blog#filter_by_tag as follows:

def filter_by_tag(tag)
  FilteredBlog.new(self, tag)
end

Then we define FilteredBlog as a decorator which wraps the main Blog instance and filters its #entries by a given tag.

class Blog
  # ...
  class FilteredBlog < DelegateClass(Blog)
    include ::Conversions
    def initialize(blog, tag)
      super(blog)
      @tag = tag
    end
    def entries
      Taggable(super).tagged(@tag)
    end
  end
end

This class is an implementation detail of Blog, and will not be used by any other code, so we just nest it inside the Blog class rather than giving it its own file.

Wondering about the DelegateClass(Blog) bit? That's a very close relative to SimpleDelegator, which we've already used. SimpleDelegator is a generic delegator base class which can work when wrapped around any underlying object. DelegateClass(klass), on the other hand, generates a delegator base class customized specifically for wrapping objects of the passed klass. In practice, it doesn't make a huge difference; but delegates based on DelegateClass may be a little more efficient since they don't have to use #method_missing to intercept method calls. There are some other minor differences; for instance, the class DelegateClass() generates responds to .public_instance_methods with a more accurate list than the SimpleDelegator version. Since we know that FilteredBlog will always be wrapping a Blog object, we can use DelegateClass() instead of SimpleDelegator.

At this point, we have a bare-bones but still useful post-tagging functionality. We can add tags to a post, see the keywords a post has been tagged with, and see a list of all tags on the front page. And when we click on one of the tags, we are presented with a subset of posts which are tagged with that keyword.

Filtering by tag

:composed_of enabled us to keep most of the tagging code inside of TagList and out of Post. But there is still a fair amount of tagging-specific code in the Post class. This is troubling for two reasons:

1. Right now it's just tagging. But what about when we add other functionality, like post revision control, or authorization? Will every new feature that we add result in adding another dozen lines of code to Post? What ever happened to the Single Responsibility Principle?
2. What if we decide we want to tag entities other than posts? Will we be duplicating this code for every class that can be tagged?

We might try to pull the tagging "facet" into a module. For each new feature, we could include a new module in Post:

class Post
  include Taggable
  include RevisionControlled
  include Permissible
  # etc...
end

And in fact, this is how many Rails projects address the issue of ever-expanding class files. But does this really address the root problem? We're still adding more and more responsibilities to Post objects. The only difference is, now it's harder to find the definition of any given Post method (or validation, or before-filter…) because it might be in any of a half-dozen different files.

We don't have to spend much time with our new tagging system to realize that our naive implementation is grossly inefficient at scale. To search across or list all tags in the blog, we are forced to load every single blog entry. If this blog engine is going to compete with WordPress it's definitely going to need a faster tags implementation.

We decide to give tags some database tables of their own. In order to keep tags nice and generic, we'll create a tags table which stores the actual tag keyword, and an item_tags table which will polymorphically map from tags to taggable items (such as posts).

We write a migration that creates the new tables, migrates the old tags data to the new tables, and then removes the tags field from the posts table.

class AddTagTables < ActiveRecord::Migration
  class Post < ActiveRecord::Base; end
  class Tag < ActiveRecord::Base; end
  class ItemTag < ActiveRecord::Base
    belongs_to :tag
    belongs_to :item, polymorphic: true
  end
  def self.up
    create_table :tags do |t|
      t.string :name
      t.timestamps
    end
    create_table :item_tags do |t|
      t.integer :item_id
      t.string  :item_type
      t.integer :tag_id
    end
    Post.find_each do |post|
      Array(post.tags).each do |tag|
        tag_record = Tag.create!(name: tag.to_s)
        ItemTag.create!(item: post, tag: tag_record)
      end
    end
    remove_column :posts, :tags
  end
  def self.down
    raise ActiveRecord::IrreversibleMigration, "Cannot be reversed"
  end
end

Note that we define any ActiveRecord models we need for the data migration within the context of the migration. This will enable the migration to continue working even if we change or remove those models in future revisions.

Implementing the Taggable role has been an instructive exercise. I don't know about you, but I learned a lot while writing it.

Looking back over the code we wrote for Taggable, some of it is undeniably awkward. And for an aspect like taggability, which many would consider an intrinsic property of a blog post, it honestly feels like overkill. I think if I were to write a blog engine right now, based on these experiences, I would keep Taggable as an ordinary module and include it into the Post class.

However, I don't think this completely invalidates the technique. There are more truly orthogonal concerns which I think would lend themselves well to this dynamic role-extension approach. As an example, consider adding security to the application. It would be nice if we could write our models without thinking about crosscutting concern of security, and then dynamically extend them with an AccessControlled role at the controller level. Since such a role might well want to intercept ActiveRecord methods like #save, the dynamic module extension technique would be well-suited to it.

The bottom line is this: your classes don't need to grow linearly with your requirements, even if they are your app's "core" classes. It is possible to build up your business objects as composites of small, orthogonal pieces. Whether through decoration, composition, or module extension, you have the power to put a stop to unchecked method creep today, and implement your next feature as a small, focused unit.

Note what we didn't write in the controller:

# ...
@post = exhibit(blog.entries.find_by_id(params[:id]), self)
# ...

This version would have satisfied the "tree of objects" architectural style we're shooting for. But there a couple of problems with it.

For one thing, it taunts the Law of Demeter. It sets up structural coupling between PostsController and Blog. It duplicates the knowledge that Blog has a collection of entries which responds to #find_by_id and returns a Post, thus making that structure just a little bit harder to change.

But another, and perhaps even bigger problem is that it makes it harder for Blog to exercise control over its entries collection.

Imagine a lending library. A lending library has various collections: books, videos, periodicals. The library will allow patrons to use and even borrow the items in its collection; that's it's purpose. But the library doesn't allow them to just take items willy-nilly.

Instead, the library requires patrons to enter during visiting hours. They must register for a library card before borrowing items. They must come to the counter and and present their card before taking an item out of the library. The books they borrow have stickers or perhaps even an RFID tag identifying them as part of the library's collection.

Now imagine the the library as an object. Would the library we've just described prefer that a book to be withdrawn like this?

library.books.find_by_isbn('161293031X')

That's a bit like putting the bookshelf outside the front door of the library and allowing passersby to take books off the shelves as they please.

I suspect the electronic librarians working inside our virtual library would much rather the patrons used an interface like this:

library.borrow_book('161293031X', library_card)

OK, I admit, this is getting to be a pretty stretched-out metaphor. The point is, when client code accesses an object's children through a collection object, rather than directly through the parent object, the parent is no longer the mediator. Remember the advantages we cited earlier of having a parent object mediate access to its children:

1. The ability to control access based on authorization information.
2. The opportunity to pre-load child objects with a reference back to their parent.
3. The opportunity to keep a list of child objects in the parent, for autosave or other purposes.
4. The ability to decide the concrete type of child object to return, or, in this example, what collection(s) to search for the child.

It's not impossible for a parent object to mediate access to its children even with a collection object as a middleman. There are schemes involving proxy objects and callbacks which can enable the parent object to stay "in the loop" with regard to child access.

It's easier and introduces less structural coupling, however, to simply have all child access go through the parent object. That may mean, in some cases, that the parent simply delegates finder methods directly to an underlying collection, as we did in Blog#post(id). But even that simple act of delegation introduces a seam where more involved processing can be introduced later on, with no change to the code's clients.

In short, we prefer to let parent objects mediate access to their children, rather than having clients pick through their collection associations directly.

First of all, having to explicitly exhibit() models inside each view is a drag. To avoid this, we start exhibiting our models at the controller level.

We're actually already doing this in the action for showing a single post:

# app/controllers/posts_controller.rb
# ...
def show
  @post = exhibit(blog.post(params[:id]), self)
  respond_with(@post)
end
# ...

So that's alright. But now that we are using a controller as the context for the exhibited model, instead of a view context, we have a problem: render_body no longer works.

Remember that render_body relies on having a reference to a view template in order to work:

class PicturePostExhibit < Exhibit
  def render_body
    @context.render(partial: "/posts/picture_body", locals: {post: self})
  end
end

Yes, ActionController provides a #render method too, but it's a very different beast from the #render found in views. It expects to be called once per action in order to determine what top-level rendering action to take.

So, we change #render_body to accept a template argument:

# ...
def render_body(template)
  template.render(partial: "/posts/picture_body", locals: {post: self})
end
# ...

And then we explicitly pass in the current view context object in the view:

<article>
  <!-- ... -->
  <%= post.render_body(self) %>
</article>

From now on, we'll use this pattern of explicitly passing in the template object which the exhibit should use to render itself.

Incidentally, this is a classic example of Double Dispatch. Quoting Smalltalk Best Practice Patterns:

How can you code a computation that has many cases, the cross product of two families of classes? […] The solution is adding a layer of messages that get both objects involved in the computation.

In our case, the two families of cases are:

1. The specific Exhibit which might be wrapped around a given model object; and
2. The template object within which the model may be presented.

The first dispatch, the call to #render_body, enables the post body partial to be determined polymorphically. The second dispatch, the call to template.render, farms the specific details of finding and rendering the chosen partial back out to the template object.

It was easy enough to exhibit a single Post object at the controller level. It gets more complicated when we look at rendering multiple blog posts in the context of the front page.

In that context, we can't directly exhibit entries at the controller level, because the controller only supplies a blog object to the view. Then, consistent with our object tree, we access the blog entries via the blog object using the #entries accessor.

We'll have to start at the root of the tree by first exhibiting the blog object itself at the controller level. We alter ApplicationController to always decorate the blog before returning it:

class ApplicationController < ActionController::Base
  include ExhibitsHelper
  # ...
  def blog
    @blog ||= exhibit(THE_BLOG)
  end
  # ...
end

This alone, however, is not quite enough to ensure the blog object is always exhibited. Recall that earlier we made it possible to present only a subset of posts on the blog home page by filtering by tag:

class BlogController < ApplicationController
  # ...
  def blog
    if params[:tag].present?
      super.filter_by_tag(params[:tag])
    else
      super
    end
  end
end

If there's no filter, we get the exhibited blog from ApplicationController#blog, and all is well. If there is a filter, however, we get a raw Blog::FilteredBlog instance - with no exhibit wrapped around it!

The naive solution is to keep calling exhibit() every time we have a new non-exhibited object to deal with:

exhibit(super.filter_by_tag(params[:tag]))

This solution is ugly, verbose, and unsustainable. The more code we write, the more often we'll wind up accidentally leaving out an exhibit() call and introducing a bug.

We need a way to recursively exhibit objects, such that the exhibited object's "children" are automatically exhibited as well..

Our first cut at this problem is to write an explicit wrapper for Blog#filter_by_tag in a brand-new BlogExhibit class:

class BlogExhibit < Exhibit
  # ...
  def filter_by_tag(*)
    exhibit(super)
  end
end

This method simply calls the underlying model's #filter_by_tag method and then wraps the result in a call to exhibit() before returning it.

We know we're going to need this for more than Blog#filter_by_tag. So once we are confident this works, we extract it to a "macro" method:

class Exhibit
  # ...
  def self.exhibit_query(*method_names)
    method_names.each do |name|
      define_method(name) do |*args, &block|
        exhibit(super(*args, &block))
      end
    end
  end
  private_class_method :exhibit_query
  # ...
end

We call the macro exhibit_query. "Query", in this case, is used in the sense of "command/query separation". It refers to a method whose purpose is to return an object, rather than to effect some change in the system state. exhibit_query advises such methods such that their return value will be wrapped in the appropriate exhibit(s) (if any).

We then replace our explicit version in BlogExhibit with a call to the new macro:

class BlogExhibit < Exhibit
  # ...
  exhibit_query :filter_by_tag
end

We finish out our new BlogExhibit with a predicate to determine if it is applicable.

class BlogExhibit < Exhibit
  def self.applicable_to?(object)
    object_is_any_of?(object, 'Blog', 'Blog::FilteredBlog')
  end
  # ...
end

This definition makes use of a new Exhibit.object_is_any_of? helper to match on any of a list of class names. Here's the the definition of Exhibit.object_is_any_of?:

def self.object_is_any_of?(object, *classes)
  # What with Rails development mode reloading making class matching
  # unreliable, plus wanting to avoid adding dependencies to
  # external class definitions if we can avoid it, we just match
  # against class/module name strings rather than the actual class
  # objects.
  # Note that '&' is the set intersection operator for Arrays. 
  (classes.map(&:to_s) & object.class.ancestors.map(&:name)).any?
end
private_class_method :object_is_any_of?

Note that we made both this method and the exhibit_query "macro" private with private_class_method. Since they are both intended exclusively for use inside exhibit class definitions, there is no reason to clutter up the class' external interface with them.

Let's circle back and remind ourselves what we're trying to accomplish right now. Inside the template for the Blog#index action we'd like to be able to write something like this:

<!-- ... -->
<%= render partial: "/posts/post", collection: blog.entries %>
<!-- ... -->

So far, we've been trying to find a way for the exhibited blog object to recursively confer exhibited status on its children, the blog entries.

We have the first part of the puzzle now. In order for blog.entries to also be exhibited, we need to make it an "exhibited query" just as we did with Blog#filter_by_tag.

class BlogExhibit < Exhibit
  # ...
  exhibit_query :filter_by_tag, :entries
end

Is this all we need to do? Alas, no. The return value of Blog#entries is a collection (an ActiveRecord::Relation instance, if you really want to know). We've made sure that the collection itself will go through the exhibiting process; but the individual elements of the collection will still come back as bare, unadorned Post objects. Objects which have no idea what to do when someone sends them the #render_body message.

What we need is a type of Exhibit which will wrap a collection, and ensure that any elements accessed from within the collection will also be exhibited.

We begin to spec out an EnumerableExhibit class, using Ruby's Enumerable, Array, and Hash classes as a guideline for what methods a collection exhibit should be expected to handle.

Here's a sample of the spec:

describe EnumerableExhibit do
  # ...
  subject { EnumerableExhibit.new(model, context) }
  let(:model) { ["e1", "e2", "e3"] }
  let(:context) { Object.new }

  before do
    # #exhibit is part of the superclass interface, not this class'
    # interface, so it is fair game for stubbing
    stub(subject).exhibit {|model|
      @last_exhibited = model
      "exhibit(#{model})"
    }
  end

  describe "#each" do
    it "exhibits each element" do
      results = []
      subject.each do |e| results << e end
      results.must_equal(["exhibit(e1)", "exhibit(e2)", "exhibit(e3)"])
    end
  end

  # ...

  describe "#grep" do
    it "exhibits the result set" do
      subject.grep(/[12]/).must_equal('exhibit(["e1", "e2"])')
    end
  end

  describe "#select" do
    it "exhibits each result" do
      subject.select{|e| /[23]/ === e}.must_equal('exhibit(["e2", "e3"])')
    end
  end

  # ...

  describe "#[]" do
    it "exhibits the result" do
      subject[1].must_equal("exhibit(e2)")
    end
  end

  # ...

  describe "#group_by" do
    it "exhibits the result" do
      subject.group_by{|e| e == "e2"}.
        must_equal({ true  => 'exhibit(["e2"])',
                     false => 'exhibit(["e1", "e3"])'})
    end
  end

  # ...
end

This is just a small subset of the full spec; we want to be very careful to avoid surprises with this class, so we carefully spec out the behavior of every common, and some not-so-common, Enumerable and Array method, as well as one or two methods from ActiveRecord::Relation.

For some of the methods, getting the desired behavior is as simple as making the EnumerableExhibit Enumerable itself, and defining #each.

class EnumerableExhibit < Exhibit
  include Enumerable
  # ...
  def each(*)
    super do |e|
      yield exhibit(e)
    end
  end
  # ...
end

We implement #each to wrap each element in exhibit() before yielding. Because they are implemented in terms of #each, methods like #map and #inject will now work exactly as expected, also wrapping each element in exhibit() before returning them.

Other accessor methods which return single elements, such as #[] and #fetch, we are able to quickly add using our handy exhibit_query macro.

class EnumerableExhibit < Exhibit
  # ...
  exhibit_query :[], :fetch
  # ...
end

However, there is another set of methods which are not so straightforward. As an example, consider Enumerable#select, aka Enumerable#find_all. This method takes a one-argument block and returns all elements for which the block evaluates to true.

At first, it seems like we could just rely on the free implementation of #select that we get from Enumerable. And indeed, there's nothing broken about this version. Each matching element (if any) will be wrapped in appropriate exhibits.

The problem is that "filter" methods like select are often used as part of chains of calls, each link in the chain winnowing down and/or transforming the elements until the desired result set is reached. And it really doesn't make sense to be wrapping exhibits around every single element at intermediate points in the chain. In addition, for some types of filter chains, having the individual elements wrapped in exhibits may mess up the filter logic in non-obvious ways. What we really want is to leave the individual elements yielded to the #select's block to be "pristine", and for the method to return a new EnumerableExhibit which is wrapped around the result set.

In order to achieve this behavior, we write another macro along the lines of exhibit_query, this time called exhibit_enum. The job of exhibit_enum is to wrap an underlying collection method such that:

1. It has "stock" block behavior - no wrapping elements in exhibit() before yielding them to the block.
2. The return value is run through the exhibiting process in order to wrap the result set in a new EnumerableExhibit result set.
3. Optionally, the return value is post-processed with a custom block to account for more complex result formats.

Here's the macro:

class EnumerableExhibit < Exhibit
  # ...
  def self.exhibit_enum(*method_names, &post_process)
    post_process ||= ->(result){exhibit(result)}
    method_names.each do |method_name|
      define_method(method_name) do |*args, &block|
        result = __getobj__.public_send(method_name, *args, &block)
        instance_exec(result, &post_process)
      end
    end
  end
  private_class_method :exhibit_enum
  # ...
end

We then list out the methods to be wrapped in this fashion.

class EnumerableExhibit < Exhibit
  # ...
  exhibit_enum :select, :grep, :reject, :to_enum, :sort, :sort_by, :reverse
  # ...
end

As noted above, a few methods require special post-processing for the return value. For example, Enumerable#partition returns an array of arrays instead of a simple array. We handle these cases separately:

class EnumerableExhibit < Exhibit
  # ...
  exhibit_enum :partition do |result|
    result.map{|group| exhibit(group)}
  end
  # ...
end

Here's the source of the complete EnumerableExhibit class.

require_relative 'exhibit'

class EnumerableExhibit < Exhibit
  include Enumerable

  def self.applicable_to?(object)
    # ActiveRecord::Relation, surprisingly, is not Enumerable. But it
    # behaves sufficiently similarly for our purposes.
    object_is_any_of?(object, 'Enumerable', 'ActiveRecord::Relation')
  end

  # Wrap an Enumerable method which returns another collection
  def self.exhibit_enum(*method_names, &post_process)
    post_process ||= ->(result){exhibit(result)}
    method_names.each do |method_name|
      define_method(method_name) do |*args, &block|
        result = __getobj__.public_send(method_name, *args, &block)
        instance_exec(result, &post_process)
      end
    end
  end
  private_class_method :exhibit_enum

  exhibit_query :[], :fetch, :slice, :values_at, :last
  exhibit_enum :select, :grep, :reject, :to_enum, :sort, :sort_by, :reverse
  exhibit_enum :partition do |result|
    result.map{|group| exhibit(group)}
  end
  exhibit_enum :group_by do |result|
    result.inject({}) { |h,(k,v)|
      h.merge!(k => exhibit(v))
    }
  end

  def each(*)
    super do |e|
      yield exhibit(e)
    end
  end

  # `render '...', :collection => self` will call #to_ary on this
  # before rendering, so we need to be prepared.
  def to_ary
    self
  end
end

It's taken some effort, but we've got some pretty nifty functionality on our hands now. Given a line of code like the following:

entry = exhibit(blog).entries.first

The "exhibited" nature of blog will be conferred upon entries, and then upon the chosen entry. Each object in the chain will be transparently wrapped in the appropriate Exhibit objects (if any). In effect, we've made the "exhibited" property transitive from parent objects to children.

This template code now works:

<!-- ... -->
<%= render partial: "/posts/post", collection: blog.entries %>
<!-- ... -->

What this means is that we can now be confident that no matter where the /posts/post partial is rendered, either on a single-post page or as part of the front-page index, its post local will refer to an exhibited object. We can safely call post.render_body(self) and know that the right body partial will be rendered.

When we look at the code to render a post body:

<article>
  <!-- ... -->
  <%= post.render_body(self) %>
</article>

…a question naturally springs to mind. If we can tell an exhibited Post to render its body… why not tell it to render the whole post the same way? Making this work will be our next task.

It turns out to be fairly straightforward. First, we add a a method #to_partial_path to Exhibit. This method's job is to return an appropriate partial path (as in render partial: path) for the exhibited model.

class Exhibit < SimpleDelegator
  # ...
  def to_partial_path
    if __getobj__.respond_to?(:to_partial_path)
      __getobj__.to_partial_path
    else
      partialize_name(__getobj__.class.name)
    end
  end
  # ...
end

We first check to see if the underlying model has its own idea of what partial should be used. We do this because as of Rails 3.2, #to_partial_path is a part of the ActiveModel API. If a model implements the method, we want to defer to it by default.

Otherwise, we munge the model's class name into a partial path using a helper method #partialize_name. That method is defined as follows:

class Exhibit < SimpleDelegator
  private
  # ...
  def partialize_name(name)
    "/#{name.underscore.pluralize}/#{name.demodulize.underscore}"
  end
  # ...
end

Given the class name "Post", this will return "/posts/post", which is exactly what we want.

Now that we know the name of the partial to render, the #render method itself is trivial.

class Exhibit < SimpleDelegator
  # ...
  def render(template)
    template.render(:partial => to_partial_path, :object => self)
  end
  # ...
end

We can now use this in app/views/posts/show.html.erb to render the post object:

<%= post.render(self) %>

OK, that's cool, but can we use the same thing for rendering a list of posts? Like, say, on the blog front page?

Not quite yet. Here's what we'd like to write:

<!-- ... -->
<%= blog.entries.render(self) %>

We know we can tell an exhibited Post to render itself, but here we're rendering a collection of posts.

Hm, "collection"… didn't we just finish writing an exhibit class for collections? And doesn't it now inherit #render from Exhibit?

It does indeed, but if we try the code above right now, it tries to render the collection of posts with a partial named /active_record/relation, and fails when it can't find that partial. Let's customize EnumerableExhibit to do something a little smarter.

class EnumerableExhibit < Exhibit
  # ...
  def render(template)
    inject(ActiveSupport::SafeBuffer.new) { |output,element|
      output << element.render(template)
    }
  end
  # ...
end

Instead of rendering a partial, this version of #render iterates over the elements of the underlying collection, rendering each one and appending the results to a buffer. Remember that #inject is implemented in terms of our #each method, which exhibits the elements before yielding them. We use an ActiveSupport::SafeBuffer instead of a String so that Rails will render the resulting string as raw HTML instead of escaping it.

Once we upgrade to Rails 3.2 we'll probably be able to switch this to use a simple render self and rely on Rails to ask each item for a partial path using #to_partial_path. But for right now this works well enough.

Now we can write this:

<!-- ... -->
<%= blog.entries.render(self) %>

And it renders blog posts to the front page.

Back at the beginning of this chapter, we said we'd like to be able to write the following code as part of our app/views/posts/_post.html.erb partial:

<!-- ... -->
<div class="entry_tags">Tags: 
  <%= post.tags.render(self) %>
</div>
<!-- ... -->

The first step to making this work the way we want is to make sure the tags collection gets exhibited. Which means we first need to make the tags collection accessible in the first place. Remember, #tags is added by the Taggable wrapper, it's not an intrinsic feature of Post.

We'll kill to birds with one stone:

class PostExhibit < Exhibit
  # ...
  def tags
    exhibit(Taggable(to_model).tags)
  end
  # ...
end

Calling #tags on an exhibited Post now gets us the exhibited TagList associated with that post.

TagList is Enumerable, so it will have EnumerableExhibit added to it. Unfortunately, this doesn't give us quite what we need. EnumerableExhibit works well for rendering collections of render-able objects. But the tags in TagList are just strings, and we don't have a StringExhibit. Nor are we sure we want one.

Instead, we'll create a dirt-simple TagListExhibit.

# app/exhibits/tag_list_exhibit.rb
class TagListExhibit < Exhibit
  def self.applicable_to?(object)
    object_is_any_of?(object, 'TagList')
  end
end

Wait a sec… that doesn't actually do anything, does it? In fact, we don't need it to do much. So long as it comes after EnumerableExhibit in the list of exhibits, it will override that exhibit's #render by dint of being the "outermost" exhibit. Which means it will use the default Exhibit#render, which means it will look for a partial named /tag_lists/tag_list. Which we then dutifully provide:

<!-- app/views/tag_lists/_tag_list.html.erb -->
<ul class="tags">
  <%= render partial: "/tags/tag_item", collection: tag_list %>
</ul>

The /tags/tag_item, as you may recall from earlier, renders /tags/tag inside an <LI> tag, and /tags/tag renders the tag as a link to all tagged posts.

<!-- app/views/tags/_tag_item.html.erb -->
<li><%= render partial: "/tags/tag", object: tag_item %></li>

<!-- app/views/tags/_tag.html.erb -->
<%= link_to tag.to_s, root_path(tag: tag.to_s) %>

Now anywhere we exhibit a TagList, we can tell it to #render itself and it will generate an unordered list. With a little CSS (not shown) we can make this work anywhere we show a list of tags.

We opened this chapter with some code showing how we would like to write the /posts/post template. Let's take a look at it again, alongside the original template, now that we've done the work to make the new version render successfully.

<!-- old -->
<% entry = exhibit(entry, self) %>
<article>
  <header>
    <p><time pubdate="pubdate"><%= entry.pubdate %></time></p>
    <h3><%= entry.title %></h3>
    <p class="entry_tags">Tags: 
      <span class="tags"><%= Taggable(entry).tags %></span>
    </p>
  </header>
  <%= entry.render_body %>
</article>

<!-- new -->
<article>
  <header>
    <p><time pubdate="pubdate"><%= post.pubdate %></time></p>
    <h3><%= post.title %></h3>
    <div class="entry_tags">Tags: 
      <%= post.tags.render(self) %>
    </div>
  </header>
  <%= post.render_body(self) %>
</article>

Let's also take a look at the revised /blog/index template within which this template is rendered.

<!-- app/views/blog/index.html.erb -->
<h1><%= blog.title %></h1>
<h2 class="tagline"><%= blog.subtitle %></h2>
<%= blog.entries.render(self) %>

Let's recap what we did:

1. We moved exhibiting of the post and blog object into their respective controllers. No more cluttering up templates with calls to exhibit().
2. By making "exhibited-ness" transitive, and making collections such as ActiveRecord::Relation exhibit-able, we made it possible to render the collection of blog entries with a straightforward:

   blog.entries.render(self)
   
   

3. We extracted the wrapping of the post object with Taggable() into the post exhibit object.
4. We made TagList exhibit-able, making the rendering of a list of tags have the exact same form as the rendering of the list of blog entries: post.tags.render(self).

With these changes, we've taken a big step towards a "component", or "widget" style of page rendering. By enabling objects in the template to render themselves to the page, we've engaged the full power of polymorphism. We've introduced a significantly greater degree of flexibility to vary what is shown, how it is shown, and where it is shown independently.

But we've still respected many Rails conventions. We still look for view templates in the conventional places. We still use the plain vanilla Rails RHTML views, along with the standard tag helpers, to take care of the actual rendering of HTML tags to the browser. We still follow the standard Rails workflow of: set up an object in the controller, then render its attributes in a template.

In short, as with the other parts of this text we've tried to find a middle way. A little more decoupled and flexible than vanilla Rails style, but still close enough that someone new to the project could learn their way around within a few days.

Pain don't hurt.

—Dalton, in "Roadhouse"

A lot of the patterns we've looked at have been significantly more work than following the traditional Rails development process. For instance, we went to an awful lot of effort to avoid exposing common ActiveRecord methods on the Post class.

Is all this extra effort worth it? Well, that really depends on the application. In some ways a blog app was a terrible choice for demonstrating these techniques, since if there's one type of app the rails "golden path" is well suited for, it's a blog. I chose a blog application as the demo because I wanted to go with a problem domain anyone would be familiar with, so as to put the focus on the coding strategies rather than the problem domain. As a result, a lot of those strategies felt like overkill in this context.

But in my experience there are a lot of more complex Rails projects out there which could have benefited from a little more "pain" in the form of careful design decisions. Many of these pain points are really canaries in a coal mine, letting us know that our code is becoming overly coupled, our interfaces too large, our objects saddled with too many responsibilities. Like muscles which have sat too long in one position, we don't realize how knotted-up they've become until we stand up and stretch. Disciplines like isolated tests, or FigLeaf, keep us on our toes and keep those muscles from knotting up in the first place.

I want to be clear that the techniques I've demonstrated here aren't "the Right Way" to do Rails; or even necessarily "the Avdi Grimm Way". More than showing you a set of patterns and practices, what I hope you'll take away from this is that Rails is not a set of rigid walls confining your project. Your project is not a Rails project; it is a software project, which uses Rails to satisfy the need of projecting your business objects onto the web. Rails is not the framework; it is a part of your overall project architecture.

As a project scales, its architecture must evolve and grow to support it. That may mean building new abstractions upon the foundation Rails gives you. This should not be a cause for consternation and fear, but a cause for excitement! One, because your project is successful enough to need new abstractions to support its continued evolution. Two, because you're working in Ruby and Rails, and it's all just objects, all the way down.

So don't be afraid to build up your project's architecture. And in the process, don't be shy about lifting idioms and patterns from the Object-Oriented literature. There is very little new under the sun; whatever the problem you are facing, chances are Kent Beck already solved it in Smalltalk. Ruby didn't invent OO, it just made it ten times more fun. Likewise Rails didn't invent web programming patterns, it just stripped away all the ceremony and boilerplate.

It's been a ton of work but a lot of fun writing this; I hope you get some value from it. If you have questions, corrections, suggestions, or objections, please don't hesitate to get in touch. I'm always interested in seeing how other developers tackle the problems of sustainably growing and evolving a codebase.

Thanks for reading, and happy hacking!

• The definitive compilation of web application patterns, and the source of many of the patterns found in Rails, is Patterns of Enterprise Application Architecture, by Martin Fowler. Every web application developer should have a copy of this book within easy reach.
• No object-oriented programming book list is complete without Kent Beck's Smalltalk Best Practice Patterns. Cleverly disguised as a book about Smalltalk, this book is really a comprehensive manual for constructing elegant, expressive code in any OO language.
• Steven Baker is writing an eBook on applying SOLID principles to Rails code, called Solid Rails.
• Steve Klabnick wrote an article called "The Secret to Rails OO Design"
• In September 2011 The Ruby Rogues podcast (of which I am a member) interviewed Jim Weirich on the topic of "Object Oriented Programming with Rails".
• My fellow CodeBender Piotr Solnica has written on the topic of "Making ActiveRecord Models Thin".
• Gary Bernhardt has been offering up a wealth of information on clean OO design and writing fast, isolated tests in his Destroy All Software video series.
• Greg Brown has been writing some great stuff on this topic; for instance, here's an article on applying SOLID Design Principles to Ruby code based on his experience writing the Prawn PDF library.
• Nicholas Henry: "Rails is Not Your Application".
• Dan Croak wrote a comprehensive overview of Decorator implementations in Ruby
• Nick Gauthier gave a presentation on "Ruby and the Web" in February 2012 at B'More on Rails. In it, he talks about how Rails is actually closer to a Model 2 architecture than to Model-View-Controller. He also explores what a more deliberately Object-Oriented web framework in Ruby might look like.
• Gary Bernhard has an alternative take on a Ruby web framework called Raptor. Quoting the README: "Raptor is an experimental web framework that encourages simple, decoupled objects. There are no base classes and as little 'DSL' as possible."

• Greg Moeck explains why stubs are not enough. I also really enjoyed his RubyConf 2011 presentation "Why You Don't Get Mock Objects".
• Corey Haines has been giving talks on fast Rails tests.

A number of Rails practitioners have begun exploring the application of the Data-Context-Interaction (DCI) pattern to Rails apps. DCI is the brainchild of the same people who came up with MVC, and offers some novel techniques for breaking down functionality along use-case boundaries. Here are some reading suggestions to get you started learning about DCI.

• An article by the inventors of DCI laying out the foundations of the pattern.
• Jim Gay is writing a book on using DCI in Ruby and Rails. I've seen Jim present on this topic and he's at the forefront of applying this approach to Rails projects. I'm eagerly looking forward to reading his book.
• Andrzej Krzywda has a great intro post on DCI and Rails.
• Mike Pack: The right way to code DCI in Ruby.

• Jay Fields:
  • Model View Controller + Presenter? - the post that first introduced the Presenter concept.
  • Another Presenter Example
  • Presenters - An Additional layer example.
  • Presenter Pattern - a formalization of the pattern.
  • Rise, Fall, and Potential Rebirth of the Presenter Pattern. A retrospective look at the experiences Jay and others had applying Presenters to various projects.
• Courtenay Gasking: Simple Presenters.
• Zach Dennis: The Exceptional Presenter.
• Dmytro Shteflyuk: Simplifying your Ruby on Rails code: Presenter pattern, cells plugin.
• Steve Klabnick: Better Ruby Presenters. A follow-up to The Secret to Rails OO Design, referenced earlier.
• Jeff Casimir: Blow Up Your Views. Jeff encoded the concepts introduced in this presentation in his Draper gem.
• Martin Fowler summarizes GUI patterns. Note: this article is more concerned with rich client-side GUI patterns than web GUIs.
• Model View ViewModel. A pattern from the .NET/Silverlight world.

• Effigy replaces your view templates with honest-to-goodness objects. Among other interesting implications, this means that instead of layouts you simply have a base class which defines boilerplate HTML, and then individual view subclasses override the parts of the base which they wish to customize.
• decent_exposure enables you to decoratively set up your controller interfaces, and enforces the use of those interfaces.
• Apotomo is a view component framework for Rails.
• The Two-Step View pattern from Patterns of Enterprise Application Architecture is a robust pattern for decoupling models from views.

• Rails 3 took massive strides towards being a modular framework which allows you to mix and match pieces, or swap in your own pieces when the stock ones aren't sufficient for your app. For understanding how the Rails puzzle fits together, and how to hook your own code into it, there is no better guide than Crafting Rails Applications, by José Valim.

Consider an adventure game, with objects representing player characters.

class Character
  # ...
end

A Character can be described:

class Character
  # ...

  # ...
end

A Character can look, listen, and smell his environment:

class Character
  # ...

  # ...
end

<<definitions>>
cohen = Character.new
cohen.describe
cohen.look
cohen.listen

The character can also consult all of his senses at once:

class Character
  # ...

  # ...
end

<<definitions>>
cohen = Character.new
cohen.observe

Characters can have various effects conferred upon them by items, potions, etc. A simple example is a hat:

require 'delegate'
class BowlerHatDecorator < SimpleDelegator
  def describe
    super
    puts "A jaunty bowler cap sits atop your head."
  end
end

At each turn of the game, the Character object will be decorated with whatever effects are currently active, and then a user command will be performed:

<<definitions>>
cohen = BowlerHatDecorator.new(Character.new)
cohen.describe

You are a dashing, rugged adventurer.
A jaunty bowler cap sits atop your head.

A more interesting effect is conferred by an infravision potion. It enables your character to see in the dark.

class InfravisionPotionDecorator < SimpleDelegator
  def describe
    super
    puts "Your eyes glow dull red."
  end

  def look
    super
    look_infrared
  end

  def look_infrared
    list("You can see", ["the ravenous bugblatter beast of traal"])
  end
end

While the character is experiencing the effects of an infravision potion, his powers of observation increase:

<<definitions>>
cohen = InfravisionPotionDecorator.new(Character.new)
cohen.describe
cohen.look

You are a dashing, rugged adventurer.
Your eyes glow dull red.
You can see a lightning bug.
You can see a guttering candle.
You can see the ravenous bugblatter beast of traal.

There's just one little problem that crops up when the #observe method is called.

<<definitions>>
cohen = InfravisionPotionDecorator.new(Character.new)
cohen.observe

You can see a lightning bug.
You can see a guttering candle.
You hear a distant waterfall.
You smell egg salad.

Hey, where'd that bugblatter beast go?

The Character#observe method calls #look—but since the wrapped object has no knowledge whatsoever of the InfravisionPotionDecorator, it calls the original definition of #look, not the one which also calls #look_infrared.

Now, granted, this flaw actually works out in our intrepid adventurer's favor, since the ravenous bugblatter beast of Traal is so stupid it thinks that if you can't see it, it can't see you. But never mind that: it's still a bug, and bugs must be blattered.

We could patch this flaw by overriding #observe as well in the decorator:

class InfravisionPotionDecorator < SimpleDelegator
  def observe
    look
    listen
    smell
  end
end

Yuck! This is the exact same implementation as in Character, just copied and pasted so that the correct implementation of #look will be called. Clearly this is non-DRY. But even worse, we've introduced a nasty variety of connascence. Every time we introduces a new Character method which calls #look, we'll have to cull through every single effect decorator which overrides #look, adding copy-and-pasted versions of the new method so that it doesn't accidentally ignore the effect-wrapped version. Double yuck!

In Ruby, there is an easy solution: extend the character with a module instead of a decorator.

module InfravisionPotionModule
  def describe
    super
    puts "Your eyes glow dull red."
  end

  def look
    super
    look_infrared
  end

  def look_infrared
    list("You can see", ["the ravenous bugblatter beast of traal"])
  end
end

<<definitions>>
cohen = Character.new.extend(InfravisionPotionModule)
cohen.observe

This time the overridden method is added directly to the object via its singleton class. So even the object's own unmodified methods get the new infravision version of #look.

Sadly, by enabling him to see the monster we have sealed our protagonist's fate. But at least we fixed the bug!

That's not the only way to fix the problem. We might, for instance, decompose our Character into individual body parts, with separate attributes for eyes, nose, and ears. The Character could then delegate the individual senses to their respective organs:

require 'forwardable'
class Character
  extend Forwardable

  attr_accessor :eyes
  attr_accessor :ears
  attr_accessor :nose

  def_delegator :eyes, :look
  def_delegator :ears, :listen
  def_delegator :nose, :smell
end

A potion of infravision might then replace the character's eyes with infrared-enhanced ones:

class InfravisionPotionDecorator < SimpleDelegator
  class EyesDecorator < SimpleDelegator
    # ...
  end

  def initialize(character)
    super(character)
    character.eyes = EyesDecorator.new(character.eyes)
  end
end

…but this is an awful lot of code and ceremony. It might make sense someday, but right now it feels like massive overkill. The module extension approach, by contrast, is only a small change from our original version.

So what can we learn from this? When composing objects, Is it always better to use module extension than decoration?

In a word, no. For one thing, decoration is a simpler structure to understand. Given object A wrapped in object B wrapped in object C, it's easy to reason about how method calls will be handled. They'll always go one-way: a method in object A will never reference a method in B or C.By contrast, method calls in a module-extended object can bounce around the inheritance hierarchy in unexpected ways.

A second consideration is that once you've extended an object with a module, its behavior is changed for all clients, including itself. You can't interact with the "unadorned" object anymore. You might extend an object for your own purposes, then pass it to a third-party method which doesn't understand the modified behavior of the object and barfs as a result.

Finally, there's a performance penalty. While it varies from implementation to implementation, dynamically extending objects can slow down your code as a result of the method cache being invalidated. Of course, as with all performance-related guidelines, be sure to profile before making any code changes based on this point.

Decoration and module extension are both viable ways to compose objects in Ruby. Which to use is not a simple black-or-white choice; it depends on the purpose of the composition.

For applications where you want to adorn an object with some extra functionality, or modify how it presents itself, a decorator is probably the best bet. Decorators are great for creating Presenters, where we just want to change an object's "face" in a specific context.

On the other hand, when building up a composite object at runtime object out of individual "aspects" or "facets", module extension may make more sense. Judicious use of module extension can lead to a kind of "emergent behavior" which is hard to replicate with decoration or delegation.

The purpose of this file is to supply the prerequisites for purely isolated model tests, without burdening the tests with excessive startup time. Notably, it eschews both the Rails environment and Bundler setup, which means that any needed gems must be explicitly required. It also means the tests must be run in an environment where the correct gem versions are available, e.g. in the context of an RVM gemset which has been initialized using bundle install.

Minitest is explicitly specified with gem, in order to get the newer gem version of Minitest instead of the one that comes with Ruby.

RR ("Double Ruby") is also required, for mocking and stubbing.

Finally, this is the file which defines stub_module and stub_class, which enable us to stub out references to other classes and modules without actually loading the code for them.

ENV['RAILS_ENV'] ||= 'test'
gem 'minitest' # demand gem version
require 'minitest/autorun'
require 'rr'
require 'ostruct'
$: << File.expand_path('../lib', File.dirname(__FILE__))
class MiniTest::Unit::TestCase
  include RR::Adapters::MiniTest
end
def stub_module(full_name, &block)
  stub_class_or_module(full_name, Module)
end
def stub_class(full_name, &block)
  stub_class_or_module(full_name, Class)
end
def stub_class_or_module(full_name, kind, &block)
  full_name.to_s.split(/::/).inject(Object) do |context, name|
    begin
      # Give autoloading an opportunity to work
      context.const_get(name)
    rescue NameError
      # Defer substitution of a stub module/class to the last possible
      # moment by overloading const_missing. We use a module here so
      # we can "stack" const_missing definitions for various
      # constants.
      mod = Module.new do
        define_method(:const_missing) do |missing_const_name|
          if missing_const_name.to_s == name.to_s
            value = kind.new
            const_set(name, value)
            value
          else
            super(missing_const_name)
          end
        end
      end
      context.extend(mod)
    end
  end
end

This file builds on spec_helper_lite.rb and adds NullDB helpers for stubbing out database interactions. It was originally part of spec_helper_lite.rb, but I separated it out to its own file when I removed Bundler setup from spec_helper_lite.rb.

require "bundler/setup"
require_relative 'spec_helper_lite'
module SpecHelpers
  def setup_nulldb
    require 'nulldb'
    schema_path = File.expand_path('../db/schema.rb', File.dirname(__FILE__))
    NullDB.nullify(:schema => schema_path)
  end
  def teardown_nulldb
    NullDB.restore
  end
end

This file adds the full Rails environment to the setup already done in spec_helper_lite.rb. It also sets up DatabaseCleaner for integration tests.

require_relative 'spec_helper_lite'
require_relative '../config/environment.rb'
module SpecHelpers
  def setup_database
    DatabaseCleaner.strategy = :transaction
    DatabaseCleaner.clean_with(:truncation)
    DatabaseCleaner.start
  end
  def teardown_database
    DatabaseCleaner.clean
  end
end