Our jobs as programmers require us to be abstract problem solvers. We solve problems that range from searching databases to updating online to-do lists to managing user authentication. The product of our labor is a collection of solutions, usually in the form of an application, to a particular set of problems that we’ve been asked to solve.

However, I doubt that many of us would still be programmers if we had to solve exactly the same problems repeatedly, day after day. Instead, we are always looking for ways to reapply existing solutions to the problems we encounter. Your code represents the abstract solution to a problem, and so you are often striving to either reuse this abstraction (albeit in slightly different contexts), or refine your solution so that it can be reused. Through reuse, you can save time, money, and effort, and give yourself the opportunity to focus on the interesting and novel aspects of the particular problem you’re currently trying to solve. After all, it’s coming up with interesting and novel solutions to problems that makes us really succeessful.

Using the script/plugin command is often the simplest and easiest way to install plugins. It should be run from the root directory of the application you are developing.

Before getting into gory details, here is an example of script/plugin in action:

$ cd /Users/obie/time_and_expenses
$ script/plugin install acts_as_taggable
+./acts_as_taggable/init.rb
+./acts_as_taggable/lib/README
+./acts_as_taggable/lib/acts_as_taggable.rb
+./acts_as_taggable/lib/tag.rb
+./acts_as_taggable/lib/tagging.rb
+./acts_as_taggable/test/acts_as_taggable_test.rb

Checking the vendor/plugins directory after running this script, you can see that a new directory has appeared named acts_as_taggable.

Where did these files come from? How did script/plugin know where to go to download acts_as_taggable? To understand what’s really going on under the hood here, let’s examine the plugin script’s commands a bit more closely.

In the following sections, we cover each command in depth:

$ script/plugin list
account_location
http://dev.rubyonrails.com/svn/rails/plugins/account_location/
acts_as_taggable
http://dev.rubyonrails.com/svn/rails/plugins/acts_as_taggable/
browser_filters
http://dev.rubyonrails.com/svn/rails/plugins/browser_filters/
continuous_builder
http://dev.rubyonrails.com/svn/rails/plugins/continuous_builder/
deadlock_retry
http://dev.rubyonrails.com/svn/rails/plugins/deadlock_retry/
exception_notification
http://dev.rubyonrails.com/svn/rails/plugins/exception_notification/
localization
http://dev.rubyonrails.com/svn/rails/plugins/localization/
...

$ script/plugin sources
http://dev.rubyonrails.com/svn/rails/plugins/
http://svn.techno-weenie.net/projects/plugins/
http://svn.protocool.com/rails/plugins/
http://svn.rails-engines.org/plugins/
http://lesscode.org/svn/rtomayko/rails/plugins/
...

$ script/plugin source http://www.our-server.com/plugins/
Added 1 repositories.

$ script/plugin source http:///www.our-server.com/plugins/
 Added 1 repositories.

$ script/plugin unsource http:///www.our-server.com/plugins/
Removed 1 repositories.

$ script/plugin discover
Add http://opensvn.csie.org/rails_file_column/plugins/? [Y/n] y
Add http://svn.protocool.com/rails/plugins/? [Y/n] y
Add svn://rubyforge.org//var/svn/laszlo-plugin/rails/plugins/? [Y/n] y
Add http://svn.hasmanythrough.com/public/plugins/? [Y/n] y
Add http://lesscode.org/svn/rtomayko/rails/plugins/? [Y/n] y
...

$ script/plugin discover http://internaldev.railsco.com/railsplugins

$ script/plugin install simply_restful

$ script/plugin install
http://www.pheonix.org/plugins/acts_as_macgyver
+./vendor/plugins/acts_as_macgyver/init.rb
+./vendor/plugins/acts_as_macgyver/lib/mac_gyver/chemistry.rb
+./vendor/plugins/acts_as_macgyver/lib/mac_gyver/swiss_army_knife.rb
+./vendor/plugins/acts_as_macgyver/assets/toothpick.jpg
+./vendor/plugins/acts_as_macgyver/assets/busted_up_bike_frame.html
+./vendor/plugins/acts_as_macgyver/assets/fire_extinguisher.css

$script/plugin -v remove acts_as_taggable
Removing 'vendor/plugins/acts_as_taggable'

$ script/plugin -f install my_plugin

As mentioned earlier, most of the plugin sources you encounter will actually be Subversion repositories. Why is this useful for plugin users? Most importantly, because you don’t have to be a developer contributing to a repository to receive updates from it; you can maintain a copy of a plugin that can be easily (or even automatically) updated when the plugin author adds new features, fixes bugs, and generally updates the central plugin code.

