FallbackRouter¶ ↑

An Rails engine that can be used to specify fallback routing rules, which will be evaluated last (lowest priority). This is useful for catch-all routes that should execute after all other engines.

FallbackRouter has been tested on Rails 4.0, but should work on later 4.x versions as well.

Usage¶ ↑

In your Gemfile, add the engine as the LAST gem:

gem 'fallback_router', github: 'markwpiper/fallback_router'

In your routes.rb, mount the engine as the LAST entry:

mount FallbackRouter::Engine => '/'
FallbackRouter::Engine.routes.draw do
  # Your fallback routes go here.
  # Note that helpers and routes will be included in your regular application namespace / module
  # (This is because isolate_namespace is intentionally not called for this engine)
end

Routing HEAD Requests¶ ↑

Some versions of Rails 4.x require a workaround for a Rails bug with HEAD request routing when using an engine mounted at ‘/’.

In these problematic versions, implicitly generated HEAD routes are not prioritized high enough in the Rails routing table to be routed correctly, and will be accidentally routed to the mounted engine instead of the application.

To workaround this issue, call synthesize_head_routes with your application’s route set before mounting the FallbackRouter.

Rack Interactions¶ ↑

FallbackRouter will be last in the Rails precendence order, but depending on your Rack setup and middleware you have loaded, there may stil be routes provided by these plugins that are accidentally masked by FallbackRouter.

It is important to use the :constraints option on your fallback routing rules to allow these requests to get routed to the right place.

eg: To allow OmniAuth Rack middleware to still work, you might add :constraints => lambda {|request| !request.path.include?("/auth/") } to your route.

Example¶ ↑

As a full example of how to setup your application’s routes.rb, here is how to load the routes for the excellent Comfortable Mexican Sofa CMS as a fallback engine at the root of your site, and exclude mucking w/ any Rack-level Omni-auth routes:

# NOTE: You may need to call synthesize_head_routes if you are on a version of Rails that doesn't route HEAD requests correctly!
# synthesize_head_routes MyRailsProjectName::Application.routes

mount FallbackRouter::Engine => '/'
FallbackRouter::Engine.routes.draw do
  get 'cms-css/:site_id/:identifier' => 'comfy/cms/assets#render_css', :as => 'comfy_cms_render_css_path'
  get 'cms-js/:site_id/:identifier'  => 'comfy/cms/assets#render_js',  :as => 'comfy_cms_render_js_path'
  get '/:format' => 'comfy/cms/content#show', :as => 'comfy_cms_render_page_path', :path => "(*cms_path)", :constraints => lambda {|request| !request.path.include?("/auth/") }
end

Troubleshooting¶ ↑

To verify everything is setup as you expect, run rake routes and you should see that ‘Routes for FallbackRouter::Engine:’ are listed last in the list, as the lowest priority routes.