Routes Demystified

It took me a while to discover the full potential of Rails' routes. I slowly learned more and more neat stuff that made me like them more and more. They are extremely powerful and are very useful for URL re-writing. Following is all of my route knowledge. If you notice something that I didn't cover, please leave it in the comments.

A few basic routes:

            # this will route domain.com/ to the index action of your main controller
            map.connect '', :controller => 'main'
            
            # this will create a custom URL for your about-us page
            map.connect 'custom-url/about-us', :controller => 'about_us', :action => 'index'
            

Pay attention to the order of your routes in your routes.rb file. They are evaluated in order from top to bottom. Routes at the top will be used before routes at the bottom if they are too similar.

Named Routes

Instead of saying map.connect, let's get crazy and name our routes. I'll use the same routes as above and add a few.

            # you can now call this route with home_path or home_url
            map.home '', :controller => 'main'
            
            # call this route with about_us_path or about_us_url
            map.about_us 'custom-url/about-us', :controller => 'about_us', :action => 'index'
            
            # symbols in the routes define options you pass when calling the route
            # call product_details_path(:id => @product) to access this route
            map.product_details 'products/detail-view/:id', :controller => 'products', :action => 'show'
            # all-purpose route for the products controller : products_path(:action => 'search') or products_path(:action => 'buy', :id => product)
            map.products 'products/:action/:id', :controller => 'products'
            

Route Blocks Using with_options

If we have several routes for the same controller, it makes sense to use with_options to simplify the definitions.

            map.with_options :controller => 'news' do |m|
              m.news 'news-releases/list', :action => 'index' # news_path
              m.news_details 'news-releases/details/:id', :action => 'show' # news_details_path(:id => news_release)
              m.news_author 'news-releases/by-author/:name', :action => 'author' # news_author_path(:name => 'Bill')
            end
            

Better URLs with Routes

Routes are great for creating search engine friendly URLs. Supposed you'd like to add the title of your blog post to the URL.

            map.blog_details 'blog/details/:id/:title', :controller => 'blog', :action => 'show', :title => nil
            

Now you can call the blog_details path and give it the :id and :title as options for the URL. Also notice that I set :title => nil at the end of the route. This marks that option as optional for the route call.

            # this call will generate the following URL: http://domain.com/blog/details/1/My-First-Blog-Post
            # I'm using a helper method in this call entitled 'strip_chars', it is below
            blog_details_path(:id => post, :title => strip_chars(post.title)) %>
            
            # you can also omit the title when invoking the route because it is optional.
            # since your 'details' method will be using the :id parameter to find the record
            # we don't really need the title, it's just for search engines
            blog_details_path(:id => post) %>
            
            # this helper method takes a string, replaces all spaces with dashes, then strips out all non-letter, non-number, non-dashes
            # it's good for generating URL-friendly titles
            def strip_chars(string='')
              return '' if string.blank?
              string.gsub(' ','-').gsub(/[^a-z0-9\-]+/i, '')
            end
            

Caching and Pagination

If we cache our site, and certain actions show a paginated list, then we need to add the :page attribute to the route to ensure that the cache is recorded properly. After all, to our server /blog/list looks the exact same as /blog/list?page=2 when retrieving cached pages.

            map.blog 'blog/list/:page',
                     :controller => 'blog',
                     :action => 'list',
                     :requirements => {:page => /\d+/},
                     :page => nil
            # blog_path
            # blog_path(:page => 1)
            

Notice that we added something new, the :requirements option. For :page, it's a regular expression telling us the supplied value must be a number. I've also set :page => nil so that we don't always have to specify it when invoking the route.

One thing to watch out for when calling a paged route is to be careful when you're on another paged section of your site. Say I have the route above for blogs and a similar route for news releases. If I'm on the page /news/list/5 and I call blog_path it will take the :page parameter from the current URL and you'll end up on page 5 of your blog post list. Confused? Just make sure when you are calling a paged route to specify it as blog_path(:page => 1) to explicitly go to /blog/list/1 or call blog_path(:page => nil) to go to /blog/list. Both will work.

Route Conditions

Similar to RESTful routes, you can specify the method of the request with the :requirements option. While this is useful, it makes much more sense to just use map.resources to get real RESTful routes.

            map.connect 'blog-post/:id', :controller => 'blog', :action => 'show', :requirements => { :method => :get }
            map.connect 'blog-post/:id', :controller => 'blog', :action => 'update', :requirements => { :method => :post }
            
            # a GET method to /blog-post/1 will route to the 'show' action
            # a POST method to /blog-post/1 will route to the 'update' action
            

I think that's enough for normal routes. Hopefully soon I can write a post on RESTful routes, which are a whole different beast.

Tagged: routes, rails, tutorial

Leave a comment: