Building Dynamic Forms

This chapter shows you how to use the CFFORM tag to enrich your forms with sophisticated graphical controls, including several Java applet-based controls. These controls can be enabled without the need to code Java directly.

• Creating Forms with the CFFORM Tag... 124

• Input Validation with CFFORM Controls ... 126

• Input Validation with JavaScript ... 127

• Building Tree Controls with CFTREE... 129

• Structuring Tree Controls ... 132

• Embedding URLs in a CFTREE ... 134

• Creating Data Grids with CFGRID ... 135

• Creating an Updateable Grid ... 137

• Building Slider Bar Controls ... 142

• Building Text Entry Boxes ... 142

• Building Drop-Down List Boxes... 143

Creating Forms with the CFFORM Tag

You’ve already learned how to use HTML forms to gather user input. (See “Using Forms to Specify the Data to Retrieve” on page 30.) This chapter shows you how to use the CFFORM tag to create dynamic forms in CFML. In addition to HTML control types, you can use CFFORM to create forms that contain controls such as:

• Text boxes in which you can specify the appearance such as fonts and colors

• Java applet based controls, inclusing trees, sliders, and grids

• Other Java applets that act as form elements

With CFFORM, you gain the advantage of access to these Java applet-based controls without having to know the Java language, and, you don't have to juggle CFOUTPUT tags and HTML FORM tags to reference ColdFusion variables in your forms.

In addition, most CFFORM controls offer input validation attributes you can use to validate a user's entry, selection, or interaction. This means you don't have to write separate CFML code specifically for input validation as you do in HTML forms.

Using HTML in a CFFORM

You can use the HTML FORM tag in combination with the CFFORM tag. ColdFusion generates HTML forms dynamically from CFFORM tags and passes through to the browser any HTML code it finds in the form. You can use the PASSTHROUGH attribute of the CFFORM, CFINPUT, and CFSELECT tags to enter any HTML attributes that are not explicitly allowed in these tags. The attribute values will be passed through to the HTML generated by these form tags. You can also replace your existing HTML FORM tags with CFFORM and your forms will work fine.

CFFORM controls

Forms created using CFFORM use one or more of the following controls:

CFFORM Controls

Control Description

CFGRID A Java applet-based control used to create a data grid you can populate from a query or by defining the contents of individual cells. Grids can also be used to insert, update, and delete records from a data source.

CFSLIDER A Java applet-based control used to define a slider.

CFINPUT Used to place radio buttons, check boxes, text input boxes, and password entry boxes.

Chapter 10: Building Dynamic Forms 125

Improving performance with ENABLECAB

The CFFORM ENABLECAB attribute allows you to improve the performance of Java- applet based CFFORM controls. When you use ENABLECAB, ColdFusion prompts the end user to accept a download of the Java classes needed for the CFFORM controls that use them. CAB files are digitally signed using VeriSign digital IDs to ensure file security.

Note

The ENABLECAB attribute is supported only for MS Internet Explorer clients that have Authenticode 2.0 installed. Authenticode 2.0 can be downloaded from http://www.microsoft.com/Windows/ie/security/ authent2.asp.

Browsers that disable Java

Since each of the Java applet-based controls, CFGRID, CFSLIDER, CFTEXTINPUT, and CFTREE require a Java applet to run, browsers that do not support Java or that have disabled Java execution will not execute the forms that contain these controls. Using the NOTSUPPORTED attribute, ColdFusion allows you to present an error message rather than the blank applet space that appears in the browser. This attribute is available in each of the Java applet-based controls as well as the CFAPPLET tag. You use NOTSUPPORTED to specify the message you want to appear, formatted as HTML, when an application page is loaded by a browser that does not support Java.

CFTREE and CFTREEITEM

Java applet-based controls used to define a tree control and individual tree control items.

CFTEXTINPUT A Java applet-based control used to define a text input box. CFSELECT Used to define a drop-down list box.

CFAPPLET Used to embed your own Java applets.

CFFORM Controls (Continued) Control Description

Input Validation with CFFORM Controls

The CFINPUT and CFTEXTINPUT tags include the VALIDATE attributes which allows you to specify a valid data type entry for the control. You can validate user entries on the following data types.

When you specify an input type in the VALIDATE attribute, ColdFusion tests for the specified input type when the form is submitted and submits form data only on a successful match. A true value is returned on successful form submission, false if validation fails.

Input Validation Controls

