CFFORM |
Description
Builds a form with CFML custom control tags; these provide more functionality than standard HTML form input elements.
Category
Forms tags

Syntax

    <cfform
       name = "name"
       action = "form_action"
       preserveData = "Yes" or "No"
       onSubmit = "javascript"
       target = "window_name"
       encType = "type"
       passThrough = "HTML_attribute(s)"
       codeBase = "URL"
       archive = "URL"
       scriptSrc = "path"
       standard HTML attributes>
    ...
    </cfform>

See also
cfapplet, cfgrid, cfinput, cfselect, cfslider, cftextinput, cftree, cftreeitem
History

ColdFusion MX:

- Deprecated the enableCAB attribute. It might not work, and might cause an error, in later releases.
- Changed the name and action attributes to optional.

In addition to the listed attributes, you can use the following HTML attributes in the cfform tag. The tag does not use these attributes, but includes them in the form tag that it generates and returns to the browser:

- class
- enctype
- id
- onReset
- style
- target

Usage
This tag requires an end tag.

Some custom control tags that you can use within this tag require the client to download a Java applet; they might execute slightly more slowly than using an HTML form element to get the same information. In addition to regular HTML form elements, you can use the following custom control tags within the cfform tag:

- cfinput Creates and validates an input element (radio button, text box, check box)
- cfselect Creates a drop-down list box
- cfslider Creates a slider control (Java support required)
- cftextinput Creates a text input box (Java support required)
- cftree Creates a tree control (Java support required)
- cfgrid Creates a grid control to display tabular data (Java support required)
- cfapplet Embeds a registered Java applet (Java support required)

All of these control tags require that the browser is JavaScript-enabled.
If you use this tag after the cfflush tag on a page, an error is thrown.
The method attribute is automatically set to post; if you specify a value, it is ignored.
If you specify a value in quotation marks, you must escape them by doubling them; for example: passThrough = "readonly = ""Yes"" ".

Any form field name, from the cfform tag or an HTML form, that ends in one of the following suffixes invokes server-side form validation:

- _integer Verifies that the user entered a number.
- _float Verifies that the user entered a number.
- _range Verifies that a numeric value entered is within specified boundaries.
- _date Verifies that the user entered a date; converts to ODBC date format.
- _time Verifies that the user correctly entered a time; converts to ODBC time format.
- _eurodate Verifies that the user entered a date in a standard European date format; converts to ODBC date format.

Do not use these suffixes for your field names.
For more information, see Chapter 26, "Retrieving and Formatting Data," in Developing ColdFusion MX Applications.
Incorporating HTML form tags

The cfform tag lets you incorporate these standard HTML elements:

- Standard form tag attributes and values. The attributes and values are included in the form tag that cfform outputs in the page. For example, you can use form tag attributes like target with cfform. Other pass-through attributes include CLASS, ENCTYPE, ID, ONLOAD, ONRESET, and STYLE.
- HTML tags that can ordinarily be put within the HTML form tag. For example, you can use the HTML input tag to create a submit button in a cfform, without the other features of cfinput:

    <cfform>
       <input type = "Submit" value = " update... ">
    </cfform>

Example

    <h3>cfform Example</h3>
    <cfif IsDefined("form.oncethrough") is "Yes">
       <cfif IsDefined("form.testVal1") is True>
       <h3>Results of Radio Button Test</h3>
       <cfif form.testVal1 is "Yes">Your radio button answer was yes</cfif>
       <cfif form.testVal1 is "No">Your radio button answer was no</cfif>
       </cfif>
       <cfif IsDefined("form.chkTest2") is True>
       <h3>Results of Checkbox Test</h3>
          Your checkbox answer was yes
       <cfelse>
          <h3>Results of Checkbox Test</h3>
          Your checkbox answer was no
       </cfif>
       <cfif IsDefined("form.textSample") is True
        AND form.textSample is not "">
       <h3>Results of Credit Card Input</h3>
          Your credit card number, <cfoutput>#form.textSample#</cfoutput>,
    was valid under the MOD 10 algorithm.
       </cfif>
       <cfif IsDefined("form.sampleSlider") is "True">
       <h3>You gave this page a rating of <cfoutput>#form.sampleSlider#
       </cfoutput></h3>
       </cfif>
       <hr noshade>
    </cfif>
    <!--- begin by calling the cfform tag --->
    <cfform action = "cfform.cfm">
    <table>
    <tr>
       <td>
       <h4>This example displays radio button input type for cfinput.</h4>
       Yes <cfinput type = "Radio" name = "TestVal1" value = "Yes" checked>
       No <cfinput type = "Radio" name = "TestVal1" value = "No">
       </td>
    </tr>
    <tr>
       <td>
       <h4>This example displays checkbox input type for cfinput.</h4>
       <cfinput type = "Checkbox" name = "ChkTest2" value = "Yes">
       </td>
    </tr>
    <tr>
       <td>
       <h4>This shows client-side validation for cfinput text boxes.</h4>
       <br>(<I>This item is optional</i>)<br>
       Please enter a credit card number:
       <cfinput type = "Text" name = "TextSample"
          message = "Please enter a Credit Card Number"
          validate = "creditcard" required = "No">
       </td>
    </tr>
    <tr>
       <td>
       <h4>This example shows the use of the cfslider tag.</h4>
       <p>Rate your approval of this example from 1 to 10 by sliding control.
       <p>1 <cfslider name = "sampleSlider"
             label = "Sample Slider" range = "1,10"
             message = "Please enter a value from 1 to 10"
             scale = "1" bold = "No"
             italic = "No" refreshlabel = "No"> 10
       </td>
    </tr>
    </table>
    <p><input type = "submit" name = "submit" value = "show me the result">
    <input type = "hidden" name = "oncethrough" value = "Yes">
    </cfform>
    </body>
    </html>

NAME |
| Optional
Default value: "CFForm_1 [, ...]" A name for the form.

ACTION |
| Optional
Default value: " " Name of ColdFusion page to execute when the form is submitted for processing.

SCRIPTSRC |
| Optional
Default value: "/cfide/scripts/cfform.js" Lets the user control the URL of the script file; useful if you do not keep the file in the /cfide directory.

PRESERVEDATA |
| Optional

Default value: "No"

When the cfform action attribute posts back to the same page as the form, this determines whether to override the control values with the submitted values.

- false: values specified in the control tag attributes are used
- true: corresponding submitted values are used

Applies to these controls:

- cfform controls cfinput, cfslider, cftextinput; overrides value attribute value
- cfselect controls that are populated from queries. Overrides the selected attribute. See cfselect.
- cftree controls: Overrides the cftreeitem expand attribute. If true, expands previously-selected elements. The cftree completePath attribute must be set to Yes.
- cfgrid controls: has no effect. (This avoids confusion as to whether data has been resubmitted to the database by the control.)

ONSUBMIT |
| Optional
JavaScript function to execute after input validation. Use for preprocessing data before form is submitted. See Developing ColdFusion MX Applications.

PASSTHROUGH |
| Optional
Passes arbitrary attribute-value pairs to the HTML code that is generated for the tag. You can use either of the following formats: passthrough="title=""myTitle""" passthrough='title="mytitle"'

CODEBASE |
| Optional
Default value: "See Description" URL of downloadable JRE plug-in (for Internet Explorer only). Default: /CFIDE/classes/cf-j2re-win.cab

ARCHIVE |
| Optional
Default value: "See Description" Default value: "URL of downloadable Java classes for ColdFusion controls. " Default value: "Default: /CFIDE/classes/CFJava2.jar"