padrino-routing

= 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

Go to the <%= link_to 'accounts dashboard', url_for(:accounts) %> to view your accounts

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

Copyright (c) 2009 Padrino. See LICENSE for details.