|
|
# 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 <tt>routes.rb</tt> file like the one below
|
|
|
# at the root of your plugin (along-side <tt>init.rb</tt> and <tt>lib/</tt>):
|
|
|
#
|
|
|
# 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 <tt>RAILS_ROOT/config/routes.rb</tt> file
|
|
|
# where you might have <tt>map.connect</tt>, you just use <tt>connect</tt> in your
|
|
|
# plugin's <tt>routes.rb</tt>.
|
|
|
#
|
|
|
# === 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 <tt>routes.rb</tt> 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 <tt>config/routes.rb</tt> file to load plugin routes at that point.
|
|
|
#
|
|
|
module Engines::RailsExtensions::Routing
|
|
|
# Loads the set of routes from within a plugin and evaluates them at this
|
|
|
# point within an application's main <tt>routes.rb</tt> file.
|
|
|
#
|
|
|
# Plugin routes are loaded from <tt><plugin_root>/routes.rb</tt>.
|
|
|
def from_plugin(name)
|
|
|
map = self # to make 'map' available within the plugin route file
|
|
|
routes_path = Engines.plugins[name].routes_path
|
|
|
eval(IO.read(routes_path), binding, routes_path) if File.file?(routes_path)
|
|
|
end
|
|
|
end
|
|
|
|
|
|
|
|
|
module ::ActionController #:nodoc:
|
|
|
module Routing #:nodoc:
|
|
|
class RouteSet #:nodoc:
|
|
|
class Mapper #:nodoc:
|
|
|
include Engines::RailsExtensions::Routing
|
|
|
end
|
|
|
end
|
|
|
end
|
|
|
end
|
|
|
|