Before you can use Subversion, you need to ensure that it has been installed on your local systems. The Subversion project can be found at http://subversion.tigris.org, where they maintain a number of binary distributions of the Subversion tools. If you’re running on Linux or Mac OS X, chances are that you already have it installed, but Windows users will almost certainly need to use one of the prebuilt installers available on the Subversion web site.

$ script/plugin install -o white_list
A  t_and_e/vendor/plugins/white_list/test
A  t_and_e/vendor/plugins/white_list/test/white_list_test.rb
A  t_and_e/vendor/plugins/white_list/Rakefile
A  t_and_e/vendor/plugins/white_list/init.rb
A  t_and_e/vendor/plugins/white_list/lib
A  t_and_e/vendor/plugins/white_list/lib/white_list_helper.rb
A  t_and_e/vendor/plugins/white_list/README
Checked out revision 2517.

$ script/plugin install -x continuous_builder
A  t_and_e/vendor/plugins/continuous_builder/tasks
A  t_and_e/vendor/plugins/continuous_builder/tasks/test_build.rake
A  t_and_e/vendor/plugins/continuous_builder/lib
A  t_and_e/vendor/plugins/continuous_builder/lib/marshmallow.rb
A  t_and_e/vendor/plugins/continuous_builder/lib/builder.rb
A  t_and_e/vendor/plugins/builder/README.txt
Checked out revision 5651.

$ svn propget svn:externals vendor/plugins/ continuous_builder
  http://dev.rubyonrails.com/svn/rails/plugins/continuous_builder

Piston is distributed as a RubyGem. Installation is as simple as typing gem install piston:

$ sudo gem install —include-dependencies piston
Need to update 13 gems from http://gems.rubyforge.org
.............
complete
Successfully installed piston-1.2.1

After installation, a new executable named piston will be available on your command line, with the following commands:

$ piston
Available commands are:
  convert      Converts existing svn:externals into Piston managed
folders
  help         Returns detailed help on a specific command
  import       Prepares a folder for merge tracking
  lock         Lock one or more folders to their current revision
  status       Determines the current status of each pistoned
directory
  unlock       Undoes the changes enabled by lock
  update       Updates all or specified folders to the latest revision

The import command tells Piston to add a vendor library to your project. For example, let’s use Piston to make our sample project run EdgeRails, meaning that Rails is executed out of the vendor/rails folder instead of wherever it is installed as a RubyGem:

$ piston import http://dev.rubyonrails.org/svn/rails/trunk
vendor/rails
Exported r5731 from 'http://dev.rubyonrails.org/svn/rails/trunk' to
'vendor/rails'

Piston does not commit anything to Subversion on its own. To make Piston changes permanent, you need to check in the changes yourself.

$ svn commit -m "Importing local copy of Rails"

Also, don’t forget that unlike Rails’ own plugin script, Piston takes a second argument specifying the target directory to install the library into (and if you leave the parameter off, it will default to the current directory).

For example, here’s how you would install Rick Olsen’s excellent white_list plugin, from the projects directory:

$ piston import
  http://svn.techno-
weenie.net/projects/plugins/white_list/vendor/plugins/white_list
Exported r2562 from
'http://svn.techno-weenie.net/projects/plugins/white_list' to
'vendor/plugins/white_list'

If you’ve already been using svn:externals to link plugins into the source code of your project, the first thing you should do is to convert those over to Piston, by invoking the piston convert command from your project directory:

$ piston convert
Importing 'http://macromates.com/svn/Bundles/trunk/Bundles/
Rails.tmbundle/Support/plugins/footnotes' to vendor/plugins/footnotes
(-r 6038)
Exported r6038 from 'http://macromates.com/svn/Bundles/trunk/Bundles/
Rails.tmbundle/Support/plugins/footnotes' to 'vendor/plugins/footnotes'

Importing 'http://dev.rubyonrails.com/svn/rails/plugins/
continuous_builder' to vendor/plugins/continuous_builder (-r 5280)
Exported r5280 from 'http://dev.rubyonrails.com/svn/rails/plugins/
continuous_builder' to 'vendor/plugins/continuous_builder'

Done converting existing svn:externals to Piston

Again, remember that it’s necessary to check in the resulting changes to your project files after running Piston.

When you want to get the latest changes from a remote repository for a library installed with Piston, use the update command:

$ piston update vendor/plugins/white_list/
Processing 'vendor/plugins/white_list/'...
  Fetching remote repository's latest revision and UUID
  Restoring remote repository to known state at r2562
  Updating remote repository to r2384
  Processing adds/deletes
  Removing temporary files / folders
  Updating Piston properties
  Updated to r2384 (0 changes)

