Creating Forms with the cfform Tag

You already learned how to use HTML forms to gather user input (see "Using Forms to Specify the Data to Retrieve"). 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
Predefined ColdFusion Java applet based controls, including trees, sliders, and grids
Custom Java applets that act as form elements

With cfform, you can access these Java applet-based controls without knowing the Java language, and you do not 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 do not have to write separate CFML code specifically for input validation, as you do in HTML forms.

Using HTML and cfform

ColdFusion generates HTML forms dynamically from cfform tags and passes through to the browser any HTML code it finds in the form. As a result, you can also do the following:

You can use the HTML form tag and form control tags in combination with the cfform tag.
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 are passed through to the HTML generated by these form tags.
You can replace your existing HTML form tags with cfform and your forms will work fine.

cfform controls

The following table describes the controls ColdFusion controls you use in forms created using cfform:

Control

Description

cfgrid
A Java applet-based control that creates a data grid you can populate from a query or by defining the contents of individual cells. You can also use grids to insert, update, and delete records from a data source.

cfslider
A Java applet-based control that defines a slider.

cfinput
Places radio buttons, check boxes, text input boxes, and password entry boxes in your form (not a Java applet).

cftree and cftreeitem
Java applet-based controls that define a tree control and individual tree control items.

cftextinput
A Java applet-based control that defines a text input box.

cfselect
Defines a drop-down list box not a Java applet).

cfapplet
Embed your own Java applets in the form.

Control	Description
cfgrid	A Java applet-based control that creates a data grid you can populate from a query or by defining the contents of individual cells. You can also use grids to insert, update, and delete records from a data source.
cfslider	A Java applet-based control that defines a slider.
cfinput	Places radio buttons, check boxes, text input boxes, and password entry boxes in your form (not a Java applet).
cftree and cftreeitem	Java applet-based controls that define a tree control and individual tree control items.
cftextinput	A Java applet-based control that defines a text input box.
cfselect	Defines a drop-down list box not a Java applet).
cfapplet	Embed your own Java applets in the form.

Preserving input data with preservedata

The cfform attribute preservedata tells ColdFusion to continue displaying the data that a user entered in the form after the user submits the form. Data is preserved in the cftext, cfslider, cftextinput, and cftree controls and in cfselect controls populated by queries. You can retain data on the form in the following circumstances:

The form and action are on a single cfml page.
The action page has a form that contains controls with the same names as the corresponding controls on the form page.

For example, if you save this form as preseve.cfm, it continues to display any text that you enter after you submit it:

<cfform action="preserve.cfm" method="POST" preservedata="Yes">

<p>Please enter your name:

<cfinput type="Text" name="UserName" required="Yes">

<p><input type="Submit" name=""> <input type="RESET">

</cfform>

Usage notes

In cftree, the preservedata attribute causes the tree to expand the tree to the previously selected element. For this to work correctly, you must also set the completePath attribute to True.
The preservedata attribute has no effect on cfgrid. If you populate the control from a query, you should update the data source with the new data (typically by using cfgridupdate) before redisplaying the grid. The grid then displays the updated database information.

Browser considerations

The applet-based controls for cfform-cfgrid, cfslider, cftextinput, and cftree-use JavaScript and Java to display their content. To allow them to display consistently across a variety of browsers, these applets use the Java plug-in, and not the browser's native Java runtime. As a result, they are independent of the level of Java support provided by the browser.

ColdFusion downloads and installs the browser plug-in if necessary. Some browsers display a single permission dialog box asking you to confirm the plug-in install. Other browsers, particularly older versions of Netscape, require you to navigate some simple option screens.

Because the controls use JavaScript to return data to ColdFusion, if you disable JavaScript in your browser it cannot properly run forms that contain these controls. In that case, the controls still display, but data return and validation does not work and you may receive a JavaScript error.

Because Java is handled by the plug-in and not directly by the browser, disabling Java execution in the browser should not affect the operation of the controls. If for some other reason, however, the browser is unable to render the controls as requested, a "notsupported" message displays in place of the control.

You can use the cfform tag's notsupported attribute to specify an alternate error message.

Developing ColdFusion Applications
Building Dynamic Forms