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
:js in normal Rails controllers.)
If you take a look at the source for
ActionController::Renderers, here's how we do it:
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
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.
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
headers directly, regardless of whether you use the
Response helpers or not.
If you want to add rendering in, you can do something like this:
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:
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.
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#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.