Advanced Rails - Building Industrial-Strength Web Apps in Record Time

Plugin Examples | 85

README

It is helpful to provide a short explanation here of the plugin’s purpose, usage,

and any special instructions. A hook can be included ininstall.rb(described ear-

lier) to print this file upon plugin installation.

test/
This folder contains the plugin’s tests. These tests are run using Rake, without
loading Rails. Any tests written in this folder must stand alone—they must either
mock out any required Rails functionality or actually load the Rails framework.
We will explore both of these options later.

uninstall.rb (not shown)
This is the uninstall hook, run when a plugin is removed by tools such as
script/pluginor RaPT. Unless you have a very pressing need, the use of this file
is discouraged. Likeinstall.rb,uninstall.rbis not always used—many people sim-
ply delete the plugin directory without thought.

Of course, you should feel free to add any folders required by your plugin. Use
File.dirname(_ FILE _)ininit.rbto refer to your plugin’s directory as installed.
None of these files are specifically required; for example, a simple plugin may do all
of its work ininit.rb.

You can generate a plugin skeleton with a built-in Rails generator:

$ script/generate plugin my_plugin

This generates a skeleton invendor/plugins/my_pluginwith sample files, a fill-in-the-
blanks MIT license, and instructions.

Plugin Examples

To illustrate the flexibility and design of a typical Rails plugin, we will examine some
of the plugins available from the rubyonrails.org Subversion repository. Most of
these plugins are used fairly commonly; many of them are used in 37signals applica-
tions. Consider them the “standard library” of Rails. They are all available fromhttp://
svn.rubyonrails.org/rails/plugins/.

Account Location

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 exam-
ple, 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, includeAccountLocationin one or more of
your controllers, which adds the appropriate instance methods: