Developing ColdFusion MX Applications with CFML
Building Dynamic Forms

Creating forms with the cfform tag

You already learned how to use HTML forms to gather user input (see Chapter 26, "Retrieving and Formatting Data"). This chapter shows you how to use the cfform tag to create dynamic forms in CFML. In addition to standard HTML form controls, the cfform tag allows you to create forms that contain the following controls:

• Text boxes in which you can specify the appearance, such as fonts and colors
• Text inputs that allow you to validate the data entered into the control
• Predefined ColdFusion Java applet based controls, including trees, sliders, and grids
• Custom Java applets that act as form elements

Most cfform controls offer input validation attributes that you can use to validate user 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 dynamically generates HTML forms from cfform tags and passes to the browser any HTML code that it finds in the form. As a result, you can also do the following:

• 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.
• ColdFusion passes to the action page of the cfform the variable Form.fieldnames which contains the names of the form fields submitted from the form.

The cfform controls

The following table describes the ColdFusion controls that you use in forms created using cfform. You can use these tags only inside a cfform tag.

Control	Description	For more information
cfgrid	Java applet-based control that creates a 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 cfgrid".
cfslider	Java applet-based control that defines a slider.	"Building slider bar controls".
cfinput	Places radio buttons, check boxes, text input boxes, and password entry boxes. Equivalent to the HTML input tag with the addition of input validation.	"Input validation with cfform controls".
cftree	Java applet-based controls that define a tree control and individual tree control items.	"Building tree controls with cftree".
cftextinput	Java applet-based control that defines a text input box.	"Building text input boxes".
cfselect	Drop-down list box not a Java applet). Equivalent to the HTML select tag with the addition of input validation and data binding.	"Building drop-down list boxes".
cfapplet	Embed your own Java applets in the form.	"Embedding Java applets".

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 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 form's action posts to the same ColdFusion page as the form itself, and the control names are the same.

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 using the preservedata attribute, follow these guidelines:

• 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 must 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. 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 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 "notsupported" message appears in place of the control.

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

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments