cfform

Description

Builds a form with CFML custom control tags; these provide more functionality than standard HTML form input elements. You can include the resulting form on the client page as HTML or Flash content, and generate the form using XML and XSLT.

Category

Forms tags

Syntax

<cfform 
   name = "name"
   action = "form_action"
   method = "POST" or "GET"
   format = "HTML" or "Flash" or "XML"
   skin = "Flash or XSL skin"
   style = "style specification"
   preserveData = "yes" or "no"
   onSubmit = "javascript" 
   scriptSrc = "path"
   codeBase = "URL"
   archive = "URL"
onLoad = "load event script"
The following attributes are supported in Flash and XML only
width = "pixels or percent"
height = "pixels or percent"
The following attributes are supported in Flash only
onError = "ActionScript code"
wMode = "window" or "transparent" or "opaque"
accessible = "yes" or "no"
preloader = "yes" or "no"
timeout = "seconds"
The following attributes are supported in HTML and XML only
class = "form class"
enctype = "Internet media type"
id = "HTML id"
onReset = "reset event script"
target = "target window or frame">
...
</cfform>

See also

cfapplet, cfcalendar, cfformgroup, cfformitem, cfgrid, cfinput, cfselect, cfslider, cftextarea, cftree; Requesting and Presenting Information in ColdFusion MX Developer's Guide

History

ColdFusion MX 7:

• Added ability to set the default value of the scriptSrc attribute in the ColdFusion MX Administrator.
• Deprecated the passthrough attribute. The tag now supports all HTML form tag attributes directly.
• Added the method attribute and support for the GET method.
• Added support for Flash and XML output, including the format, height, width, preloader, timeout, wMode, accessible, and skin attributes.
• Added cfformgroup, cfformitem, and cftextarea child tags.
• Added the onReset attribute.

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.
• Changed integer validation to require an integer value. In previous releases it would convert a floating point value to an integer.

Attributes

The following table lists attributes that ColdFusion uses directly. For HTML format forms, this tag also supports the standard HTML form tag attributes that are not on this list, and passes them directly to the browser. ColdFusion also includes all supported HTML attributes in the XML.

Note: Attributes that are not marked as supported in XML are not handled by the skins provided with ColdFusion MX. They are, however, included in the generated XML as html namespace attributes to the form tag.

Usage

This tag requires an end tag.

You can use the following ColdFusion form control tags within the cfform tag:

• cfapplet Used in HTML and XML format only; embeds a registered Java applet.
• cfformgroup Used in Flash and XML format only; groups and arranges child controls.
• cfformitem Used in Flash and XML format only; adds horizontal rules, vertical rules, and text to the form.
• cfgrid Creates a grid control to display tabular data.
• cfinput Creates and an input element.
• cfselect Creates a drop-down list box.
• cfslider Used in HTML and XML format only; creates a slider control.
• cftextarea Creates a multi-line text input box.
• cftree Creates a tree control.

In HTML format, all tags, and in Flash format the cftree and cfgrid tags, require JavaScript support on the browser. The cfapplet tag and applet format cfgrid, cfslider, and cftree tags require the client to download a Java applet.

If you specify Flash format in the cfform tag, ColdFusion ignores any HTML in the form body. You must use ColdFusion tags, such as cfinput, for all form controls. You can include individual Flash format cfgrid and cftree controls in an HTML format cfform tag.

In Flash format, if your forms do not request sensitive data (such as credit card numbers), consider setting the timeout attribute. This can prevent users from getting "The form data has expired, Please reload this page in your browser" errors if they use the browser back button to return to the form. For more information, see Caching data in Flash forms in Caching data in Flash formsin ColdFusion MX Developer's Guide.

Note: In Flash format, if you do not specify height and width attributes, Flash reserves browser space equal to the area of the browser window. If any other output follows the form, users must scroll to see it. Therefore, if you follow a Flash form with additional output, specify the height and width values. The width and height attributes are required for Flash forms, if they are used inside of a table.

If attribute value text must include quotation marks, escape them by doubling them.

Using the onError attribute in Flash forms

If you use onSubmit or onBlur validation, the onError attribute lets you specify ActionScript code to execute if the user tries to submit a Flash form with validation errors, as follows:

• If you specify one or more valid Flash expressions, Flash executes the expressions.
• If you omit the attribute, Flash displays a dialog box with all applicable error messages.
• If you specify onError="" (an empty string) Flash does not display any message, but does not submit the form.

Your ActionScript can use the errors variable to determine the fields and errors. The errors object has the following fields:

The following example shows cfform tags with an onError attribute that selects the tab in an accordion or tabnavigator that contains a lastName field with an invalid entry:

<cfform name="form1" format="flash" width="800" height="500" 
      onError="if (errors['lastName'] != undefined
         ){tabA.selectedIndex=0; _root.lastName.setFocus();}">

<Incorporating HTML form tags and attributes

In HTML format, the cfform tag lets you incorporate the following standard HTML elements. They are not available in Flash format:

• Standard HTML 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 or onMouseOver with cfform.
• 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>
  