You can prevent a local Piston-managed folder from updating by using the piston lock command. And once a folder is locked, you can unlock it by using the piston_unlock command. Locking functionality is provided as an extra precaution available to teams of Rails developers. If you know that updating a plugin will break the application, you can lock it and other developers will get an error if they try to update without unlocking.

If we use svn proplist to examine the properties for vendor/plugins/continuous_builder, we’ll see that Piston stores its own properties for each plugin folder rather than on the plugins folder itself:

$ svn proplist —verbose vendor/plugins/continuous_builder/

Properties on 'vendor/plugins/continuous_builder':

  piston:root :
http://dev.rubyonrails.com/svn/rails/plugins/continuous_builder

  piston:local-revision : 105
  piston:uuid : 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  piston:remote-revision : 5280

If you pop open the boilerplate init.rb file that Rails generated for you, you’ll read a simple instruction.

# insert hook code here

Hook code means code that hooks into the Rails initialization routines. To see a quick example of hook code in action, just go ahead and generate a plugin in one of your projects and add the following line to its init.rb:

puts "Current Rails version: #{Rails::VERSION::STRING}"

Congratulations, you’ve written your first simple plugin. Run the Rails console and see what I mean:

$ script/console
Loading development environment.
Current Rails version: 1.2.3
>>

Code that’s added to init.rb is run at startup. (That’s any sort of Rails startup, including server, console, and script/runner.) Most plugins have their require statements in init.rb.

A few special variables are available to your code in init.rb having to do with the plugin itself:

Our simple example is just that, simple. Most of the time you want a plugin to provide new functionality to the rest of your application or modify the Rails libraries in more interesting ways than printing out a version number on startup.

The lib directory of your plugin is added to Ruby’s load path before init.rb is run. That means that you can require your code without needing to jump through hoops specifying the load path:

require File.dirname(__FILE__) + '/lib/my_plugin' # unnecessary

Assuming your lib directory contains a file named my_plugin.rb, your init.rb just needs to read:

require 'my_plugin'

Simple. You can bundle any class or Ruby code in a plugin’s lib folder and then load it in init.rb (or allow other developers to optionally load it in environment.rb) using Ruby’s require statement. This is the simplest way to share Ruby code among multiple Rails applications.

It’s typical for plugins to alter or enhance the behavior or existing Ruby classes. As a simple example, Listing 19.1 is the source of a plugin that gives ActiveRecord classes a cursorlike iterator. (Please note that a smarter implementation of this technique might incorporate transactions, error-handling, and batching. See http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord for more on the subject.)

# in file vendor/plugins/my_plugin/my_plugin.rb

class ActiveRecord::Base

  def self.each
    ids = connection.select_values("select id from #{table_name}")
    ids.each do |id|
      yield find(id)
    end
    ids.size
  end

end

In addition to opening existing classes to add or modify behavior, there are at least three other ways used by plugins to extend Rails functionality:

The way that we re-open the ActiveRecord::Base class in Listing 19.1 and simply add a method to it is simple, but most plugins follow a pattern used internally in Rails and split their methods into two modules, one each for class and instance methods. We’ll go ahead and add a useful to_param instance method to all our ActiveRecord objects too^[3].

Let’s rework my_plugin so that it follows that style. First, after requiring 'my_plugin' in init.rb, we’ll send an include message to the ActiveRecord class itself:

ActiveRecord::Base.send(:include, MyPlugin)

There’s also another way of accomplishing the same result, which you might encounter when browsing through the source code of popular plugins^[4]:

ActiveRecord::Base.class_eval do
  include MyPlugin
end

Now we need to write a MyPlugin module to house the class and instance variables with which we will extend ActiveRecord::Base. See Listing 19.2.

module MyPlugin
  def self.included(base)
    base.extend(ClassMethods)
    base.send(:include, InstanceMethods)
  end

  module ClassMethods
    def each
      ids = connection.select_values("select id from #{table_name}")
      ids.each do |id|
        yield find(id)
      end
      ids.size
    end
  end

  module InstanceMethods
    def to_param
      has_name? ? "#{id}-#{name.gsub(/[^a-z0-9]+/i, '-')}" : super
    end

    private

      def has_name?
        respond_to?(:name) and not new_record?
      end

  end
end

You can use similar techniques to extend controllers and views.^[5] For instance, if you want to add custom helper methods available in all your view templates, you can extend ActionView like this:

ActionView::Base.send(:include, MyPlugin::MySpecialHelper)

Now that we’ve covered the fundamentals of writing Rails plugins (init.rb and the contents of the lib directory), we can take a look at the other files that are created by the plugin generator script.

