# How to write a Rails Plugin (for controllers)

A few days back I posted my very first Rails plugin, Acts As Exportable. Although writing a plugin is rather easy, you must know a few tricks on how to get things going.

This article will show you how to develop a plugin that adds functionality to a controller (other plugins, e.g. for models) will follow later. In fact, I’ll explain to you how I developed my Acts As Exportable plugin.

Let’s take a basic Rails application for starters. You have setup a model with some attributes and a scaffolded controller that allows you to CRUD your items. In this tutorial I’ll be working with books. The model is named ‘Book’ and the controller ‘BooksController’. Start your web server now and add some random data to play with.

Before you dive into writing a plugin for the controller to export data to XML you should have some basic functionality in your controller first. I’ve found it easier to develop my code in the controller first, and then port it to a plugin.

So, add a new method to your BooksController that’ll export books to XML. This looks quite easy:

def export_to_xml
books = Book.find(:all, :order => 'title')
send_data books.to_xml,
:type => 'text/xml; charset=UTF-8;',
:disposition => "attachment; filename=books.xml"
end


Now, call /books/export_to_xml and you download a real XML file containing all your books! To make things a bit more complicated, we want to be able to feed this method some conditions to select books. A nice solution is to add a special method for this that defines these conditions. (You could also use them in listing books, for example.) I add a new method to the BooksController:

def conditions_for_collection
['title = ?', 'some title!']
end


The condition is of the same format you can feed to find. Here you could, for example, select only the books belonging to the currently logged in user.

Next, update the export_to_xml method to use these conditions

def export_to_xml
books = Book.find(:all, :order => 'title', :conditions => conditions_for_collection)
send_data books.to_xml,
:type => 'text/xml; charset=UTF-8;',
:disposition => "attachment; filename=books.xml"
end


Nice that’s it. Now, you like what you’ve made so far, and want to stuff it into a plugin and put it on your weblog. Here’s how to go about that.

## Creating the plugin

First, generate the basic code for a plugin:

./script/generate plugin acts_as_exportable


This will create a new directory in vendor/plugins containing all the basic files you need. First, we’ll take a look at vendor/plugins/acts_as_exportable/lib/acts_as_exportable.rb. This is where all the magic happens.

What we want is to is add a method to ActionControllerBase that allows you to easily enable the plugin in a certain controller. So, how do you want to activate the plugin? Right, you just call ‘acts_as_exportable’ from the controller, or optionally, you add the name of the model you want to use.

acts_as_exportable
acts_as_exportable :book


The vendor/plugins/acts_as_exportable/lib/acts_as_exportable.rb contains a module that’s named after our plugin:

module ActsAsExportable
end


Next, we add a module named ‘ClassMethods’. These class methods will be added to ActionController::Base when the plugin is loaded (we’ll take care of that in a moment), and enable the functionality described above.

module ActsAsExportable
def self.included(base)
base.extend(ClassMethods)
end

class Config

def initialize(model_id)
@model_id = model_id
@model = model_id.to_s.camelize.constantize
end

def model_name
@model_id.to_s
end
end

module ClassMethods
def acts_as_exportable(model_id = nil)
# converts Foo::BarController to 'bar' and FooBarsController
model_id = self.to_s.split('::').last.sub(/Controller$/, '').\ pluralize.singularize.underscore unless model_id @acts_as_exportable_config = ActsAsExportable::Config.\ new(model_id) include ActsAsExportable::InstanceMethods end # Make the @acts_as_exportable_config class variable easily # accessable from the instance methods. def acts_as_exportable_config @acts_as_exportable_config || self.superclass.\ instance_variable_get('@acts_as_exportable_config') end end end  So, what happened? The first method you see extends the current class (that’s every one of your controllers with the methods from the ClassMethods module). Every class now has the ‘acts_as_exportable’ method available. What does it do? The plugin automatically grabs the name of the model associated (by convention) with the controller you use, unless you specify something else. Next, we create a new configuration object that contains information about the model we’re working with. Later on this can contain more detailed information like what attributes to include or exclude from the export. Finally we include the module InstanceMethods, which we still have to define. The instance methods are only included when we enable the plugin. In our case, the instance methods include the ‘export_to_xml’ and ‘conditions_for_collection’ methods. We can simply copy/paste them into your plugin. module InstanceMethods def export_to_xml data = Book.find(:all, :order => 'title', :conditions => conditions_for_collection) send_data data.to_xml, :type => 'text/xml; charset=UTF-8;', :disposition => "attachment; filename=books.xml" end # Empty conditions. You can override this in your controller def conditions_for_collection end end  Take note that we don’t want to define any default conditions, because we don’t know what model we’re using here. By adding an empty method, the method is available and no conditions are used. Another developer can define ‘conditions_for_collection’ in his controller to override the one we write here. In the ‘export_to_xml’ there are a few changes as well. First of all, I generalized ‘books’ to ‘data’. The most important step is yet to come. We have still application specific code in your plugin, namely the Book model. This is where the Config class and @acts_as_exportable_config come in. We have added a class variable to the controller named @acts_as_exportable_config. By default, this variable is not accessable by instance methods, so we need a little work around: self.class.acts_as_exportable_config  This will call the class method ‘acts_as_exportable_config’ we defined in ClassMethods and return the value of @acts_as_exportable_config. Note that we store the configuration in each seperate controller. This allows acts_as_exportable to be used with more than one controller at the same time. With the model name made application independent, the whole plugin code looks like: module ActsAsExportable def self.included(base) base.extend(ClassMethods) end class Config attr_reader :model attr_reader :model_id def initialize(model_id) @model_id = model_id @model = model_id.to_s.camelize.constantize end def model_name @model_id.to_s end end module ClassMethods def acts_as_exportable(model_id = nil) # converts Foo::BarController to 'bar' and FooBarsController to 'foo_bar' # and AddressController to 'address' model_id = self.to_s.split('::').last.sub(/Controller$/, '').\
pluralize.singularize.underscore unless model_id

@acts_as_exportable_config = ActsAsExportable::Config.new(model_id)
include ActsAsExportable::InstanceMethods
end

# Make the @acts_as_exportable_config class variable easily
# accessable from the instance methods.
def acts_as_exportable_config
@acts_as_exportable_config || self.superclass.\
instance_variable_get('@acts_as_exportable_config')
end
end

module InstanceMethods
def export_to_xml
data = self.class.acts_as_exportable_config.model.find(:all,
:order => 'title',
:conditions => conditions_for_collection)
send_data data.to_xml,
:type => 'text/xml; charset=UTF-8;',
:disposition => "attachment; filename=\
#{self.class.acts_as_exportable_config.model_name.pluralize}.xml"
end

# Empty conditions. You can override this in your controller
def	conditions_for_collection
end
end
end


Add the following line to your BooksController and restart your web server. (Oh, and make sure to remove the export_to_xml method from the controller as well)

acts_as_exportable


Done! – Or not?

## Enabling the plugin by default

We have a very nice plugin now, but it is not loaded by default! If you take a look at your plugin directory, you’ll find a file named ‘init.rb’. This file is executed when you (re)start your web server. This is the perfect place to add our class methods to the ActionController::Base. Just add the following three lines of code to ‘init.rb’:

ActionController::Base.class_eval do
include ActsAsExportable
end


When we include our module, the ‘self.included’ method is called, and the ClassMethods module is added, thus enabling the acts_as_exportable method.

That’s all! Happy plugin writing!

Feel free to comment on this post and write about any of your own plugin (for controllers) experiences.