View comments | RSS feed
Developing ColdFusion MX Applications with CFML Previous Up One Level Next
Retrieving and Formatting Data


Working with action pages

A ColdFusion action page is just like any other application page except that you can use the form variables that are passed to it from an associated form. The following sections describe how to create effective action pages.

Processing form variables on action pages

The action page gets a form variable for every form control that contains a value when the form is submitted.

Note:   If multiple controls have the same name, one form variable is passed to the action page with a comma-delimited list of values.

A form variable's name is the name that you assigned to the form control on the form page. Refer to the form variable by name within tags, functions, and other expressions on an action page.

Because form variables extend beyond the local page-their scope is the action page-prefix them with "Form." to explicitly tell ColdFusion that you are referring to a form variable. For example, the following code references the LastName form variable for output on an action page: 

<cfoutput>

  #Form.LastName#
</cfoutput>

The Form scope also contains a list variable called Form.fieldnames. It contains a list of all form variables submitted to the action page. If no form variables are passed to the action page, ColdFusion does not create the Form.fieldnames list.

Dynamically generating SQL statements

As described in previous chapters, you can retrieve a record for every employee in a database table by composing a query like the following: 

<cfquery name="GetEmployees" datasource="CompanyInfo">  

  SELECT  FirstName, LastName, Contract
  FROM   Employee
</cfquery>

But when you want to return information about employees that matches user search criteria, you use the SQL WHERE clause with a SQL SELECT statement. When the WHERE clause is processed, it filters the query data based on the results of the comparison.

For example, to return employee data for only employees with the last name of Smith, you build a query that looks like the following: 

<cfquery name="GetEmployees" datasource="CompanyInfo">  

  SELECT FirstName, LastName, Contract
  FROM    Employee
  WHERE  LastName = 'Smith'
</cfquery>

However, instead of putting the LastName directly in the SQL WHERE clause, you can use the text that the user entered in the form for comparison: 

<cfquery name="GetEmployees" datasource="CompanyInfo">

  SELECT FirstName, LastName, Salary
  FROM Employee
  WHERE LastName=<cfqueryparam value="#Form.LastName#" 
CFSQLType="CF_SQL_VARCHAR"> 
</cfquery>

For security, this example encapsulates the form variable within the cfqueryparam tag to ensure that the user passed a valid string value for the LastName. For more information on using the cfqueryparam tag with queries and on Dynamic SQL, see Chapter 20, "Accessing and Retrieving Data".

Creating action pages

Use the following procedure to create an action page for the page formpage.cfm that you created in the previous example.

To create an action page for the form:

  1. Create a ColdFusion page with the following content: 
    <html>
<head>
<title>Retrieving Employee Data Based on Criteria from Form</title>
</head>

<body>
<cfquery name="GetEmployees" datasource="CompanyInfo">
  SELECT FirstName, LastName, Salary
  FROM Employee
  WHERE LastName=<cfqueryparam value="#Form.LastName#" 
CFSQLType="CF_SQL_VARCHAR">
</cfquery>
<h4>Employee Data Based on Criteria from Form</h4>
<cfoutput query="GetEmployees">
#FirstName#
#LastName#
#Salary#<br>
</cfoutput>
<br>
<cfoutput>Contractor: #Form.Contractor#</cfoutput>
</body>
</html>
  2. Save the page as actionpage.cfm within the myapps directory.
  3. View formpage.cfm in your browser.
  4. Enter data, for example, Smith, in the Last Name box and submit the form.

    The browser displays a line with the first and last name and salary for each entry in the database that match the name you typed, followed by a line with the text "Contractor: Yes"

  5. Click Back in your browser to redisplay the form.
  6. Remove the check mark from the check box and submit the form again.

    This time an error occurs because the check box does not pass a variable to the action page. For information on modifying actionpage.cfm to fix the error, see "Testing for a variable's existence".

Reviewing the code

The following table describes the highlighted code and its function:
Code
Description
 
<cfquery name="GetEmployees"
datasource="CompanyInfo">
Queries the data source CompanyInfo and names the query GetEmployees.
 
SELECT FirstName, LastName, Salary
FROM Employee
WHERE LastName=<cfqueryparam
	value="#Form.LastName#" 
	CFSQLType="CF_SQL_VARCHAR">
Retrieves the FirstName, LastName, and Salary fields from the Employee table, but only if the value of the LastName field matches what the user entered in the LastName text box in the form on formpage.cfm.
 
<cfoutput query="GetEmployees">
Displays results of the GetEmployees query.
 
#FirstName#
#LastName#
#Salary#<br>
Displays the value of the FirstName, LastName, and Salary fields for a record, starting with the first record, then goes to the next line. Keeps displaying the records that match the criteria you specified in the SELECT statement, followed by a line break, until you run out of records.
 