Examples

<h3>cfform Example</h3>
<!--- If Form.oncethrough exists, the form has been submitted. --->
<cfif IsDefined("Form.oncethrough")>
   <cfif IsDefined("Form.testVal1")>
      <h3>Results of Radio Button Test</h3>
      <cfif Form.testVal1>Your radio button answer was yes
      <cfelse>Your radio button answer was no
      </cfif>
   </cfif>
   <h3>Results of Checkbox Test</h3>
   <cfif IsDefined("Form.chkTest2")>
      Your checkbox answer was yes
   <cfelse>
      Your checkbox answer was no
   </cfif>
   <cfif IsDefined("Form.textSample") 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")>
      <cfoutput>
         <h3>You gave this page a rating of #Form.sampleSlider#</h3>
      </cfoutput>
   </cfif>
   <hr noshade="True">
</cfif>

<!--- Begin by calling the cfform tag. --->
<cfform name="cfformexample">
   <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">
   <h4>This example displays checkbox input type for cfinput.</h4>
   <cfinput type = "Checkbox" name = "ChkTest2" value = "Yes">
   <h4>This shows client-side validation for cfinput text boxes.</h4>
   (<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">
   <h4>This example shows the use of the cfslider tag.</h4>
   Rate your approval of this example from 1 to 10 by sliding control.<br>
   1 <cfslider name = "sampleSlider" width="100"
         label = "Page Value: " range = "1,10"
         message = "Please enter a value from 1 to 10"> 10
   <p><cfinput type = "submit" name = "submit" value = "show me the result">
   <cfinput type = "hidden" name = "oncethrough" value = "Yes"></p>
</cfform>

A Simple XML form

The following example shows a simple XML-format form. It uses the default.xsl transform that is supplied with ColdFusion to generate the HTML output for display:

<cfform name="testXForm" format="XML" skin="basic">
  <!--- Use cfformgroup to put the first and last names on a single line. --->
  <cfformgroup type="horizontal">
     <cfinput type="text" name="firstname" label="First Name:" value="Robert">
     <cfinput type="text" name="lastname" label="Last Name:" value="Smith">
  </cfformgroup>
  <cfinput type="password" name="password" label="Password:" value="">
  <cfinput type="hidden" name="hidden" label="hidden:" value="">
  <cfselect name="state" style="width:200" label="State">
    <option>California</option>
    <option selected>Utah</option>
    <option>Iowa</option>
    <option selected>New York</option>
   </cfselect>
   <cftextarea name="description" label="Description:" rows="5" cols="40">this is sample text.</cftextarea>
</cfform>

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments

Add Comment

halL said on Feb 17, 2005 at 8:44 AM :

In the cfform tag, you must end the background-color style definition with a semicolon (;), even if it is the only or last definition in a style attribute.

While, currently, this is the only case in Flash forms where the semicolon is always required, you should end all style definition with semicolons, even if they are the only or last definition in the style attribute.
For example, you should do the following:

<cfform format="flash" method="post" name="xxx" height="300" width="500" style="background-color:##FF00FF; indicatorGap:25;">

And not the following:

<cfform format="flash" method="post" name="xxx" height="300" width="500" style="background-color:##FF00FF; indicatorGap:25">

sthompson said on Feb 17, 2005 at 4:50 PM :

In MX 6.1, when you specify an onSubmit attribute in <cfform>, ColdFusion calls the CF JavaScript validation, then calls the code you specified in the onSubmit attribute.

In MX 7, if you specify the onSubmit attribute, ColdFusion will only call the function you specify and not perform any cfform validation. This is a significant difference.

Further, the scriptSrc attribute in 6.1 pointed to a file. In 7, it points to a path. This essentially breaks any cfform code. I think it would have been better to add a scriptPath attribute, then deprecate scriptSrc.

halL said on Feb 18, 2005 at 10:32 AM :

Responding to the 2/17/05 comment from sthompson:

Both of the issues you raise are bugs.

The first issue, where you cannot use standard cfform validation if you specify an onSubmit attribute (bug number 59602), has the following workaround:
To enable standard cfform validation when you use an onSubmit attribute, add the following statement to the onSubmit attribute, replacing CFFORM_1 the value of name attribute of your form.

return _CF_checkCFFORM_1(this)

For example:

<cfform onSubmit="myfunction();return _CF_checkMyCFForm(this)">


We have entered a bug (number 59844) for the change in behavior of the scrptSrc attribute, which now specifies a directory, not a file.

davidsimms said on Mar 3, 2005 at 8:04 AM :

Issue=clicking the Back button after submitting a Flash form causes the data submitting by the form to be lost. Setting the timeout attribute in the CFFORM tag to 60 doesn't help. Here's the code.

<cfform name="testForm"
method="post"
action="action.cfm"
format="flash"
timeout="60">
<cfinput type="text" name="firstName" size="30">
<cfinput type="text" name="lastName" size="30">
<cfinput type="submit" name="Submit" value="Submit">
</cfform>

Macromedia's documentation indicates that should all that is

jrunrandy said on Mar 7, 2005 at 10:12 AM :

This page neglects to mention that cfform height/width are required for flash forms, if they are used inside of a table. I have entered this into our bug tracking system as bug number 59900.

doxx said on May 10, 2005 at 4:36 AM :

Responding to the 2/18/05 comment from halL :

If your javascript function return a boolean value (true or false) your onSubmit attribute look like following statement:
...
<cfform onSubmit="return ( myfunction() && _CF_checkMyCFForm(this) )">

because this attribute should return only one value...
...

FEW said on May 30, 2005 at 9:33 AM :

It'ssimple to have multiple submit buttons and execute different
repsonsed based on which is pressed. Just add a different name
attribute to each button and test for it's existance in the response
page. If it exists, then that button was pressed and you can do what
you want for that user input.

i.e.

<cfinput name="submit" type="submit" label="Update" value="Update"
>
<cfinput name="deleteIt" type="submit" label="Delete" value="Delete"
>

then, in the response page:

<cfif IsDefined("FORM.update")>
<!--- update action goes here --->
</cfif>
<cfif IsDefined("FORM.deleteit")>
<!--- deleteit action goes here --->
</cfif>

jrunrandy said on Jul 26, 2005 at 11:45 AM :

I just saw some cool Flash form discussions at http://www.asfusion.com/blog/. Check it out if you get a minute.

ASandstrom said on Aug 15, 2005 at 10:02 AM :

Tip: You might want to take a look at the article "Advanced Flash Forms Techniques" here:
http://www.macromedia.com/devnet/coldfusion/articles/adv_flashforms.html

dhoule said on Sep 20, 2005 at 7:23 AM :

No screen name,

To have the Submit button submit the Flash form when the user presses the Enter key just do this...

<cfinput
type="submit"
name="submit"
value="Submit"
onkeyup="submitForm();">

Of course, the Flash form itself needs to have focus first, but if the user has been typing into the form it probably will.

MARMC WebMaster said on Sep 27, 2005 at 10:43 AM :

In working around bug 59602 (broken onsubmit functionality) mentioned on 2/17/05 (sthompson), 2/18/05 (halL), and 5/10/05 (doxx), I would caution against using the work-around suggested. The problem is that once the bug is fixed, the work-around will cause an infinite loop. This is because the onsubmit code is inserted into the body of _CF_checkCFForm_1, which will include a call to _CF_checkCFForm_1...

Where possible, use the onvalidate attribute in <cfinput> instead. If you need a general purpose validation block not associated to a specific element, you could try the following:

1) Add a javascript function like the following:

