linkTo()

Signature

linkTo() — returns string

Available in: controller Category: Link Functions

Description

Creates a link to another page in your application. Pass in the name of a route to use your configured routes or a controller/action/key combination. Note: Pass any additional arguments like class, rel, and id, and the generated tag will also include those values as HTML attributes.

Parameters

Name	Type	Required	Default	Description
text	string	no	—	The text content of the link.
route	string	no	—	Name of a route that you have configured in config/routes.cfm.
controller	string	no	—	Name of the controller to include in the URL.
action	string	no	—	Name of the action to include in the URL.
key	any	no	—	Key(s) to include in the URL.
params	string	no	—	Any additional parameters to be set in the query string (example: wheels=cool&x=y). Please note that Wheels uses the & and = characters to split the parameters and encode them properly for you. However, if you need to pass in & or = as part of the value, then you need to encode them (and only them), example: a=cats%26dogs%3Dtrouble!&b=1.
anchor	string	no	—	Sets an anchor name to be appended to the path.
onlyPath	boolean	no	true	If true, returns only the relative URL (no protocol, host name or port).
host	string	no	—	Set this to override the current host.
protocol	string	no	—	Set this to override the current protocol.
port	numeric	no	0	Set this to override the current port number.
href	string	no	—	Pass a link to an external site here if you want to bypass the Wheels routing system altogether and link to an external URL.
encode	any	no	true	Use this argument to decide whether the output of the function should be encoded in order to prevent Cross Site Scripting (XSS) attacks. Set it to true to encode all relevant output for the specific HTML element in question (e.g. tag content, attribute values, and URLs). For HTML elements that have both tag content and attribute values you can set this argument to attributes to only encode attribute values and not tag content.
sanitizeHref	boolean	no	false	When true, blank out caller-supplied javascript: / data: hrefs. Default false (B3: default deny is a public-behavior change).

Examples

// 1. Link to a controller/action pair
writeOutput(linkTo(text="Log Out", controller="account", action="logout"));
// -> <a href="/account/logout">Log Out</a>

// 2. Omit the controller when linking within the same controller
// (CFWheels uses the current controller automatically)
writeOutput(linkTo(text="Log Out", action="logout"));
// -> <a href="/account/logout">Log Out</a>

// 3. Link to a specific record using a key
writeOutput(linkTo(text="View Post", controller="blog", action="post", key=99));
// -> <a href="/blog/post/99">View Post</a>

// 4. Pass extra query string parameters
writeOutput(linkTo(text="View Settings", action="settings", params="show=all&sort=asc"));
// -> <a href="/account/settings?show=all&amp;sort=asc">View Settings</a>

// 5. Use a named route (configured in app/config/routes.cfm)
writeOutput(linkTo(text="Joe's Profile", route="userProfile", userName="joe"));
// -> <a href="/user/joe">Joe's Profile</a>

// 6. Link to an external URL, bypassing the routing system
writeOutput(linkTo(text="ColdFusion on Wheels", href="https://cfwheels.org/"));
// -> <a href="https://cfwheels.org/">ColdFusion on Wheels</a>

// 7. Add HTML attributes (class, id, rel, etc.) via extra arguments
writeOutput(linkTo(text="Delete Post", action="delete", key=99, class="delete", id="delete-99"));
// -> <a class="delete" href="/blog/delete/99" id="delete-99">Delete Post</a>

// 8. Include icon markup in link text; use encode="attributes" to encode
//    only attribute values and leave the tag content (the icon HTML) untouched
writeOutput(linkTo(text="<i class='fa fa-trash'></i> Delete Post", encode="attributes", action="delete", key=99));
// -> <a href="/blog/delete/99"><i class='fa fa-trash'></i> Delete Post</a>

// 9. Build an absolute URL by turning off onlyPath and setting a protocol/host
writeOutput(linkTo(text="Home", action="index", onlyPath=false, protocol="https", host="www.example.com"));
// -> <a href="https://www.example.com/home/index">Home</a>

// 10. Link to an anchor on the target page
writeOutput(linkTo(text="Jump to Comments", controller="blog", action="post", key=99, anchor="comments"));
// -> <a href="/blog/post/99#comments">Jump to Comments</a>