Effective use of Rails’ routes can help create a tidy and elegant set of URLs, and is a significant part of creating an external API for your web application.

When developing plugins which contain controllers, it seems obvious that including the corresponding routes would be extremely useful. This is particularly true when exposing RESTful resources using the new REST-ian features of Rails.

Including routes in your plugin

The engines plugin makes it possible to include a set of routes within your plugin very simply, as it turns out. Include a routes.rb file like the one below at the root of your plugin (along-side init.rb and lib/):

  connect "/login", :controller => "account", :action => "login"

  # add a named route
  logout "/logout", :controller => "account", :action => "logout"

  # some restful stuff
  resources :things do |t|
    t.resources :other_things
  end

Everywhere in a normal RAILS_ROOT/config/routes.rb file where you might have map.connect, you just use connect in your plugin‘s routes.rb.

Hooking it up in your application

While it would be possible to have each plugin‘s routes automagically included into the application‘s route set, to do so would actually be a stunningly bad idea. Route priority is the key issue here. You, the application developer, needs to be in complete control when it comes to specifying the priority of routes in your application, since the ordering of your routes directly affects how Rails will interpret incoming requests.

To add plugin routes into your application‘s routes.rb file, you need to explicitly map them in using the Engines::RailsExtensions::Routing#from_plugin method:

  ApplicationController::Routing::Routes.draw do |map|

    map.connect "/app_stuff", :controller => "application_thing" # etc...

    # This line includes the routes from the given plugin at this point, giving you
    # control over the priority of your application routes
    map.from_plugin :your_plugin

    map.connect ":controller/:action/:id"
  end

By including routes in plugins which have controllers, you can now share in a simple way a compact and elegant URL scheme which corresponds to those controllers.

The Engines::RailsExtensions::Routing module defines extensions to Rails’ routing (ActionController::Routing) mechanism such that routes can be loaded from a given plugin.

The key method is Engines::RailsExtensions::Routing#from_plugin, which can be called within your application‘s config/routes.rb file to load plugin routes at that point.