Using Routes

The convention for URLs in Wheels works for most situations and helps to promote an easy-to-maintain code base. With routes, you have the flexibility to break this convention when needed.

The Convention for URLs

To write clear MVC applications with ColdFusion on Wheels, we recommend sticking to conventions as much as possible. As you may already know, the convention for URLs is as follows:

http://www.domain.com/news/story/5


With this convention, the URL above tells Wheels to invoke the story action in the News controller. It also passes a parameter to the action called id, with a value of 5.

Creating Your Own Routes

But let's say that you wanted a simpler URL for your site's user profiles. What if you wanted to have a profile action in a controller called User with this URL?

http://www.domain.com/user/johndoe


Fear not, this is possible in Wheels.

Adding a New Route

Routes are configured in the file at config/routes.cfm. This is where we'll add our new user profile route.

Routes are added to Wheels using the addRoute() function. Here is how we would set up our new route using addRoute():

<cfset addRoute(name="userProfile", pattern="user/[username]", controller="user", action="profile")>


This call to addRoute() instructs Wheels to create a route named userProfile that passes a username parameter to the profile action in the User controller. This route will be invoked by any URL that starts with a top level folder of user. In most cases, a pattern in a route should begin with a unique top level folder.

As you can see, any new parameters that you want to introduce to a new route should be surrounded by square brackets [].

With this, you can create URL patterns with any level of complexity that you wish.

Using action Within Your Route

The controller and action arguments are always required in the addRoute() function. But you can still have some flexibility with the action argument.

Consider this line of code:

<cfset addRoute(name="adminUser", pattern="admin/user/[action]", controller="adminUser", action="index")>


With this pattern, a URL that begins with admin/user/ will always call the adminUser controller.

But because we have [action] within the pattern, we don't always necessarily need for the route to point to controllers/AdminUser.cfc's index() method. The action="index" parameter instructs Wheels to call the index action when one is not otherwise specified in the URL.

So now this route pattern will match for these URLs:

URL	Controller	Action
http://www.domain.com/admin/user	adminUser	index
http://www.domain.com/admin/user/index	adminUser	index
http://www.domain.com/admin/user/add	adminUser	add
http://www.domain.com/admin/user/delete	adminUser	delete

Linking to Your New Route

Now if you wanted to create a link to your new user profile action, you would use Wheels's linkTo() function like so:

#linkTo(route="userProfile", username="johndoe")#


As you can see, linkTo() accepts a route argument, which changes the function's expectations on which other arguments are passed. Because our userProfile route expects a username parameter, we would need to pass that.

Order of Precedence

With the potential of your application requiring many custom routes, you may wonder which order that Wheels considers these new routes. The answer is that Wheels gives precedence to the first listed custom route in your config/routes.cfm file.

Wheels will look through each custom route in order to see if there is a match. If not, it defaults to the default route mentioned at the beginning of this chapter under The Convention for URLs.

Example of Precedence

Let's pretend that our config/routes.cfm file looks like this:

<cfset addRoute(name="newsAdmin", pattern="admin/news/[action]"), controller="NewsAdmin", action="index">
<cfset addRoute(name="searchAdmin", pattern="admin/search/[action]", controller="SearchAdmin", action="index")>
<cfset addRoute(name="adminRoot", pattern="admin/[action]", controller="Admin", action="index")>


Wheels would make sure that the URL didn't begin with admin/news or admin/search before calling the third route listed, adminRoot.

If the URL didn't begin with admin at all, Wheels would use the default route, matching the usual pattern of [controller]/[action]/[id].

---