Module: Engines::RailsExtensions::Routing

Included in:
ActionController::Routing::RouteSet::Mapper
Defined in:
lib/engines/rails_extensions/routing.rb

Overview

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. In your plugin, you simply include a routes.rb file like the one below at the root of your plugin:

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

# add a named route
logout "/logout", :controller => "my_plugin/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.

Instance Method Summary collapse

Instance Method Details

#from_plugin(name) ⇒ Object

Loads the set of routes from within a plugin and evaluates them at this point within an application’s main routes.rb file.

Plugin routes are loaded from <plugin_root>/routes.rb.



67
68
69
70
71
72
 
# File 'lib/engines/rails_extensions/routing.rb', line 67

def from_plugin(name)
  map = self # to make 'map' available within the plugin route file
  routes_path = Engines.plugins[name].routes_path
  Engines.logger.debug "loading routes from #{routes_path}"
  eval(IO.read(routes_path), binding, routes_path) if File.file?(routes_path)
end