- Using Forms to Display Input Data
- Using the URL Scope to Pass Parameters
- Passing Multiple Parameters in One Query String
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Using the URL Scope to Pass Parameters
Forms are an excellent way to pass parameters from one template to another when you require user input. There are many times when you need to pass nonsecure variables from one page to another without requiring user input. In this case, you can pass parameters within the URL scope.
Just as it sounds, the URL scope is the set of variables available from the URL of a given template. URL variables, or parameters, are similar to form variables in one respect: They are not available to the page on which they are set—they are available only to the page that they get passed to.
Setting a URL Variable
URL parameters are passed in the query string of a given URL. You create a query string by appending a question mark (?) to your link. They take the form parameter=value. Let's say that you have a page called SomePage.cfm. You want to pass a value to SomeActionPage.cfm. You structure your link as follows:
SomeActionPage.cfm?Parameter=Value
In the above example, SomeActionPage.cfm will receive the parameter value when the link on SomePage.cfm is clicked. Your URL variable will be available for further processing or display on SomeActionPage.cfm, but not on SomePage.cfm.
An example should quickly elucidate. Let's create these two pages and populate them with real values. In Studio, type the code in Listing 3, and save your file as SetURLParam.cfm.
Listing 3: Setting Parameters in the URL
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Untitled</title> </head> <body> Choose your favorite color: <br> <a href="URLAction.cfm?favecolor=Green">Green</a> <br> <a href="URLAction.cfm?favecolor=Red">Red</a> <br> <a href="URLAction.cfm?favecolor=Blue">Blue</a> <br> </body> </html>
You now have three links that all point to the same action page but have different parameters. Let's make an action page, URLAction.cfm, that accepts your passed URL parameter and displays it. Type the code from Listing 4 into Studio.
Listing 4: Outputting the Value of a Parameter Passed in the URL
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>URL Fave</title> </head> <body> Your favorite color is <b><cfoutput>#URL.favecolor#</cfoutput></b>. </body> </html>
When you click on a link in SetURLParam.cfm, the favecolor parameter is passed in the query string of the link to URLAction.cfm. The value of that parameter is then available to the action page as favecolor. When you reference that parameter, its value is displayed (or is available for further processing). Just like we did with form variables, we put the scoped variable inside a block of <cfoutput> tags. ColdFusion interprets the variable and assigns it the value passed.
Notice that you can reference URL parameters in the title of your document as well. Your browser will display dynamic output from ColdFusion here just as well as any other place.
NOTE
Just as a reminder that it is possible to reference your variables without their scope. We could also write <cfoutput>#favecolor#</cfoutput> in the above code, and it would work. However, because ColdFusion will look for a parameter within each scope in a predetermined order until it finds one, forgetting the scope may lead to unpredictable results. Your code will process a bit faster, too, because ColdFusion doesn't have to go looking for a variable's scope.
URL Encoded Format
URLs may not contain spaces or any nonalphanumeric characters. If you are going to pass variables through a URL, you must define your parameter string to be acceptable for use in a URL. ColdFusion provides an easy way to do this: the URLEncodedFormat function.
The URLEncodedFormat function encodes the special characters and spaces within a string into a percent sign, followed by hexadecimal (16-bit) code. Nonalphanumeric characters are replaced with equivalent hexadecimal escape sequences. Spaces are replaced with plus signs.
URL variables are browser-independent, which means that they will work on any platform. However, they sometimes work slightly differently, depending on how forgiving your browser is. For instance, Microsoft Internet Explorer will account for incorrectly formed URL query strings, if it can, and will insert the proper base 16 codes.
Netscape, on the other hand, is far stricter in its interpretation of URL parameters. I recommend that you consider using Netscape as your development browser for just this reason. If it works in Netscape, you can be usually be confident that it will work in Internet Explorer. Of course, it is prudent to test your code in a wide variety of browsers. I've just found that this practice keeps me careful about working with URL parameters.
The URLEncodedFormat function takes one argument—the string to be encoded. You can therefore use it this way:
URLEncodedFormat(someString)
Let's say that we wanted to pass a parameter whose value contained spaces or special characters. We'll write some code very similar to the favorite color code that we wrote before. However, this time we are going to choose our favorite cook. Because all of the choices of favorite cooks are first and last names, they need to contain spaces in the URL parameters in order to display correctly (with one space between the first and last names) on the action page. So, let's quickly modify our favorite color code from above as shown in Listing 5, and save it as favecook.cfm. (Note: This code will not perform reliably; we need to view it to make the point.)
Listing 5: Setting URL Parameters with Spaces in the String
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Favorite Cooks</title> </head> <body> Choose your favorite cook:<br> <a href="Action2.cfm?cook=Julia Child">Julia Child</a> <br> <a href="Action2.cfm?cook=Martha Stewart">Martha Stewart</a> <br> <a href="Action2.cfm?cook=My Dad">My Dad</a> <br> </body> </html>
We now need to create Action2.cfm to accept the cook parameter. You can easily modify URLAction to output the value of the #URL.cook# parameter, as in Listing 6.
Listing 6: You Can Sometimes Output the Value of Unencoded Parameters, Depending on Your Browser
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Fave Cooks</title> </head> <body> Your favorite cook is <b><cfoutput>#URL.cook#</cfoutput></b>. </body> </html>
Netscape would return an error stating the "the parameter is incorrect." Let's really make it tough. We'll change our code to include not only spaces, but also two special characters: ' and &.
Create a file, FaveCookBook.cfm, with the code in Listing 7.
Listing 7: Using the URLEncoded Format Function Handles the Problem
Choose your favorite cook book:<br> <cfset cookbook1 = "Julia Child & Friends"> <cfset cookbook2 = "Martha Stewart's"> <cfoutput> <a href="Action2.cfm?book=#URLEncodedFormat(cookbook1)#">Julia Child & Friends</a> <br> <a href="Action2.cfm?book=#URLEncodedFormat(cookbook2)#">Martha Stewart's</a> </cfoutput> <br>
Then create a simple action page to accept these values:
<body> Your favorite cook book is <b><cfoutput>#URL.book#</cfoutput></b>. </body>
Now, using the URLEncodedFormat function, we will pass these difficult parameters with ease to our action page. If you load this page and look in the address bar of your browser, you notice that the spaces have been replaced with %20 and the ampersand (&) has been replaced with %26. These are hexadecimal representations that your browser can read.