VALIDATE Entry Description

Date Verifies US date entry in the form mm/dd/yyy.

Eurodate Verifies valid European date entry in the form dd/mm/ yyyy.

Time Verifies a time entry in the form hh:mm:ss.

Float Verifies a floating point entry.

Integer Verifies an integer entry.

Telephone Verifies a telephone entry. Telephone data must be entered as ###-###-####. The hyphen separator (-) can be replaced with a blank. The area code and exchange must begin with a digit between 1 and 9.

Zipcode (U.S. formats only) Number can be a 5-digit or 9-digit zip in the form #####-####. The hyphen separator (-) can be replaced with a blank.

Creditcard Blanks and dashes are stripped and the number is verified using the mod10 algorithm.

Social_security_number Number must be entered as ###-##-####. The hyphen separator (-) can be replaced with a blank.

Chapter 10: Building Dynamic Forms 127

Input Validation with JavaScript

In addition to native ColdFusion input validation using the VALIDATE attribute of the CFINPUT and CFTEXTINPUT tags, the following tags support the ONVALIDATE attribute , which allows you to specify a JavaScript function to handle your CFFORM input validation:

• CFINPUT

• CFSLIDER

• CFTEXTINPUT

• CFTREE

JavaScript objects passed to the validation routine

The following JavaScript objects are passed by ColdFusion to the JavaScript function you specify in the ONVALIDATE attribute:

• form_object

• input_object

• object_value

Handling failed validation

The ONERROR attribute allows you to specify a JavaScript function you want to execute in the event of a failed validation. For example, if you specify a JavaScript function to handle input validation in the ONVALIDATE attribute you can also specify a JavaScript function in the ONERROR attribute to handle a failed validation, which returns a false value. ONERROR is available in the following CFFORM tags:

• CFINPUT

• CFSELECT

• CFSLIDER

• CFTEXTINPUT

• CFTREE

When you specify a JavaScript routine in the ONERROR attribute, ColdFusion passes the following JavaScript objects to the specified routine:

• form_object

• input_object

• object_value

To use JavaScript to validate form data:

1. Create a new file in Studio.

2. Edit the page so that it appears as follows: <HTML> <HEAD> <TITLE>JavaScript Validation</TITLE> 4 <SCRIPT>  </SCRIPT> </HEAD> <BODY>

<H2>JavaScript validation test</H2> <P>Please enter your email address:</P> <CFFORM NAME="UpdateForm" ACTION="update.cfm" > <CFINPUT TYPE="text" NAME="inputbox1" REQUIRED="YES" 4 ONVALIDATE="testbox"

MESSAGE="Sorry, invalid entry." SIZE="10"

MAXLENGTH="10">

</BODY> </HTML>

3. Save the page as validjs.cfm. 4. View validjs.cfm in your browser.

When you enter an invalid email address, an error appears. Even if you enter a valide email address, and Error 404 appears because you haven’t created the action page update.cfm.

Chapter 10: Building Dynamic Forms 129

Code Review

See the following Web site for information on JavaScript validation scripts:

• http://www.dannyg.com/javascript

Building Tree Controls with CFTREE

The CFTREE form lets you display hierarchical information in a space-saving collapsible tree populated from data source queries. To build a tree control with CFTREE, you use individual CFTREEITEM tags to populate the control. You can specify one of six built-in icons to represent individual items in the tree control.

To create and populate a tree control from a query:

1. Open a new file named tree1.cfm in Studio. 2. Modify the page so that it appears as follows:

<CFQUERY NAME="engquery" DATASOURCE="CompanyInfo"> SELECT FirstName + ’ ’ + LastName AS FullName FROM EMPLOYEES

</CFQUERY>

JavaScript code to test for valid entry in text box.

ONVALIDATE="testbox" Text box control parameter that calls the JavaScript test.

4 QUERY="engquery" 4 QUERYASROOT="yes" 4 IMG="folder,document"> 4 </CFTREE>

</CFFORM>

3. Save the page and view it in your browser.

Code Review

Grouping output from a query

In a similar query, you may want to organize your employees by the department. In this case, you separate column names with commas in the CFTREEITEM VALUE attribute

To organize the tree based on ordered results of a query:

1. Open a new file named tree2.cfm in Studio. 2. Modify the page so that it appears as follows:

<CFQUERY NAME="deptquery" DATASOURCE="CompanyInfo"> SELECT Department_ID, FirstName + ’ ’ + LastName AS FullName

