Rails Plugins: Chapter 3 - Advanced Rails

By default, plugins are loaded from directories under vendor/plugins in the Rails application root. Should you need to change or add to these paths, the plugin_paths configuration item contains the plugin load paths:

	config.plugin_paths += [File.join(RAILS_ROOT, 'vendor', 'other_plugins')]

By default, plugins are loaded in alphabetical order; attachment_fu is loaded before http_authentication. If the plugins have dependencies on each other, a manual loading order can be specified with the plugins configuration element:

	config.plugins = %w(prerequisite_plugin actual_plugin)

Any plugins not specified in config.plugins will not be loaded. However, if the last plugin specified is the symbol :all, Rails will load all remaining plugins at that point. Rails accepts either symbols or strings as plugin names here.

	config.plugins = [ :prerequisite_plugin, :actual_plugin, :all ]

The plugin locator searches for plugins under the configured paths, recursively. Because a recursive search is performed, you can organize plugins into directories; for example, vendor/plugins/active_record_acts and vendor/plugins/view_extensions.

The actual plugin locating and loading system is extensible, and you can write your own strategies. The locator (which by default is Rails::Plugin::FileSystemLocator) searches for plugins; the loader (by default Rails::Plugin::Loader) determines whether a directory contains a plugin and does the work of loading it.

To write your own locators and loaders, examine railties/lib/rails/plugin/locator.rb and railties/lib/rails/plugin/loader.rb. The locators (more than one locator can be used) and loader can be changed with configuration directives:

	config.plugin_locators += [MyPluginLocator]
	config.plugin_loader = MyPluginLoader

Plugins are most often installed with the built-in Rails plugin tool, script/plugin. This plugin tool has several commands:

script/plugin install takes an option, -x, that directs it to manage plugins as Subversion externals. This has the advantage that the directory is still linked to the external repository. However, it is a bit inflexible—you cannot cherry-pick changes from the upstream repository. We will examine some better options later.

	$ rapt search calendar
	Calendar Helper
	  Info: http://agilewebdevelopment.com/plugins/show/98
	  Install: http://topfunky.net/svn/plugins/calendar_helper
	Calendariffic 0.1.0
	  Info: http://agilewebdevelopment.com/plugins/show/743
	  Install: http://opensvn.csie.org/calendariffic/calendariffic/
	Google Calendar Generator
	  Info: http://agilewebdevelopment.com/plugins/show/277
	  Install: svn://rubyforge.org//var/svn/googlecalendar/plugins/googlecalendar
	dhtml_calendar
	  Info: http://agilewebdevelopment.com/plugins/show/333
	  Install: svn://rubyforge.org//var/svn/dhtmlcalendar/dhtml_calendar
	Bundled Resource
	  Info: http://agilewebdevelopment.com/plugins/show/166
	  Install: svn://syncid.textdriven.com/svn/opensource/bundled_resource/trunk
	DatebocksEngine
	  Info: http://agilewebdevelopment.com/plugins/show/356
	  Install: http://svn.toolbocks.com/plugins/datebocks_engine/       
	datepicker_engine       
	  Info: http://agilewebdevelopment.com/plugins/show/409
	  Install: http://svn.mamatux.dk/rails-engines/datepicker_engine

	$ piston import http://svn.rubyonrails.org/rails/plugins/deadlock_retry \
	    vendor/plugins/deadlock_retry
	Exported r7144 from 'http://svn.rubyonrails.org/rails/plugins/deadlock_retry/'
	to 'vendor/plugins/deadlock_retry'

	$ svn ci

	$ piston import http://svn.rubyonrails.org/rails/trunk vendor/rails

Plugins can be very simple in structure. For example, consider David Heinemeier Hansson's account_location plugin. This plugin provides controller and helper methods to support using part of the domain name as an account name (for example, to support customers with domain names of customer1.example.com and customer2.example.com, using customer1 and customer2 as keys to look up the account information). To use the plugin, include AccountLocation in one or more of your controllers, which adds the appropriate instance methods:

	class ApplicationController < ActionController::Base
	  include AccountLocation
	end

	puts ApplicationController.instance_methods.grep /^account/
	=> ["account_domain", "account_subdomain", "account_host", "account_url"]

Including the AccountLocation module in the controller allows you to access various URL options from the controller and the view. For example, to set the @account variable from the subdomain on each request:

	class ApplicationController < ActionController::Base
	  include AccountLocation
	  before_filter :find_account

	  protected

	  def find_account
	    @account = Account.find_by_username(account_subdomain)
	  end
	end

