Rails and Merb Merge: Plugin API (Part 3 of 6)


I started off this series on the Rails/Merb merge (aka Rails 3) talking about modularity, and then performance. Next up, plugins!

When we announced the Rails/Merb merge, we promised to bring a more stable plugin API to Rails 3. Merb had strong opinions about an explicitly exposed plugin API, so we hoped to end the complications of alias_method_chain in favor of exposed APIs which plugin authors could rely on across versions.


By far the most important element in developing the plugin APIs for Rails 3 was to eliminate the “secret” APIs used in Rails itself. Instead, we wanted to build Rails on top of the same core components that we would ask plugin authors to build on. The focal point of this effort (because we already had experience doing this with Merb) was ActionPack, and specifically ActionController.

ActionController presented us with another excellent opportunity: because ActionMailer reused a lot of the controller functionality, we had a built-in opportunity to create components that could be used in both ActionController and ActionMailer. In a sense, ActionController and ActionMailer would become plugins of the core system we were creating.

We also took a second important conceptual step. In Rails 2.3, the idea of “metal” was that you could skip the entire ActionController chain and write raw Rack handlers where needed for performance. In Rails 3, we are exposing an incremental series of components that, in sum, make up ActionController::Base. These components include rendering, layouts, conditional get, respond_to, streaming, and others.

In Rails 3, ActionController::Metal is the simplest possible controller, with no additional components added in. ActionController::Base is simply a subclass of ActionController::Metal with all components included. Again, we are dog-fooding our componentized APIs, not simply giving you a watered down version of what we use internally.

Now, let’s dig into a few specific examples of new APIs.


One of the most common reasons people extend controllers is to expose additional renderers. For instance, you may want to render a PDF as well as HTML. The Rails 3 API that we expose to plugin authors for this purpose is identical to the one that we use internally. (As you probably know, in addition to being able to render templates, you can render :json, :xml, or :js in normal Rails controllers.)

If you take a look at the source for ActionController::Renderers, here’s how we do it:

add :json do |json, options|
json = ActiveSupport::JSON.encode(json) unless json.respond_to?(:to_str)
json = "#{options[:callback]}(#{json})" unless options[:callback].blank?
self.content_type ||= Mime::JSON
self.response_body = json

This method is in ActionController::Renderers, so it’s like saying ActionController::Renderers.add(:json) do |json, options|. You can add additional renderers easily in Rails 3 plugins, and you don’‘t have to figure out how to hook into Rails at the appropriate time. Like other parts of the public API, we’re committing to keeping this API unchanged across multiple versions of Rails. If and when when the API DOES change, the change will be flagged for you first, via the normal Rails API deprecation process.


In Rails 3, there’s a supported way to use a simple, stripped down controller, and opt into the functionality you want. The overhead of the completely stripped down controller is a mere 8 microseconds (not much more than the overhead for a pure Rack app), compared with 100 or so microseconds of overhead for the full ActionController::Base (as I said last time, this itself is significantly less than Rails 2.3).

Here’s an example of using ActionController::Metal:

class SimpleController < ActionController::Metal

class HelloController < SimpleController
def index
self.response_body = "Hello World"

A few things to note here. First of all, you don’t need a superclass, but you can build one to re-use in multiple places. The abstract! declaration tells Rails 3 not to include public methods on the superclass as controller actions. It’s not strictly needed here (because there are no public methods), but it’s a good habit for custom ActionController::Metal subclasses. Second of all, because this is a controller, you can route to it through the normal Rails router. From the perspective of the rest of Rails, this is a perfectly normal controller.

Finally, the self.response_body usage is the simple, low-level API used in ActionController itself (for instance, during template rendering), but it’s now 100% first-class and available for your use. You can also set status, content_type and headers directly, regardless of whether you use the Request and Response helpers or not.

If you want to add rendering in, you can do something like this:

class SimpleController < ActionController::Metal
include ActionController::Rendering
append_view_path "#{Rails.root}/app/views"

class HelloController "hello"

You’ve now added in a new module, which provides rendering support. This keeps things simple by not including layout support, because you don’t need it in this case. With this capability, you can add the features that you want to add, leaving out what you don’t. This means that as a metal grows, you don’t need to completely rewrite it as a “normal” controller. Instead, you can pull in the specific features you need. This process is seamless, and again, you can route to it as a normal controller throughout.

If you look at the source for ActionController::Base, you can see that we aren’t doing anything particularly special anymore:

module ActionController
class Base < Metal

include AbstractController::Callbacks
include AbstractController::Layouts

include ActionController::Helpers
helper :all # By default, all helpers should be included

include ActionController::HideActions
include ActionController::UrlFor
include ActionController::Redirecting
include ActionController::Rendering
include ActionController::Renderers::All
include ActionController::ConditionalGet
include ActionController::RackDelegation
include ActionController::Logger
include ActionController::Configuration

Here, ActionController::Base inherits from Metal, and then proceeds to pull in all of the functionality not exposed as separate modules. Although Base pulls them all in, you don’t have to worry about dependencies between these modules; handling dependencies is built into the way these modules work.

View Contexts

As one last example, the way that ActionController communicates with ActionView itself has become a fully defined, exposed API. From the perspective of ActionController, a view implements three APIs:

  • Context.for_controller(controller)
  • Context#render_partial(options)
  • Context#render_template(template, layout, options)

By implementing this API, you can drop in any object in place of ActionView. How would you use this? Well to date, I can think of two examples: rspec_rails is going to use this functionality to implement isolation tests, and you can use this to implement a Merb shim in which the controller and view are the same object (an implementation using an earlier version of the API).

In addition to the usefulness of exposing this functionality via a stable Public API, reducing the boundary between ActionController and ActionView significantly improved the architecture, and exposed areas of brittleness that benefited quite a bit from the definition.


The APIs provided here, while stable at this point, are not final. If you feel that they (or any other part of Rails 3) aren’t adequate for a plugin you’re building, please let us know by commenting.

This post is just a taste of the new ways you can extend Rails 3. In the weeks ahead, expect a lot more documentation and discussion about the exposed plugin hooks.

Yehuda Katz


Subscribe to our Blog