The first thing that developers do when they encounter a new plugin is to take a look in the README file. It’s tempting to ignore this file, but at the very least, you should add a simple description of the what the plugin does, for future reference. The README file is also read and processed by Ruby’s RDoc tool, when you generate documentation for your plugin using the doc:: Rake tasks. It’s worth learning some fundamentals of RDoc formatting if you want the information that you put in the README file to look polished and inviting later.

Rails is open-sourced under the extremely liberal and open MIT license, as are most of the popular plugins available. In his keynote address to Railsconf 2007, David announced that the plugin generator will auto-generate an MIT license for the file, to help to solve the problem of plugins being distributed without an open-source license. Of course, you can still change the license to whatever you want, but the MIT license is definitely considered the Rails way.

This pair of files is placed in the root of the plugin directory along with init.rb and README. Just as the init.rb file can be used to perform a set of actions each time the server starts, these files can be used to ensure that prerequisites of your plugin are in place when the plugin is installed using the script/plugin install command and that your plugin cleans up after itself when it is uninstalled using script/plugin remove.

require 'fileutils'
FileUtils.mkdir_p File.join(RAILS_ROOT, 'tmp', 'my_plugin_data')

# Install the engines plugin unless it is already present
unless File.exist?(File.dirname(__FILE__) + "/../engines")
  Commands::Plugin.parse!(['install',
    'http://svn.rails-engines.org/plugins/engines'])
end

$ svn co http://plugins.com/svn/whoops vendor/plugins/whoops # no install

It is often useful to include Rake tasks in plugins. For example, if your plugin stores files in a temporary directory (such as /tmp), you can include a helpful task for clearing out those temporary files without having to dig around in the plugin code to find out where the files are stored. Rake tasks such as this should be defined in a .rake file in your plugin’s tasks folder (see Listing 19.5).

# vendor/plugins/my_plugin/tasks/my_plugin.rake

namespace :my_plugin do

  desc 'Clear out the temporary files'
  task :cleanup => :environment do
    Dir[File.join(RAILS_ROOT, 'tmp', 'my_plugin_data')].each do |f|
      FileUtils.rm(f)
    end
  end

end

Rake tasks added via plugins are listed alongside their standard Rails brothers and sister when you run rake -T to list all the tasks in a project. (In the following snippet, I limited Rake’s output by passing a string argument to use for matching task names):

$ rake -T my_plugin
rake my_plugin:cleanup   # Clear out the temporary files

Generated plugins get their own little Rakefile, which can be used from within the plugin’s directory to run its tests and generate its RDoc documentation (see Listing 19.6).

require 'rake'
require 'rake/testtask'
require 'rake/rdoctask'

desc 'Default: run unit tests.'
task :default => :test

desc 'Test the my_plugin plugin.'
Rake::TestTask.new(:test) do |t|
  t.libs << 'lib'
  t.pattern = 'test/**/*_test.rb'
  t.verbose = true
end

desc 'Generate documentation for the my_plugin plugin.'
Rake::RDocTask.new(:rdoc) do |rdoc|
  rdoc.rdoc_dir = 'rdoc'
  rdoc.title    = 'MyPlugin'
  rdoc.options << '--line-numbers' << '--inline-source'
  rdoc.rdoc_files.include('README')
  rdoc.rdoc_files.include('lib/**/*.rb')
end

While we’re on the subject, I’ll also mention that Rails has its own default rake tasks related to plugins, and they’re fairly self-explanatory:

$ rake -T plugin

rake doc:clobber_plugins        # Remove plugin documentation
rake doc:plugins                # Generate docs for installed plugins
rake test:plugins               # Run the plugin tests in
                                  vendor/plugins/*/**/test
                                  (or specify with PLUGIN=name)

Before closing this section, let’s make the distinction between a plugin’s Rakefile and any .rake files in the tasks folder clear:

Last, but not least, after you’ve written your plugin, it’s essential that you provide tests that verify its behavior. Writing tests for plugins is for the most part identical to any testing in Rails or Ruby and for the most part the methods used to test both are the same. However, because plugins cannot often predict the exact environment in which they are run, they require extra precautions to ensure that the test behavior of your plugin code is isolated from the rest of the application.

There is a subtle distinction between running plugin tests using the global test:plugins rake task and via the plugin’s own Rakefile. Although the former can test all installed plugins at the same time, the internal Rakefile can and should be exploited to add any specific tasks your plugin requires to be tested properly.

Techniques used in testing plugins properly include bootstrapping a separate database for testing plugins in complete isolation. This is particularly useful when a plugin augments ActiveRecord with additional functionality, because you need to test the new methods in a controlled environment, minimizing the interaction with other plugins and the application’s own test data.

As you can imagine, testing of plugins is a lengthy topic that is primarily of interest to plugin authors. Unfortunately, I must leave further analysis of the subject out of this book for reasons of practicality and overall length.