The account_location plugin has no init.rb; nothing needs to be set up on load, as all functionality is encapsulated in the AccountLocation module. Here is the implementation, in lib/account_location.rb (minus some license text):

	module AccountLocation
	  def self.included(controller)
	    controller.helper_method(:account_domain, :account_subdomain,
	      :account_host, :account_url)
	  end

	  protected

	  def default_account_subdomain
	    @account.username if @account && @account.respond_to?(:username)
	  end

	  def account_url(account_subdomain = default_account_subdomain,
	      use_ssl = request.ssl?)
	    (use_ssl ? "https://" : "http://") + account_host(account_subdomain)
	  end

	  def account_host(account_subdomain = default_account_subdomain)
	    account_host = ""
	    account_host << account_subdomain + "."
	    account_host << account_domain
	  end

	  def account_domain
	    account_domain = ""
	    account_domain << request.subdomains[1..-1].join(".") +
	      "." if request.subdomains.size > 1
	    account_domain << request.domain + request.port_string
	  end

	  def account_subdomain
	    request.subdomains.first
	  end
	end

The self.included method is a standard idiom for plugins; it is triggered after the module is included in a class. In this case, that method marks the included instance methods as Rails helper methods, so they can be used from a view.

Finally, remember that Dependencies.load_paths contains the lib directories of all loaded plugins, so the act of mentioning AccountLocation searches for account_ location.rb among those lib directories. Because of this, you do not need to require anything in order to use the plugin—just drop the code into vendor/plugins.

The ssl_requirement plugin allows you to specify certain actions that must be protected by SSL. This plugin conceptually divides actions into three categories:

In typical Rails fashion, the methods that specify SSL requirements are a declarative language. They specify what the requirements are, not how to enforce them. This means that the code reads very cleanly:

	class OrderController < ApplicationController
	  ssl_required :checkout, :payment
	  ssl_allowed :cart
	end

Like the account_location plugin, the ssl_requirement plugin is enabled by including a module. The SslRequirement module contains the entire SSL requirement logic:

	module SslRequirement
	  def self.included(controller)
	    controller.extend(ClassMethods)
	    controller.before_filter(:ensure_proper_protocol)
	  end

	  module ClassMethods
	    def ssl_required(*actions)

	      write_inheritable_array(:ssl_required_actions, actions)
	    end

	    def ssl_allowed(*actions)
	      write_inheritable_array(:ssl_allowed_actions, actions)
	    end
	  end

	  protected

	  def ssl_required?
	    (self.class.read_inheritable_attribute(:ssl_required_actions) || []).
	      include?(action_name.to_sym)
	  end

	  def ssl_allowed?
	    (self.class.read_inheritable_attribute(:ssl_allowed_actions) || []).
	      include?(action_name.to_sym)
	  end

	  private

	  def ensure_proper_protocol
	    return true if ssl_allowed?

	    if ssl_required? && !request.ssl?
	      redirect_to "https://" + request.host + request.request_uri
	      return false
	    elsif request.ssl? && !ssl_required?
	      redirect_to "http://" + request.host + request.request_uri
	      return false
	    end
	  end
	end

Again, the SslRequirement.included method is triggered when SslRequirement is included in a controller class. The included method does two things here. First, it extends the controller with the SslRequirement::ClassMethods module, to include the ssl_required and ssl_allowed class methods. This is a common Ruby idiom for adding class methods, and it is required because module methods of an included module do not become class methods of the including class. (In other words, ssl_required and ssl_allowed could not be module methods of SslRequirement, because they would not be added as class methods of the controller class.)

The second thing that SslRequirement.included does is to set up a before_filter on the controller to enforce the SSL requirement. This filter redirects to the proper http:// or https:// URL, depending on the logic declared by the class methods.

The final plugin we will examine is the http_authentication plugin, which allows you to protect certain actions in an application by HTTP Basic authentication (currently, Digest authentication is stubbed out but not implemented).

The HTTP Authentication plugin is very straightforward; the most common interface is the ActionController class method authenticate_or_request_with_http_basic, typically used in a before_filter on protected actions. That method takes as parameters an authentication realm and a login procedure block that verifies the given credentials. If the login procedure returns true, the action is allowed to continue. If the login procedure returns false, the action is blocked and an HTTP 401 Unauthorized status code is sent, with instructions on how to authenticate (a WWW-Authenticate header). In that case, the browser will typically present the user with a login and password and allow three tries before displaying an "Unauthorized" page.