FROM EMPLOYEES

ORDER BY Department_ID </CFQUERY>

Code Description

<CFTREE NAME="tree1" Create a tree and name it tree1. REQUIRED="yes" Specify that a user must select

an item in the tree.

HSCROLL="no" Don’t allow horizontal scrolling. VSCROLL="yes"> Allow vertical scrolling. <CFTREEITEM VALUE=FullName

QUERY="engquery"

Create an item in the tree and put the results of the query named engquery in it.

QUERYASROOT="yes" Specify the query name as the root level of the tree control. IMG="folder,document" Use the images "folder" and

"document" that ship with ColdFusion in the tree structure.

Chapter 10: Building Dynamic Forms 131

<CFTREEITEM VALUE="Department_ID, FullName" QUERY="deptquery"

QUERYASROOT="Department_ID" IMG="cd,folder">

</CFTREE>

3. Save the page and view it in your browser.

Code Review

Note that the comma-separated items in the IMG and the VALUE attributes

correspond. If you leave out the IMG attribute, ColdFusion uses the folder image for all levels in the tree.

CFTREE form variables

The CFTREE tag allows you to force a user to select an item from the tree control by setting the REQUIRED attribute to YES. With or without the REQUIRED attribute, ColdFusion passes two form variables to the application page specified in the CFTREE ACTION attribute:

• form.treename.node — Returns the node of the user selection.

Code Description

ORDER BY Department_ID Order the query results by department. <CFTREEITEM

VALUE="Department_ID, FullName"

Popluate the tree with the Department ID, and under each department, the Full Name for each employee in the department

QUERYASROOT="Department_ID" Make the Department ID the root of the tree IMG="cd,folder"> Use the ColdFusion-supplied images CD and

• form.treename.path — Returns the complete path of the user selection, in the form: root\node1\node2\node_n\value

The root part of the path is only returned if you set the COMPLETEPATH attribute tof CFTREE to YES; otherwise, the path value starts with the first node.

In the previous example, if the user selects the name "John Allen" in this tree, the following form variables are returned by ColdFusion:

form.tree1.node = John Allen

form.tree1.path = Department_ID\3\John Allen

You can specify the backslash character used to delimit each element of the path form variable in the CFTREE DELIMITER attribute.

Input validation

Although, the CFTREE does not include a VALIDATE attribute, you can use the REQUIRED attribute to force a user to select an item from the tree control. In addition, you can use the ONVALIDATE attribute to specify the JavaScript code to perform validation.

Structuring Tree Controls

Tree controls built with CFTREE can be very complex. Knowing how to specify the relationship between multiple CFTREEITEM entries will help you handle even the most labyrinthine of CFTREE constructs.

Note

The following tree examples all use the result set from folllowing query. To run any of the tree examples, insert the query into your test template:

<CFQUERY NAME="deptquery" DATASOURCE="CompanyInfo"> SELECT Department_ID, FirstName + ’ ’ + LastName AS FullName

FROM EMPLOYEES

ORDER BY Department_ID </CFQUERY>

Example: One-level tree control

This example consists of a single root and a number of individual items: <CFFORM NAME="form1" ACTION="submit.cfm">

<CFTREEITEM VALUE="FullName" QUERY="deptquery"

QUERYASROOT="Department"> </CFTREE>

Chapter 10: Building Dynamic Forms 133

Example: Multi-level tree control

When populating a CFTREE, you manipulate the structure of the tree by specifying a TREEITEM parent. In this example, every TREEITEM, except the top level, specifies a parent. The PARENT attribute allows your CFTREE to show the relationships between elements in the tree control.

<CFTREEITEM VALUE="Divisions"> <CFTREEITEM VALUE="Development"

PARENT="Divisions" IMG="folder"> <CFTREEITEM VALUE="Product One"

PARENT="Development">

<CFTREEITEM VALUE="GUI"

PARENT="Product Two" IMG="document"> <CFTREEITEM VALUE="Kernel"

PARENT="Product Two" IMG="document"> <CFTREEITEM VALUE="Product Three"

PARENT="Development"> <CFTREEITEM VALUE="QA"

PARENT="Divisions" IMG="folder"> <CFTREEITEM VALUE="Product One"

PARENT="QA">

<CFTREEITEM VALUE="Product Two" PARENT="QA"> <CFTREEITEM VALUE="Product Three"