</cfoutput>
Closes the cfoutput block.
 
<br>
<cfoutput>Contractor: #Form.Contractor#
</cfoutput>
Displays a blank line followed by the text Contractor: and the value of the form Contractor check box.
A more complete example would test to ensure the existence of the variable and would use the variable in the query.

Testing for a variable's existence

Before relying on a variable's existence in an application page, you can test to see if it exists using the ColdFusion IsDefined function. A function is a named procedure that takes input and operates on it. For example, the IsDefined function determines whether a variable exists. CFML provides a large number of functions, which are documented in CFML Reference.

The following code prevents the error in the previous example by checking to see if the Contractor Form variable exists before using it: 

<cfif IsDefined("Form.Contractor")>
<cfoutput>Contractor: #Form.Contractor#</cfoutput>

</cfif>

The argument passed to the IsDefined function must always be enclosed in double quotation marks. For more information on the IsDefined function, see CFML Reference.

If you attempt to evaluate a variable that you did not define, ColdFusion cannot process the page and displays an error message. To help diagnose such problems, turn on debugging in the ColdFusion MX Administrator. The Administrator debugging information shows which variables are being passed to your application pages.

Requiring users to enter values in form fields

One of the limitations of HTML forms is the inability to define input fields as required. Because this is a particularly important requirement for database applications, ColdFusion provides a server-side mechanism for requiring users to enter data in fields.

To require entry in an input field, use a hidden field that has a name attribute composed of the field name and the suffix "_required." For example, to require that the user enter a value in the FirstName field, use the following syntax: 

<input type="hidden" name="FirstName_required">

If the user leaves the FirstName field empty, ColdFusion rejects the form submittal and returns a message informing the user that the field is required. You can customize the contents of this error message using the value attribute of the hidden field. For example, if you want the error message to read "You must enter your first name." use the following syntax: 

<input type="hidden" 
  name="FirstName_required"
  value="You must enter your first name.">

Form variable notes and considerations

When using form variables, keep the following guidelines in mind:

Previous Up Next

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments


dwhatley said on Oct 23, 2003 at 11:23 AM :
Good Day,

What does this really mean?
Note: If multiple controls have the same name, one form variable is passed to the action page with a comma-delimited list of values.

I have created a form with the following
<input type="checkbox" name="RegFieldList" value="f0">
<input type="checkbox" name="RegFieldList" value="f1">
<input type="checkbox" name="RegFieldList" value="f2">

I have created a field named RegFieldList in my database.

This is going to be my new form, but I am not sure if this is right.
<cfif ListFind(RegFieldList,"f0")>
<input type="checkbox" name="RegFieldList" value="f0" <cfif ConferenceFields.RegFieldList is 1> checked</cfif>>

<input type="text" name="MiddleInitial" maxlength="2" value="" size="2">

Now how should my action page look?
Should I have an update query or a select query. My boss wants me to use the ListFind or ListGetAt functions. I don't know what to do can you help me.

Basically the user selects all the checkboxes that are necessary on the form page. Then I need those fields that are checked to be confirmed and appear on the new form page.

Thank you very much for helping me.
bizarrojack said on Jun 8, 2004 at 10:42 AM :
(sorry about the previous comment, I thought the comments were still part of the account registration process; it has nothing to do with htis page and hopefully can be deleted)

What I meant to say:
"What does this really mean?
Note: If multiple controls have the same name, one form variable is passed to the action page with a comma-delimited list of values."

suppose you have inputs like this:
<input type=text name="textvar" value="text1">
<input type=text name="textvar" value="text2">
<input type=text name="textvar" value="text3">

It means that this will be true:
FORM.textvar eq "text1,text2,text3"

It would have been much nicer if it came in as an array instead of a list; Its very easy to screw up and requires extra code to use this properly when using your own data, and practically impossible to take user-supplied text in this way. This is because the list deliimiter is a comma and therefore you must be sure that there is no commas in your data.

name=onevar value="text foo"
name=onevar value="foo, bar baz"
name=onevar value="foobar"

This will appear as 4 items in FORM.onevar, whether you want it to work that way or not. In a situation where a user isn't inputting data, it is still important to be certain that the data being used does not contain commas.

Some other languages read these values into an array on submission, so be sure if CF is not your first language that you take this for granted.
bizarrojack said on Jun 8, 2004 at 10:47 AM :
For more info on how to deal with identically named controls, be familiar with the list functions, or consider choosing not to re-use names for controls.

http://livedocs.macromedia.com/coldfusion/6/CFML_Reference/functions-pt016.htm#1099435

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/Developing_ColdFusion_MX_Applications_with_CFML/formatData3.htm