Inherited Templates With Rails

A nice feature of some template languages (for instance, Django's) is the ability to create templates that can be "inherited" by other templates. In effect, the goal is to create a template that has some missing content, and let "inheritors" fill in that content downstream.

It's not terribly difficult to add this feature to Rails; let's first design the API. First, the parent template (_parent.html.erb):

Before in parent  
<%= first_from_child %>  
<%= second_from_child %>  
After in parent  

We just use normal partial locals for the parent API, because they're a well-understood construct and pretty easy to work with. Next, the "subclass" (_child.html.erb):

Before in child  
<% override_template("parent") do |template| -%>  
  <% template.set_content(:first_from_child) do -%>first_from_child<% end -%>
  <% template.set_content(:second_from_child) do -%>second_from_child<% end -%>
<% end -%>  
After in child  

Here, we use Ruby's block syntax to create a context for supplying the content for the template. We expect the following output:

Before in child  
Before in parent  
first_from_child  
second_from_child  
After in parent  
After in child  

There are two parts to this implementation. First, let's create the implementation for the override_template method that will be exposed onto ActionView::Base:

module ActionView  
  module InheritedTemplates
    class Collector
    end

    def override_template(name, &block)
      locals = Collector.collect(self, &block)
      concat(render :partial => name, :locals => locals)
    end
  end

  class Base
    include InheritedTemplates
  end
end  

To start, we create the method, deferring the heavy lifting to the Collector.collect method. The API we've designed asks #collect to hand back a Hash of locals, which we can pass unmodified into the "super" template.

The collector is a pretty straight-forward implementation, but it deserves some explanation:

class Collector  
  def self.collect(view)
    collector = new(view)
    yield collector
    collector.content
  end

  attr_reader :content
  def initialize(view)
    @view = view
    @content = {}
  end

  def set_content(name, &block)
    @content[name] = @view.capture(&block)
  end
end

def override_template(name, &block)  
  locals = Collector.collect(self, &block)
  concat(render :partial => name, :locals => locals)
end  

The first thing we do is define the collect method. It's a basic DSL implementation, creating an instance of itself and evaluating the block in its context. In order to fully understand what's going on here, you need to see what the block looks like, once it's compiled from ERB into pure-Ruby:

override_template("parent") do |template|  
  template.set_content(:first_from_child) do; @output_buffer << "first_from_child"; end
  template.set_content(:second_from_child) do; @output_buffer << "second_from_child"; end
end  

We start by creating a new collector, yielding the collector to the block passed to overridetemplate. Inside the block, template.setcontent is called twice; each call sets a key and value in the @content Hash. When done, the Hash will look like {:firstfromchild => "firstfromchild", :secondfromchild => "secondfromchild"}. The collector then returns the content Hash.

When that's done, override_template simply passes that locals Hash through to render :partial, and concats the output to the buffer.

Afterthought

Those following my blog might remember that I showed how we can improve block helpers by smarter compilation. If that fix was in place, here's what _child.html.erb would look like:

Before in child  
<%= override_template("parent") do |template| -%>  
  <% template.set_content(:first_from_child) do -%>first_from_child<% end -%>
  <% template.set_content(:second_from_child) do -%>second_from_child<% end -%>
<% end -%>  
After in child  

More importantly, here's what override_template would look like:

def override_template(name, &block)  
  locals = Collector.collect(self, &block)
  render :partial => name, :locals => locals
end  

We're actually saved a bit of pain here in the unfixed case, because overridetemplate can only be called from inside templates, so we don't need to use blockcalledfromerb? to disambiguate. Had this been a normal block helper, override_template would have looked like:

def override_template(name, &block)  
  locals = Collector.collect(self, &block)
  response = render(:partial => name, :locals => locals)

  if block_called_from_erb?(&block)
    concat(response)
  else
    response
  end
end  

Of course, realizing all of this is non-trivial, and the reason we're going to be moving toward the simple block helper syntax above.