PARENT="QA">

<CFTREEITEM VALUE="Support"

PARENT="Divisions" IMG="fixed"> <CFTREEITEM VALUE="Product Two"

PARENT="Support"> <CFTREEITEM VALUE="Sales" PARENT="Divisions" IMG="cd"> <CFTREEITEM VALUE="Marketing" PARENT="Divisions" IMG="document"> <CFTREEITEM VALUE="Finance" PARENT="Divisions" IMG="element"> </CFTREE> </CFFORM>

Image names in a CFTREE

When you use the TYPE="Image" attribute, ColdFusion attempts to display an image corresponding to the value in the column, which can be a built-in ColdFusion image name, or an image of your choice in the cfide\classes directory or subdirectory, referenced with a relative URL.

The built-in image names are: • cd • computer • document • element • folder • floppy • fixed • remote

Embedding URLs in a CFTREE

The HREF attribute in the CFTREEITEM tag allows you to designate tree items as links. To use this feature in a CFTREE, you simply define the destination of the link in the HREF attribute of CFTREEITEM.

To embed links in a CFTREE:

1. Open a new file named tree3.cfm in Studio. 2. Modify the page so that it appears as follows:

<CFTREEITEM VALUE="Important Links"> <CFTREEITEM VALUE="Allaire Home"

PARENT="Important Links" IMG="document"

4 HREF="http://www.allaire.com">

<CFTREEITEM VALUE="Allaire Forums" PARENT="Important Links" IMG="document"

4 HREF="http://forums.allaire.com"> </CFTREE>

</CFFORM>

Chapter 10: Building Dynamic Forms 135

Code Review

Specifying which tree items to send to the action page

When a user selects a tree item and submits the form, the CFTREEITEMKEY variable is appended to the URL passed to the application page specified in the CFFORM ACTION attribute, in the form:

http://myserver.com?CFTREEITEMKEY=selected_value

You can disable this key by setting the APPENDKEY attribute in the CFTREE tag to No.

Creating Data Grids with CFGRID

The CFGRID tag allows you to build CFFORM grid controls. A grid control resembles a spreadsheet table and can contain data populated from a CFQUERY or from other sources of data. As with other CFFORM tags, CFGRID offers a wide range of data formatting options as well as the option of validating user selections with a JavaScript validation script.

You can also do the following with CFGRID:

• Sort data in the grid alphanumerically

• Update , insert and delete data

• Embed images in the grid

When users select grid data and submit the form, ColdFusion passes the selection information as form variables to the application page specified in the CFFORM ACTION attribute.

Just as the CFTREE tag uses CFTREEITEM, CFGRID uses the CFGRIDCOLUMN tag. You define a wide range of row and column formatting options, as well as a query name, selection options, and so on. You use the CFGRIDCOLUMN tag to define individual columns in the grid.

Code Description

HREF="http://www.allaire.com"> Make the node of the tree a link. HREF="http://forums.allaire.com" Make the node of the tree a link.

Note HREF can refer to the name of a column in a query if the tree item is populated from that query.

Populating a grid from a query

To populate a grid from a query:

1. Open a new file named grid1.cfm in Studio. 2. Edit the file so that it appears as follows:

<CFQUERY NAME="empdata" DATASOURCE="CompanyInfo"> SELECT * FROM Employees

</CFQUERY>

<CFFORM NAME="Form1" ACTION="submit.cfm" METHOD="Post"> <CFGRID NAME="employee_grid" QUERY="empdata"

SELECTMODE="single">

Note

Use the CFGRIDCOLUMN DISPLAY="No" attribute to hide columns you want to retrieve from a data source but not expose to an end

In document Developing Web Applications with ColdFusion (Page 149-175)

Contents

Creating Forms with the CFFORM Tag

Using HTML in a CFFORM

CFFORM controls

Improving performance with ENABLECAB

Note

Browsers that disable Java

Input Validation with CFFORM Controls

Input Validation with JavaScript

JavaScript objects passed to the validation routine

Handling failed validation

Code Review

Building Tree Controls with CFTREE

Code Review

Grouping output from a query

Code Review

CFTREE form variables

Input validation

Structuring Tree Controls

Note

Example: One-level tree control

Example: Multi-level tree control

Image names in a CFTREE

Embedding URLs in a CFTREE

Code Review

Specifying which tree items to send to the action page

Creating Data Grids with CFGRID

Populating a grid from a query

Note