0
@@ -21,7 +21,7 @@ h3. Getting Started
0
 
0
 h3. The Basics
0
 
0
-* -"Writing Controllers":/docs/controllers.html-
0
+* "Writing Controllers":/docs/controllers.html
0
 * "Defining Routes":/docs/routes.html
0
 * "Responding to the Client":/docs/responding.html
0
 

0
@@ -5,44 +5,63 @@ filter:
0
   - erb
0
   - textile
0
 ---
0
+
0
 h2. Defining Routes
0
 
0
-One of the most peculiar parts of Halcyon is its dependency on "Merb":http://merbivore.com/, 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!*
0
+One of the most peculiar parts of Halcyon is its dependency on
0
+"Merb":http://merbivore.com/, but this is for a very good reason: Merb provides
0
+a great deal of great code that is modular and clean, perfect to implement into
0
+Halcyon. This has two affects: first, those pieces of code are very well
0
+documented by a very large and active community, and secondly is that they are
0
+continually being updated to better perform. Rewriting what Merb has already
0
+done would be silly. *So when it comes to defining routes in Halcyon, much of
0
+the documentation for defining routes in Merb still applies!*
0
 
0
-For links to various Routing documentation for Merb, jump to the bottom of the page and look under the Resources section.
0
+For links to various Routing documentation for Merb, jump to the bottom of the
0
+page and look under the Resources section.
0
 
0
 
0
 h3. Getting Started
0
 
0
-Routes are defined in @app_name/config/initialize.rb@, wherein you will find something like this by default:
0
+Routes are defined in @app_name/config/init/routes.rb@, wherein you will find
0
+something like this by default:
0
 
0
 <% coderay(:lang => "ruby", :line_numbers => "inline", :tab_width => 2) do -%>
0
-# = Required Libraries
0
-%w().each {|dep|require dep}
0
-
0
-# = Initialization
0
-class Halcyon::Application
0
-
0
-  startup do |config|
0
-    self.logger.info 'Initialize application resources and define routes in config/initialize.rb'
0
-  end
0
-
0
-  # = Routes
0
-  route do |r|
0
-    r.match('/time').to(:controller => 'application', :action => 'time')
0
-
0
-    r.match('/').to(:controller => 'application', :action => 'index')
0
-
0
-    # failover
0
-    {:action => 'not_found'}
0
-  end
0
-
0
+# = Routes
0
+Halcyon::Application.route do |r|
0
+  
0
+  # Sample route for the sample functionality in Application.
0
+  # Safe to remove!
0
+  r.match('/time').to(:controller => 'application', :action => 'time')
0
+  
0
+  # RESTful routes
0
+  # r.resources :posts
0
+  
0
+  # This is the default route for /:controller/:action/:id
0
+  # This is fine for most cases.  If you're heavily using resource-based
0
+  # routes, you may want to comment/remove this line to prevent
0
+  # clients from calling your create or destroy actions with a GET
0
+  r.default_routes
0
+  
0
+  # Change this for the default route to be available at /
0
+  r.match('/').to(:controller => 'application', :action => 'index')
0
+  # It can often be useful to respond with available functionality if the
0
+  # application is a public-facing service.
0
+  
0
+  # Default not-found route
0
+  {:action => 'not_found'}
0
+  
0
 end
0
 <% end -%>
0
 
0
-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).
0
+In the lower half you see where two routes are defined and one failover route
0
+is specified. (This failover route is actually set by default, but it is
0
+provided here as well to indicate how to update this default easily).
0
 
0
-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:
0
+Within the @route@ block, @r@ is used to define what routes to match against
0
+and where to route those requests to. Routes can be very specific or very
0
+general, accepting no or many variables in the route itself. Here are several
0
+examples to hopefully clarify the flexibility of these routes:
0
 
0
 <% coderay(:lang => "ruby", :line_numbers => "inline", :tab_width => 2) do -%>
0
 r.match('/api/:version/app_name/:controller/:action').to()
0
@@ -52,18 +71,72 @@ r.match('/time').to(:controller => 'utilities', :action => 'time')
0
 r.match('/').to(:controller => 'application', :action => 'usage')
0
 <% end -%>
0
 
0
-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 Resources section for more information.
0
-
0
-_More coming soon!_
0
+The @default_routes@ method is also one provided for by Merb and can also
0
+provide extra functionality as well as clarifies some other useful methods like
0
+@defer_to@ for conditional routes. Read below in the Links section for more
0
+information.
0
 
0
 
0
 h3. Resources
0
 
0
-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:
0
+One of the more power routing mechanics is the definition of resources which
0
+map to "REST":http://wikipedia.org/wiki/REST functionality through standard
0
+actions (discussed in the "writing controllers":/docs/controllers.html
0
+article).
0
+
0
+Defining resources' routes is trivial and the routes that are defined doing so
0
+should cover most uses of a given resource (with the ability to define extended
0
+functionality with the rest of the Merb routes API). Here's an example of
0
+defining a resource route:
0
+
0
+<% coderay(:lang => "ruby", :line_numbers => "inline", :tab_width => 2) do -%>
0
+Halcyon::Application.route do |r|
0
+  
0
+  r.resources :messages
0
+  
0
+end
0
+<% end -%>
0
+
0
+Here are the routes that get generated with this:
0
+
0
+<code><pre>
0
+GET /messages
0
+POST /messages
0
+GET /messages/:id
0
+PUT /messages/:id
0
+DELETE /messages/:id
0
+</pre></code>
0
+
0
+These effectively map to the the @list@, @create@, @show@, @update@, and
0
+@delete@ actions in the @Messages@ controller, respectively. It's important to
0
+note that the controller it expects is the camel case of the resource. It's
0
+also an acceptable (and possibly even recommended) practice to name your model
0
+the singular form, thereby having the @Message@ resource mapped to the
0
+@Messages@ resource controller. This provides a very sane mental mapping when
0
+working with the code.
0
+
0
+
0
+h3. Links
0
+
0
+Merb's API provides two very useful resources for defining routes. These two
0
+are the methods used to match paths and define how to handle those routes.
0
+These links are:
0
 
0
 * "Merb::Router::Behavior#match":http://merbivore.com/documentation/merb-core/head/index.html?a=M000787&name=match
0
 * "Merb::Router::Behavior#to":http://merbivore.com/documentation/merb-core/head/index.html?a=M000790&name=to
0
 
0
-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')@.
0
+The @Merb::Router::Behavior@ class is used to generate each route, which you
0
+will recognize it as the block parameter passed and used similar to
0
+@r.match('/').to(:controller => 'application', :action => 'index')@.
0
+
0
+Also, the "Merb::Router::Behavior#default_routes":http://merbivore.com/documentation/merb-core/head/index.html?a=M000792&name=default_routes
0
+method may be worth investigating as it handles defining common routes like
0
+@/:controller/:action/:id@ and the like.
0
+
0
+Merb provides documentation for the @resources@ route definition as well at
0
+"Merb::Router::Behavior#resources":http://merbivore.com/documentation/merb-core/head/index.html?a=M000998&name=resources.
0
+
0
+Check out these other great links as well:
0
 
0
-Also, the "Merb::Router::Behavior#default_routes":http://merbivore.com/documentation/merb-core/head/index.html?a=M000792&name=default_routes method may be worth investigating as it handles defining common routes like @/:controller/:action/:id@ and the like.
0
+* "An Introduction to Routing":http://merbunity.com/tutorials/12 at "Merbunity":http://merbunity.com/
0
+* "Routing":http://wiki.merbivore.com/pages/routing at the "Merb Wiki":http://wiki.merbivore.com/