This post comes from guest community contributor and Engine Yard alumni Andre Arko. Andre has been building web applications with Ruby and Rails for five years, and is a member of the Bundler core team. He works for Plex, tweets as @indirect, and blogs at andre.arko.net.
Gem plugins in Rails 3.0
Rails 3.0 is finally released, and with it comes a fantastic new way to extend Rails: Railties. Railties are the basis of the core components of Rails 3, and are the result of months of careful refactoring by Carlhuda. It is easier to extend and expand Rails than it has ever been before, without an
alias_method_chain in sight.
Unfortunately, while the system for extending and expanding Rails has been completely overhauled, the documentation hasn't been updated yet. The Rails Plugins Guide only covers writing plugins in the old Rails 2 style. Ilya Grigorik wrote a Railtie & Creating Plugins blog post, but just scratched the surface of what is possible with a Railtie plugin. This post covers writing Railtie plugins, hooking into the Rails initialization process, packaging Railtie plugins as gems, and using gem plugins in a Rails 3 application.
Creating Railtie plugins
Creating a Railtie is easy. Just create a class that inherits from
::Rails::Railtie. Every subclass of Railtie is used to initialize your Rails application. Since ActionController, ActionView, and the other Rails components are also Railties, your plugin can function as a first-class member of the Rails application. It will have access to the same methods and context that are used by the official Rails components. Here is a sample minimal Railtie that will be loaded when your Rails application boots.
require 'rails' class MyCoolRailtie < Rails::Railtie # railtie code goes here end
The Railtie documentation lists all of the methods that are available inside each Railtie class, but doesn't really go into depth about what you can use Railties to do. Here are some example Railties explaining how to use the Railtie methods (in alphabetical order) to customize and extend Rails.
console method allows your Railtie to add code that will be run when a Rails console is started.
console do Foo.console_mode! end
Rails will require any generators defined in
lib/generators/*.rb automatically. If you ship Rails::Generators with your Railtie in some other directory, you can require them using this method.
generators do require 'path/to/generator' end
If you ship rake tasks for apps with your Railtie, load them using this method.
rake_tasks do require 'path/to/railtie.tasks' end
initializer method provides Railties with a lot of power. They create initializers that will be run during the Rails boot process, like the files put into
config/initializers in the app directory. The initializer method takes two options,
:before, if there are specific initializers that you want to run before or after yours.
initializer "my_cool_railtie.boot_foo" do Foo.boot(Bar) end initializer "my_cool_railtie.boot_bar", :before => "my_cool_railtie.boot_foo" do Bar.boot! end
Rails configuration hooks
The biggest extension hook that Railties provide is somewhat unassuming: the
config method. That method returns the instance of
Railtie::Configuration that belongs to the application being booted. This opens up all sorts of interesting possibilities, since the
config object is the same one that is made available inside a Rails application's
environment.rb file. Here are some annotated examples of using
config to change how a Rails application is initialized and configured.
This method takes a block that will be run after Rails is is completely initialized, and all of the application's initializers have run.
This method exposes the MiddlewareStack that will be used to handle requests to your Rails application. You can use any of the methods defined on MiddlewareStack, including
swap, to manage the Rails application's Rack middlewares. For example, if your Railtie included the Rack middleware
MyRailtie::Middleware, you could add it to the Rails application middleware stack like this:
Code passed in a block to this method will be run immediately before the application configuration block inside
application.rb is run. This is usually the best place to set default options that users of your plugin should be able to override themselves, as in the
jquery-rails example below.
The block passed to
before_eager_load will be run before Rails requires the application's classes. Eager load is never run in development mode. However, if you need to run code after Rails loads, but before any application code loads, this is the place to put it.
config.before_eager_load do SomeClass.set_important_value = "RoboCop" end
This method takes a block to be run before the Rails initialization process happens -- this is basically equivalent to creating an initializer, and setting it to run before the first initializer the app has.
This object holds the configuration for the generators that are invoked when you run the
rails generate command.
config.generators do |g| g.orm :datamapper, :migration => true g.template_engine :haml g.test_framework :rspec end
You can also use it to disable colorized logging in the console.
config.generators.colorize_logging = false
Last, but quite importantly,
to_prepare allows you to do one-time setup. The block you pass to this method will run for every request in development mode, but only once in production. Use it when you need to set something up once before the app starts serving requests.
At this point, you're probably thinking "why would I actually want to do any of that stuff?". So, here are a few select examples of Railtie plugins packaged as gems.
The rspec-rails plugin ships with a set of rake tasks and generators that integrate the RSpec gem with Rails.
module RSpec module Rails class Railtie < ::Rails::Railtie config.generators.integration_tool :rspec config.generators.test_framework :rspec rake_tasks do load "rspec/rails/tasks/rspec.rake" end end end end
This Railtie just does three things: First, it sets the generators that will be used for integration tests via the
integration_tool method. Next, it sets the generators that will be used to generate model, controller, and view tests (via the
test_framework method). Last, it loads the RSpec rake tasks to run RSpec tests instead of test-unit tests.
The jquery-rails plugin ships with a generator that downloads and installs jQuery, the jquery-ujs script that enables Rails helpers with jQuery, and optionally installs jQueryUI as well.
This Railtie only sets one setting, but checks for the jQueryUI library to determine the value to set. By using the
config.before_configuration hook, it runs right before the
application.rb config block runs. That means it has access to the Rails.root, which is needed to check for jQueryUI, and it means that users can still override
application.rb if they want something different than the new defaults that the plugin provides.
The haml-rails gem provides generators for views written in Haml instead of the default generated views that are written in ERB.
module Haml module Rails class Railtie < ::Rails::Railtie config.generators.template_engine :haml config.before_initialize do Haml.init_rails(binding) Haml::Template.options[:format] = :html5 end end end end
This Railtie simply changes the template engine that Rails invokes when you run
rails generate, and then initializes Haml for Rails, and sets the Haml output format to HTML5.
Packaging up gem plugins
Railtie plugins are easy to turn into gem plugins for Rails. This makes them easy to distribute, manage, and upgrade. The first thing you need is a gem. If you don't have a gem yet, you can create a new gem easily using Bundler. Just run
bundle gem my_new_gem and Bundler will generate a skeleton gem and gemspec that follow gem best practices. Once you have a gem, just make sure that your Railtie subclass is defined when
lib/my_new_gem.rb is loaded. You can define the Railtie in a separate file and require that file, or define it directly. Last, add a dependency on the Rails gem (~>3.0) to your gemspec.
If your gem is also a plain Ruby library, and you don't want to depend on the Rails gem, then you can put your Railtie in a separate file, and conditionally require that file inside your main library file.
# lib/my_new_gem/my_cool_railtie.rb module MyNewGem class MyCoolRailtie < ::Rails::Railtie # Railtie code here end end # lib/my_new_gem.rb require 'my_new_gem/my_cool_railtie.rb' if defined?(Rails)
This ensures that your gem can be loaded (without the Railtie) if it is loaded outside the context of a Rails application.
Now that your gem has a Railtie, you can build it and release it to Gemcutter. Once your gem is on Gemcutter, using it with Rails 3 applications is extremely easy -- just add the gem to your
Gemfile. Bundler will download and install your gem when you run
bundle install, Rails will load it, and the
Rails::Railtie class takes care of the rest!