Linking Pages

Wheels does some magic to help you link to other pages within your app. Read on to learn why you'll rarely use an <a> tag ever again.

linkTo(), the Function for Linking to Other Pages

Wheels's built-in linkTo() function does all of the heavy lifting involved with linking the different pages of your application together. You'll generally be using linkTo() within your view code.

linkTo() accepts the following arguments:

Argument	Description
text	The text content of the link. For all intents and purposes, the blue underlined text.
confirm	Passing a message to this causes a JavaScript confirmation dialogue box to pop up containing the message.
route	If the link maps to a specific route that you have configured, pass the name here.
controller	Name of the controller to include in the link. Only needs to be specified if different than the current controller.
action	Name of the action that the link needs to point to.
key	If following the link points to a page with the conventional Wheels controller/action/key link structure, this is the value of the primary key. If the primary key is a composite key, use a comma to delimit the values.
params	Any additional parameters to set in the query string.
anchor	Sets the anchor name that needs to be appended to the path after a pound sign (#)
onlyPath	If true, returns only the relative URL (no protocol, host name or port)
host	Set this to override the current host (domain name).
protocol	Set this to override the current protocol (http).

Basic Example

As a basic example, if we wanted to link to the page that is the authors action in the blog controller, this is the code that we would write:

#linkTo(text="List of Authors", controller="blog", action="authors")#


The above code would generate this markup:

<a href="/blog/authors">List of Authors</a>


Extreme Example

If we were to use all of the parameters except for route (more on that later), our code may look something like this:

#linkTo(text="Wheels Rocks!", controller="wheels", action="rocks", key=55, params="rocks=yes&referral=cfwheels.com", anchor="rockin", host="www.securesite.com", protocol="https", onlyPath=false, confirm="Are you sure that Wheels rocks?")#


Which would generate this HTML:

<a href="https://www.securesite.com/wheels/rocks/55?rocks=yes&referral=cfwheels.com#rockin" onclick="return confirm('Are you sure that Wheels rocks?')">Wheels Rocks!</a>


Using linkTo() with Routes

Routes makes creating custom URLs outside of the wheels controller/action/key convention pretty darn easy. Refer to the Using Routes chapter for more information.

Let's say that you have this route set up in your config/routes.cfm file:

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


You can then pass the route name as the route argument of linkTo(). With this, you can also pass the username parameter that the profile route requires like so. (Pretend that we have instantiated a user object that has the fields firstName, lastName, and username.)

#linkTo(text="#user.firstName# #user.lastName#", route="profile", username=user.username)#


What If I Don't Have URL Rewriting Enabled?

Wheels will handle linking to pages without URL rewriting for you automatically. Let's pretend that you still have Wheels installed in your site root, but you do not have URL rewriting on. How you write your linkTo() call will not change:

#linkTo(text="This link still works", controller="company", action="contact", key=3)#


But Wheels will still correctly build the link markup:

<a href="/index.cfm/company/contact/3">This link still works</a>


Linking in a Subfolder Deployment of Wheels

The same would be true if you had Wheels installed in a subfolder, thus eliminating your ability to use URL rewriting. The same linkTo() code above would generate this HTML if you had Wheels installed in a subfolder called foo:

<a href="/foo/index.cfm?controller=company&action=contact&key=3">This link still works</a>


Use the linkTo() Function for Portability

An <a> tag is easy enough, isn't it? Why would we need to use a function to do this mundane task? It turns out that there are some advantages. Here's the deal.

Wheels gives you a good amount of structure for your applications. With this, instead of thinking of URLs in the "old way," we think in terms of what route, controller, and/or action we're sending the user to next.

What's more, Wheels is smart enough to build URLs for you. And it'll do this for you based on your situation with URL rewriting. Are you using URL rewriting in your app? Great. Wheels will build your URLs accordingly. Not fortunate enough to have URL rewriting capabilities in your dev or production environments? That's fine too because Wheels will handle that automatically. Are you using Wheels in a subfolder on your site, thus eliminating your ability to use URL rewriting? Wheels handles that for you too.

If you see the pattern, this gives your application a good deal of portability. For example, you could later enable URL rewriting or move your app to a different subfolder. As long as you're using linkTo() to build your links, you won't need to change anything extra to your code in order to accommodate this change.

---