<script language="javascript">
<!--
function form_onvalidate(form, input, value) {
// ignore 'input' and 'value' attributes, since they apply only to the hidden field.

var bValid = true;

// validation code goes here.
// Make sure to set bValid = false if you do not want the page to be submitted.

// if you are generating your own error messages, include this line to ensure
// that the default error message generated by CFMX for validation_hook will
// not be displayed. Otherwise, if you have a single error message, you can
// remove this line and use the 'message' attribute in the in the hidden input field.
if(! bValid) _CF_error_fields[input.name] = "";

return bValid;
}
-->
</script>


2) Add the following to the end of cfform:

<cfinput type="hidden" name="form_validation_hook" onvalidate="form_onvalidate">

3) Make sure to remove the onsubmit from <cfform>.


Note: this does not interfere with any other <cfinput> elements that is marked as required. Those will still be validated as expected.

Cheese_Man said on Nov 18, 2005 at 2:05 PM :

I spent some time messing with the back/forward button flash forms issue ... "The form data has expired, please reload this page in your browser" ... I could not get the timeout parameter of CFFORM to work for me. In the end, I used someone else's idea of javascript to test for a cookie and then refresh the page if cookie found.
http://forums.devshed.com/t235953/s.html
(you need to add 'refreshPage();' to trigger the function)

ASandstrom said on Dec 19, 2005 at 10:55 AM :

Starting with the ColdFusion MX 7 Updater, Flash forms support the following:
- onFocus and onBlur events
- onLoad attribute, which means that you can run initialization ActionScript for the form

clone45 said on Mar 24, 2006 at 10:08 AM :

Be careful when using "_date" in the names of your input tags. Doing so can generate a "Form entries incomplete or invalid." error. Here's a small example to illustrate the problem:

<cfform name="test" action="">
<input type="text" name="story" value="some value">
<input type="text" name="story_date" value = "some other value">
<input type="submit" value="submit">
</cfform>

This will throw an error.

nicetim said on Jul 27, 2006 at 10:33 AM :

Hi All,
This is a late post, but i have found another issue that dosnt seem to be on this page.

In normal HTML forms, if you submit the form, then refresh the action page, the form structure is reposted.
This is NOT true in flash forms. Be careful not to use form vars on the action pages of flash forms without first testing for their existance. This has caused me tons of problems and i dont understand why it dosnt work.

give it a try the next time you post a flash form.

tim

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000256.htm

Add Comment