DRYing up your views with a TableBuilder

In the last two months, when I was adding more features to mobtropolis, I found it painful to try and lay things out all over again from scratch. As a result, it sucked to see ugly layouts on the new pages juxtaposed with all the styling I had done before. It wasn't until a week ago that I said to myself, "Stop the madness!" and started refactoring my views--something I never thought of doing much of until now. When you don't, the barrage of angle brackets blows out of proportion and it starts to look pretty damn fugly with complex views.

What I should be able to do is take common mini-layouts in my views and make them available as helpers so that I can think in terms of bigger chunks to piece together pages, rather than in divs and spans. In addition, it makes your interface more consistent for your users.

Some good resources were presentations from the 2007 RailsConf, like V is for Vexing and Keeping your views DRY. While a lot of view DRYing talks about form builders, I didn't see any on table builders, so I decided to take a stab at it. Personally, I don't like to overuse tables for layouts. But as certain elements in my page layouts have been repeated, I refactored them into first helpers, and then when I did more than one, I extracted it out into a simple table builder. This is how you'd use it:

For example, I have a mini-layout where I show simple stats:


Here's how I used a simple table builder to display the above:

<% score_card do |sc| -%>
  <% sc.placard("Votes", "", num_voters, "") -%>
  <% sc.placard("Sceneshots", "", num_sceneshots, "")-%>
  <% sc.placard("Participants", "", num_participants, "") -%>
  <% sc.placard("Challenges","", num_challenges, "") -%>
<%  end -%>

And I find that I started using the same sort of thing in other places, like in a user's profile:

<% score_card do |sc| -%>
  <% sc.placard("Submitted Scenes", "", num_scenes, "") -%>
  <% sc.placard("Submitted Sceneshots", "", num_sceneshots, "") -%>
<% end -%>

I cut out some details so you can see that it's just a block that gets passed a ScoreCard object, from which you call placard to add another score to the score_card. It sure beats writing <table> and <td> over and over again.

To declare the helper, we create a helper with the structure of the table inside the declaration of a ScoreCard object. We have a ScoreCard object to hold the contents of the placards. When they're called in the block above in the template, they get stored in the ScoreCard object, and not written out to erb immediately. That way, we can place them wherever in the table we please, by making the call to card.display(:placards):

module ScorecardHelper
 def score_card(html_options = {}, &block)
    options = { :class => :scorecard, :width => "100%" }.merge(html_options)
    ScoreCard.new(block) do |xm, card|
      xm.table(options) do
        xm.tr(:valign => :top) do
          xm << card.display(:placards)
        end
      end
    end
  end
end

So then what's ScoreCard look like? Pretty simple. It has a call to each cell that can be filled in the mini-layout. It's kinda analogous to how form_for passes in a form object, on which you can call text_field, etc.

require 'lib/table_builder'

# Used to create a scorecard helper
class ScoreCard < TableBuilder
  cells :placards

  # a placard is placed into scorecards
  def placard(text, text_id, score, widget)
    xm = Builder::XmlMarkup.new
    @placards[:html] += xm.td do
      xm.span(:style => "font-size: 1.2em") { xm << "#{text}" }
      xm.em(:id => text_id, :class => "primary_number") { xm << "#{score}" }
      xm << "#{widget}"
    end
  end

end

Notice that there's a call to cells() to initialize the type of cell, and a method of the same name that builds the html for that cell. If you have other types of cells, you simply put it in the list of cells, and then create a method for it that is called in the template. By convention, you'd stick the html of the cell contents in "@#{name_of_cell}"[:html], and if you wanted, pass in the html_options, and stick it in "@#{name_of_cell}"[:options]. Then, you can access those in the helper wherever you want.

Let's try another one. I have a mini_layout with a picture, and some caption underneath it, like a polaroid.

<% polaroid_card do |p_card| -%>
  <% p_card.picture do -%>
    <%= sceneshot_for scene -%>
  <% end -%>
  <% p_card.caption do -%>
    <%= pluralize(scene.num_of_sceneshots, "sceneshot") %>
  <% end -%>
<% end -%>

The associated helper and PolaroidCard object are pretty simple:

module PolaroidCardHelper
  # a polaroid card is used to show a picture with a caption below it.
  def polaroid_card(html_options = {}, &block)
    options = { :class => :polaroidcard, :style => "display: inline;" }
    PolaroidCard.new(block) do |xm, card|
      xm.table(options) do 
        xm.tr { xm.td(card.html_options(:picture)) {
            xm << card.display(:picture)
          }}
        xm.tr { xm.td(card.html_options(:caption).merge(:class => "caption")) {
            xm << card.display(:caption)
          }}
      end
    end
  end
end

require 'lib/table_builder'

class PolaroidCard < TableBuilder
  cells :picture, :caption

  def picture(html_options = {}, &block)
    @picture[:html] = capture(&block)
    @picture[:options] = html_options
  end

  def caption(html_options = {}, &block)
    @caption[:html] = capture(&block)
    @caption[:options] = html_options
  end
end

I've tried to pull all the plumbing out into TableBuilder (dropped it into lib/), and only leave the flexibility of creating the table structure in the helper, and the format of the cell in the object. It ends up TableBuilder isn't too complex either. It uses some metaprogramming to create some instance variables. I know it pollutes the object instance variable namespace, but I wanted to be able to say @caption[:html], rather than @cells[:caption][:html].

class TableBuilder < ActionView::Base
  class << self
    # used in the child class declaration to name and initialize cells
    def cells(*names)
      define_method(:initialize_cells) do 
        @cell_names = names.map { |n| "@#{n}".to_sym }
        @cell_names.each do |name| 
          if instance_variable_defined?(name)
            raise Exception.new("name clash with ActionView::Base instance variables") 
          end
          instance_variable_set(name, { :html => "", :options => {} })
        end
      end
    end
  end

  def initialize(decor_block, &table_block)
    super
    initialize_cells
    decor_block.call(self)
    html = table_block.call(Builder::XmlMarkup.new, self)
    concat(html, decor_block.binding)    
  end

  def display(cell_name)
    instance_variable_get("@#{cell_name}")[:html]
  end

  def html_options(cell_name)
    instance_variable_get("@#{cell_name}")[:options]
  end

end

I've found have these helpers cleans up my views significantly, though I have to admit, it's not exactly easiest to use yet. In addition, I'm not exactly thrilled about having TableBuilder inherit from ActionView::Base, but it was the only way I could figure out to get the call to concat() to work. In any case, the point is to show you that refactoring your views into helpers is a good idea, and even something like a table builder goes a long way, even if you don't do it the way I did it. Lemme know if this helps or hinders you. snippet!