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 override_template. Inside the block, template.set_content is called twice; each call sets a key and value in the @content Hash. When done, the Hash will look like {:first_from_child => "first_from_child", :second_from_child => "second_from_child"}. 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 override_template can only be called from inside templates, so we don't need to use block_called_from_erb? 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.