CFML Reference
ColdFusion Tags

cfform

Description

Builds a form with CFML custom control tags that provide more functionality than standard HTML form input elements.

Category

Forms tags

Syntax

<cfform name = "name"

  action = "form_action"

  preserveData = "Yes" or "No"

  enableCAB = "Yes" or "No"

  onSubmit = "javascript"

  target = "window_name"

  encType = "type"

  passThrough = "HTML_attributes"

  codeBase = "URL"

  archive = "URL" >



...

</cfform> 

See also

cfapplet, cfgrid, cfinput, cfselect, cfslider, cftextinput, cftree

Attributes

Attribute	Description
name	Optional. A name for the form you are creating.
action	Required. The name of the ColdFusion page that executed when the form is submitted for processing.
preserveData	Optional. "Yes" or "No." Specifies whether to display the data that was entered into cfform controls in the action page. "Yes" resets the value of the control to the value submitted when the form is submitted to itself. This works as expected for the cftextinput and cfslider controls. For cftree controls, lets the tree expand the previously selected element. The cftree completePath attribute must be set to "Yes". For cfgrid, preserveData does nothing to avoid confusion as to what data has actually been resubmitted to the database by the grid control. This attribute can be used only if the form and action are on a single page, or if the action page has a form that contains controls with the same names as the corresponding controls on the form page.
enableCAB	This attribute has been deprecated and is non-functional.
onSubmit	Optional. JavaScript function to execute after other input validation returns. Use this attribute to execute JavaScript for preprocessing data before the form is submitted. For more information, see Developing ColdFusion Applications.
target	Optional. The name of the window or window frame to which the form output is sent.
encType	Optional. The MIME type used to encode data sent by the POST method. The default value is application/x-www-form-urlencoded. It is recommended that you accept the default value. This attribute is included for compatibility with the HTML form tag.
passThrough	Optional. Used for HTML attributes that are not explicitly supported by cfform. If you specify an attribute and value, they are passed to the HTML code that is generated for the cfinput tag.
codeBase	Optional. URL for a downloadable JRE plugin (for Internet exploroer only). Default is /CFIDE/classes/cf-j2re-win.cab.
archive	Optional. URL for a downloadable Java classes for ColdFusion controls. Default is /CFIDE/classes/CFJava2.jar.

Usage

ColdFusion provides the following custom control tags:

• cfinput    Creates a form input element (radio button, text box, or checkbox) and can validate form input
• cfselect    Creates a drop down listbox
• cfslider    Creates a slider control
• cftextinput    Creates a text input box
• cftree    Creates a tree control
• cfgrid    Creates a grid control for displaying tabular data in a ColdFusion form
• cfapplet    Embeds a registered Java applet in a ColdFusion form. Applets are registered in the ColdFusion Administrator.

You can add standard and dynamic HTML form tag attributes and their values to the cfform tag by using the passThrough attribute. The attributes and values are passed through ColdFusion to the browser in creating a form.

If you specify a value in quotation marks, you must escape the quotation marks by doubling them; for example,

passThrough = "readonly = " "YES " " "

Incorporating HTML form tags

The cfform tag lets you incorporate standard HTML in two ways:

• By adding standard form tag attributes and values to the cfform tag. The attributes and values are passed through ColdFusion to the browser in creating a form. For example, you can use form tag attributes like target to enhance your cfform features.
• By placing HTML tags that can ordinarily be placed within the regular HTML form tag between <cfform> and </cfform> tags.

For example, you use a standard HTML input tag to create a submit button in a cfform:

<cfform>

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

</cfform>

Example

<!--- This example shows the use of cfinput controls in a cfform --->

<html>

<head>

<title> cfform Example </title>

</head>



<body>

<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" method = "POST" enableCAB = "Yes">



<table>

<TR>

  <TD>

  <H4>This example displays the 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 the checkbox input type for cfinput.</H4>

  <cfinput type = "Checkbox" name = "ChkTest2" value = "Yes">

  </TD>

</TR>



<TR>

  <TD>

  <H4>This example shows a 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 

    the 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>    

Copyright © 2001, Macromedia Inc. All rights reserved.

---