Allows you to create or install other plugins which can be "instanced" multiple times at different urls inside your app.
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Found at:

This plugin allows you to have individual route sets for other plugins, including a unique instance id. 

Without using this plugin you can specify a routes.rb in your plugins (as of rails 2.3), and these routes are merged into the global route set used when determining how to process the current request. This is great for allowing a plugin to introduce a set of functionality which exists only once on the site (like a login system).

The PluginInstances plugin is designed to enable individual instances of plugins to be placed in different places on the site. For example, lets say that your site is content managed, and has tabs across the top which link to various types of functionality:

In your application's routes.rb file:

  map.plugin_instances "/tabs/:id"

When a request is detected with a path like "/tabs/23/admin", it realises that this matches the plugin_instances route, finds the relevant instance (eg: PluginInstance.find(23)), asks that instance what plugin it represents (eg: a forum, user profile, etc), and then passes the route "/admin" to the route set for that plugin, along with the plugin instance object. Thus, a forum plugin could be written which can be instantiated at different places in the site, and just has to scope itself using the plugin instance id.


This Requires Rails 2.3.2, I aim to support future rails versions, but not previous ones. Don't even bother trying, the code which this plugin monkey patches has changed dramatically from previous versions.

Install the plugin

  script/plugin install git://

Ensure that the migration at /vendor/plugin/plugin_instances/db/migrate/ gets run. You can either copy it into your application's own migration directory, or preferable install the plugin migrations plugin at

In your environment.rb, ensure that the plugin instances plugin gets loaded before any plugins that use it. If you use plugin migrations, it needs to get loaded after that. For example:

  config.plugins = [ :plugin_migrations, :plugin_instances, :all ]

Create a route using the "plugin_instances" method in your application's routes.rb file. It follows all the normal rules for determining route priorities, but it matches all requests *starting* with the specified path.

  map.plugin_instances "/pages/:id"

Install or create plugins which use plugin instances (see below).

Plugin Development

To create a Rails plugin to for use with PluginInstances, it should have the following directory structure (plus any other normal plugin files):

             ... some controllers here
            ... some models here
            ... some views here

As you can see, this is just the normal rails application structure. Note however that controllers (and thus views) and models have been namespaced with the name of the plugin. This is to prevent name clashes between different plugins, and is generally good practice. Also, it is a convention enforced by the PluginInstances routing system.

Inside the routes.rb file for your plugin, the draw block is declared slightly differently, as follows:

    PluginInstances::RouteSetManager.routes_for('my_plugin').draw do |map|
      map.namespace :my_plugin do |my_plugin|
        my_plugin.resource :posts
      map.root :controller => 'my_plugin/posts', :action => 'show'    

As you can see, your plugin name is needed in the first line opening the draw block, as it needs to know which route set to write these routes for. Inside the block, routing works as normal, except that you'll want to declare your namespace as mentioned above. In theory, you can even use map.plugin_instances inside this block, although I haven't tried it.

Finally, all controllers in your plugins should inherit from the PluginInstances::PluginController class. For example:

    module MyPlugin
      class PostsController < PluginInstances::PluginController

        ... your actions

PluginController inherits from your application controller, so anything introduced there is still present. In addition, it introduces one instance method in particular that you will need, "plugin_instance" which returns the plugin instance model for the current request. You will need to use this model's id to scope all the data in your plugin, so that it can load different data for each instance. Everything else is up to you. :)


This plugin draws heavily on code from the excellent "desert" (MIT licensed) plugin, from Pivotal labs, although it does a different thing and both plugins should probably not be installed in the same app.


Copyright (c) 2009 Craig Ambrose, released under the MIT license