ColdFusion 9.0 Resources

Creating custom forms with the cfform tag

Contents [Hide]

The cfform controls
Preserving input data with the preservedata attribute
- Usage notes for the preservedata attribute
Browser considerations

The cfform tag and its CFML subtags let you create dynamic forms in three formats:

HTML

Generates standard HTML tags wherever possible, and uses applets or Flash for more complex controls, such as grids, trees, and calendars. HTML lets you present a familiar appearance, but does not let you easily separate data and presentation, or provide some of the more complex structures, such as Flash tabbed navigators or accordions, or customized XML controls.

Flash

Presents a modern, visually pleasing appearance. Flash format supports several controls, such as tabbed navigators and accordions, that are not available in HTML. Flash forms are also browser-independent. In Flash format, Flash Player works in all commonly used browsers on Windows and Macintosh systems, and in Netscape and Mozilla on Linux.

XML

Lets you specify an Extensible Stylesheet Language Transformation (XSLT) skin that converts the XML into styled HTML output. Adobe ColdFusion provides several skins that you can use, and you can write your own custom skins and support custom controls.

The cfform tag and its subtags also provide you with several methods for validating input data. For example, you can perform the validation on the browser or on the server. You can check the data type, or you can mask data input.

Individual cfform tags have additional dynamic features. Several of the tags do not have HTML counterparts, and others directly support dynamically populating the control from data sources. Also, the cfform tag preservedata attribute retains user input in a form after the user submits the form, so the data reappears if the form gets redisplayed.

The information here describes features of the cfform tag and focuses on using several of the cfform child tags that do not have HTML counterparts. For other features of ColdFusion forms that you create using the cfform tag, see the following:

The cfform controls

The following table describes the ColdFusion controls that you use in forms created using the cfform tag. You can use these tags only inside a cfform tag. Unless otherwise stated, these controls are supported in HTML, Flash, and XML skinnable forms.

Control	Description	For more information
cfapplet	Embeds a custom Java applet in the form. Not supported in Flash format forms.	Embedding Java applets.
cfcalendar	Displays an interactive Flash calendar that can be included in an HTML or Flash format form. ignored in XML skinable forms. The calendar lets a user select a date for submission as a form variable.	The cfcalendar tag in the CFML Reference
cfform	Creates a container control for organizing and formatting multiple form controls. Used in the `cfform` tag body of Flash and XML skinable forms. Ignored in HTML forms.	Creating Forms in Flash, Creating Skinnable XML Forms
cfformitem	Inserts a horizontal line, a vertical line, or formatted or unformatted text in a Flash form. Used in the `cfform` or `cfformgroup` tag body for Flash and XML forms. Ignored in HTML forms.	Creating Forms in Flash, Creating Skinnable XML Forms
cfgrid	Creates a Java applet or Flash data grid that 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.	Creating data grids with the cfgrid tag
cfinput	Equivalent to the HTML `input` tag, with the addition of input validation.	Creating a basic form
cfselect	Displays a selection box. Equivalent to the HTML `select` tag, with the addition of input validation.	Building drop-down list boxes
cfslider	Creates a Java applet-based control that lets users enter data by moving a slider. Not supported in Flash format forms.	Building slider bar controls
cftextarea	Displays a text input area. Equivalent to the HTML `textarea` tag, with the addition of input validation.	The cftextarea tag in the CFML Reference
cftree	Creates a Java applet or Flash hierarchical tree-format control that can include graphical images for the different elements. Can also generate a ColdFusion structure that represents the tree data and attributes.	Building tree controls with the cftree tag

Preserving input data with the preservedata attribute

The cfformpreservedata attribute tells ColdFusion to continue displaying the user data in a form after the user submits the form. Data is preserved in the cfinput, cfslider, cftextinput, and cftree controls and in cfselect controls populated by queries. If you specify a default value for a control, and a user overrides that default in the form, the user input is preserved.

You can retain data on the form when the same page contains the form and the form’s action code; that is, the form submits to itself. You can also retain the data if the action page has a copy of the form, and the control names are the same in the forms on both pages. (The action page form need not be identical to the initial form. It can have more or fewer elements than the initial page form; only the form elements with identical names on both pages keep their data.)

Note: The preservedata setting on the action page controls the preservation of the data.

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

<cfform action="preserve.cfm" 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 for the preservedata attribute

When you use the preservedata attribute, follow these guidelines:

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

Browser considerations

The applet-based versions of the cfgrid, cfslider, and cftree forms 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. 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 installation. Other browsers, like older versions of Netscape, require you to navigate some simple option windows.

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 can receive a JavaScript error.

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

You can use the cfform tag’s notsupported attribute to specify an alternative error message.

You can avoid browser Java and JavaScript issues with the cfgrid and cftree controls by using the Flash format versions of these controls. These controls work on Windows, Mac OS X, and Linux, and do not rely on Java support. There is no Flash version of the cfslider control, and there is no applet version of the cfcalendar control.