The following is a typical use of the HTTP Authentication plugin:

	class PrivateController < ApplicationController
	  before_filter :authenticate

	  def secret
	    render :text => "Password correct!"
	  end
 
	  protected

	  def authenticate
	    authenticate_or_request_with_http_basic do |username, password|
	      username == "bob" && password == "secret"
	    end
	  end
	end

Notice that, unlike the two plugins described earlier, here we did not have to include anything in the PrivateController—the authenticate_or_request_with_http_basic method was already provided for us. This is because the plugin added some methods to ActionController::Base (of which ApplicationController is a subclass).

One way to include methods like this is direct monkeypatching. The plugin could have directly written the methods into ActionController::Base:

	class ActionController::Base 
	  def authenticate_or_request_with_http_basic(realm = "Application", 
	                                              &login_procedure) 
	    authenticate_with_http_basic(&login_procedure) || 
	      request_http_basic_authentication(realm) 
	end


	  def authenticate_with_http_basic(&login_procedure)
	    HttpAuthentication::Basic.authenticate(self, &login_procedure)
	  end

	  def request_http_basic_authentication(realm = "Application")
	    HttpAuthentication::Basic.authentication_request(self, realm)
	  end
	end

This works for small plugins, but it can get clunky. The better solution, chosen by this plugin, is to first create a module named for the plugin (sometimes including the developer's name or company to reduce the chance of namespace collisions). Here is the abridged code for the HTTP Authentication plugin's class methods:

	module HttpAuthentication
	  module Basic
	    extend self
	    module ControllerMethods
	      def authenticate_or_request_with_http_basic(realm = "Application", 
	                                                  &login_procedure) 
	       authenticate_with_http_basic(&login_procedure) || 
	         request_http_basic_authentication(realm) 
	      end

	      def authenticate_with_http_basic(&login_procedure)
	        HttpAuthentication::Basic.authenticate(self, &login_procedure) 
	      end

	      def request_http_basic_authentication(realm = "Application")
	        HttpAuthentication::Basic.authentication_request(self, realm)
	      end
	    end
	  end
	end

Now, the methods are self-contained within HttpAuthentication::Basic:: ControllerMethods. A simple statement in the plugin's init.rb file adds the methods to ActionController::Base:

	ActionController::Base.send :include,
	  HttpAuthentication::Basic::ControllerMethods

The semantics of some plugins makes them difficult to test without relying on a data-base. But while you would like your tests to run everywhere, you cannot depend on a particular DBMS being installed. Additionally, you want to avoid requiring your users to create a test database in order to test a plugin.

Scott Barron has come up with a clever solution, which he uses in his acts_as_state_ machine plugin ^[29] (a plugin to assign states to ActiveRecord model objects, such as pending, shipped, and refunded orders). The solution is to allow the user to test with any DBMS, and fall back to SQLite (which is widely installed) if none is chosen.

To make this work, a set of test model objects and corresponding fixtures are included in the plugin's test/fixtures directory. The plugin also includes a database schema backing the models (schema.rb) and some statements in test_helper.rb that load the fixtures into the database. The full test directory structure is shown in Figure 3.2, “Plugin testing directory structure”.

Figure 3.2. Plugin testing directory structure

The first piece of the puzzle is the database.yml file, which includes not only configuration blocks for standard DBMSs, but also for SQLite and SQLite3, which save their database in a local file:

	sqlite:
	  :adapter: sqlite
	  :dbfile: state_machine.sqlite.db
	sqlite3:
	  :adapter: sqlite3
	  :dbfile: state_machine.sqlite3.db
	# (postgresql and mysql elided)

The schema files, fixtures, and models are self-explanatory; they are a Ruby schema file, YAML fixtures, and ActiveRecord model classes, respectively. The real magic happens in test_helper.rb, which ties everything together.

The test helper first sets up Rails load paths and loads ActiveRecord. Then it loads database.yml and instructs ActiveRecord to connect to the database (defaulting to SQLite):

	config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
	ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
	ActiveRecord::Base.establish_connection(config[ENV['DB'] || 'sqlite'])

Next, the schema file is loaded into the database:

	load(File.dirname(__FILE__) + "/schema.rb") if 
	  File.exist?(File.dirname(__FILE__) + "/schema.rb")

Finally, the plugin's fixture path is set as TestCase's fixture path and added to the load path so that models in that directory will be recognized:

	Test::Unit::TestCase.fixture_path = File.dirname(__FILE__) + "/fixtures/"
	$LOAD_PATH.unshift(Test::Unit::TestCase.fixture_path)

Now, the test (acts_as_state_machine_test.rb) can reference ActiveRecord classes and their fixture data just as in a standard Rails unit test.