Halcyon

Notice: The website is currently being udpated. Sorry for any inconvenience.

Defining Routes

One of the most peculiar parts of Halcyon is its dependency on
Merb, but this is for a very good reason: Merb provides
a great deal of great code that is modular and clean, perfect to implement into
Halcyon. This has two affects: first, those pieces of code are very well
documented by a very large and active community, and secondly is that they are
continually being updated to better perform. Rewriting what Merb has already
done would be silly. So when it comes to defining routes in Halcyon, much of
the documentation for defining routes in Merb still applies!

For links to various Routing documentation for Merb, jump to the bottom of the
page and look under the Resources section.

Getting Started

Routes are defined in app_name/config/init/routes.rb, wherein you will find
something like this by default:

 1 # = Routes
 2 Halcyon::Application.route do |r|
 3   
 4   # Sample route for the sample functionality in Application.
 5   # Safe to remove!
 6   r.match('/time').to(:controller => 'application', :action => 'time')
 7   
 8   # RESTful routes
 9   # r.resources :posts
10   
11   # This is the default route for /:controller/:action/:id
12   # This is fine for most cases.  If you're heavily using resource-based
13   # routes, you may want to comment/remove this line to prevent
14   # clients from calling your create or destroy actions with a GET
15   r.default_routes
16   
17   # Change this for the default route to be available at /
18   r.match('/').to(:controller => 'application', :action => 'index')
19   # It can often be useful to respond with available functionality if the
20   # application is a public-facing service.
21   
22   # Default not-found route
23   {:action => 'not_found'}
24   
25 end

In the lower half you see where two routes are defined and one failover route
is specified. (This failover route is actually set by default, but it is
provided here as well to indicate how to update this default easily).

Within the route block, r is used to define what routes to match against
and where to route those requests to. Routes can be very specific or very
general, accepting no or many variables in the route itself. Here are several
examples to hopefully clarify the flexibility of these routes:

1 r.match('/api/:version/app_name/:controller/:action').to()
2 r.match('/:controller/:action/:id').to()
3 r.match('/:controller/:action').to()
4 r.match('/time').to(:controller => 'utilities', :action => 'time')
5 r.match('/').to(:controller => 'application', :action => 'usage')

The default_routes method is also one provided for by Merb and can also
provide extra functionality as well as clarifies some other useful methods like
defer_to for conditional routes. Read below in the Links section for more
information.

Resources

One of the more power routing mechanics is the definition of resources which
map to REST functionality through standard
actions (discussed in the writing controllers
article).

Defining resources’ routes is trivial and the routes that are defined doing so
should cover most uses of a given resource (with the ability to define extended
functionality with the rest of the Merb routes API). Here’s an example of
defining a resource route:

1 Halcyon::Application.route do |r|
2   
3   r.resources :messages
4   
5 end

Here are the routes that get generated with this:

<pre> GET /messages POST /messages GET /messages/:id PUT /messages/:id DELETE /messages/:id </pre>

These effectively map to the the list, create, show, update, and
delete actions in the Messages controller, respectively. It’s important to
note that the controller it expects is the camel case of the resource. It’s
also an acceptable (and possibly even recommended) practice to name your model
the singular form, thereby having the Message resource mapped to the
Messages resource controller. This provides a very sane mental mapping when
working with the code.

Links

Merb’s API provides two very useful resources for defining routes. These two
are the methods used to match paths and define how to handle those routes.
These links are:

The Merb::Router::Behavior class is used to generate each route, which you
will recognize it as the block parameter passed and used similar to
r.match('/').to(:controller => 'application', :action => 'index').

Also, the Merb::Router::Behavior#default_routes
method may be worth investigating as it handles defining common routes like
/:controller/:action/:id and the like.

Merb provides documentation for the resources route definition as well at
Merb::Router::Behavior#resources.

Check out these other great links as well: