Merb’s routing shiznits needs some serious documentation love. Whilst I have a shot at getting some proper docpatches together here’s an overview of how to use routing in Merb 0.5.

Path Matching

The match method defines how to route requests to controllers and actions.

r.match("/contact").
  to(:controller => "info", :action => "contact")

You can define placeholder parts of the url with :symbol notation. These placeholders will be available in the params hash of your controllers. For example:

r.match("/books/:book_id/:action").
  to(:controller => "books")

The placeholders can also be referenced in the to portion of the route if necessary:

r.match("/admin/:module/:controller/:action/:id").
  to(:controller => ":module/:controller")

Named Routes

Use the name method on a route to give it a name:

r.match("/contact").
  to(:controller => "info", :action => "contact").
  name(:contact)

You can then easily reference the named route from controllers and views:

url(:contact) # => "/contact"

Namespaces

Namespacing routes with namespace is a convenient way of specifying both the :path_prefix and :name_prefix options:

r.namespace :admin do |admin|
  admin.match("/roles").
    to(:controller => "roles", :action => "index").
    name(:roles)
end

Reference a namespaced route by prefixing the route name with the namespace:

url(:admin_roles) # => "/admin/roles"

Resources

You can use Rails-like resource routing with resources:

r.resources :posts

The routes generated are named after their resources:

url(:posts)       #=> "/posts" 

@post = Post[1]
url(:post, @post) #=> "/posts/1"

You can nest resources using the same block syntax used for namespacing:

r.resources :posts do |p|
  p.resources :comments
end

To refer to a nested resource route simply use the child resource’s name. Notice in the following example there’s no need to specify the :post_id parameter as it’s automatically inferred from @comment.

url(:comment, @comment) #=> "/posts/1/comments/2"

If you prefer the Rails 2 style of namespacing nested resources simply specify the name_prefix on the child resource:

r.resources :posts do |p|
  p.resources :comments, :name_prefix => "post_" 
end