padrino-routing

This component provides Sinatra with an enhanced url routing system which enables named route aliases to be defined and used throughout your application to refer to urls. The benefits of this is that instead of having to hard-code route urls into every area of your application, now we can just define the urls in a single spot and then attach an alias which can be used to refer to the url throughout the rest.

Installation

To install the ‘full-stack’ padrino framework, simply grab the latest version from gemcutter:

$ sudo gem install padrino --source http://gemcutter.org

This will install the necessary padrino gems to get you started. Now you are ready to use this gem to enhance your existing Sinatra projects or build new Padrino applications.

You can also install only the padrino-routing gem for more fine-grained use:

$ sudo gem install padrino-routing --source http://gemcutter.org

Usage

Let’s take a look at how to define named route mappings:

# /app/routes/example.rb
require 'padrino-routing'

class RoutingDemo < Sinatra::Application
  register Padrino::Routing

  # Define the named route mappings
  map(:account).to("/the/accounts/:name/and/:id")
  map(:accounts).to("/the/accounts/index")

  # Configure the routes using the named alias
  get(:account)  { "name: params[:name] - id: params[:id]" }    
  get(:accounts) { "I am the body for the url /the/accounts/index" }
end

Notice we simply create a route alias using the map function and then pass in the corresponding url into the to method. You can then define the routes using the named symbol representing the url. The route aliases can be accessed using url_for

url_for(:accounts)
url_for(:account, :id => 1, :name => 'first')

You can also refer to the url in views using url_for

# /app/views/index.erb
<p>Go to the <%= link_to 'accounts dashboard', url_for(:accounts) %> to view your accounts</p>
<p>Go to account for <%= link_to 'first account', url_for(:account, :id => 1, :name => 'first') %>

Simply invoking url_for(name, *parameters) will return the full mapped url for use in links or anywhere else that the url might be required.

The routing plugin supports inline route definitions as well in which the url and the named alias are defined together within the controller:

# app/controllers/example.rb
SimpleApp.controllers do
  get :index, :map => '/index' do
    ...
  end

  get :account, :map => '/the/accounts/:name/and/:id' do
    # access params[:name] and params[:index]
  end
end

Routes defined inline this way can be accessed and treated the same way as traditional named aliases.

The routing system also supports url route configuration namespaces:

# /app/routes/example.rb
map(:admin, :show).to("/admin/:id/show")

namespace :admin do
  get :show do
    "admin show for #{params[:id]}"
  end
end

You could also define the route aliases themselves using a namespace for convenience:

# /app/routes/example.rb
map :admin do |namespace|
  namespace.map(:show).to("/admin/:id/show")
  namespace.map(:destroy).to("/admin/:id/destroy")
end

namespace :admin do
  get :show do
    "admin show for #{params[:id]}"
  end

  get :destroy do
    "admin destroy for #{params[:id]}"
  end
end

You can then reference the urls using the same url_for method:

<%= link_to 'admin show page', url_for(:admin, :show, :id => 25) %>
<%= link_to 'admin index page', url_for(:admin, :destroy, :id => 25) %>

In addition to regular namespacing, as a shortcut you can have a controller serve as a namespace as well:

 # /app/routes/admin.rb
SimpleApp.controllers :admin do
  get :index, :map => "/admin/:id/index" do
    "admin destroy for #{params[:id]}"
  end
end

This will put all named routes within this controller block into the ‘admin’ namespace and then can be referenced:

<%= link_to 'admin index page', url_for(:admin, :index, :id => 25) %>

Note that controller namespaces are simply a shortcut for standard namespaces and do not differ in any other way.

You can freely use both named route aliases and traditional Sinatra routes in the same application without any conflicts.

See the wiki article for additional information: <…WIKI…>

Copyright © 2009 Padrino. See LICENSE for details.