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:

ColdFusion MX:

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.

Attribute Applies
to
Req/Opt Default Description

name

HTML, Flash, XML

Opt

CFForm_n

A name for the form.

In HTML format, if you omit this attribute and specify an id attribute, ColdFusion does not include a name attribute in the HTML sent to the browser; this behavior lets you use the cfform tag to create XHTML-compliant forms. If you omit the name attribute and the id attribute, ColdFusion generates a name of the form CFForm_n where n is a number that assigned serially to the forms on a page.

action

HTML, Flash, XML

Opt

See Description

Name of ColdFusion page to execute when the form is submitted for processing.

If you omit this attribute, the form posts to the page identified by the CGI.SCRIPT_NAME variable, the requested page that resulted in displaying the form.

method

HTML, Flash, XML

Opt

post

The method the browser uses to send the form data to the server:

  • post: sends the data using the HTTP post method, This method sends the data in a separate message to the server.
  • get: sends the data using the HTTP get method, which puts the form field contents in the URL query string.

format

HTML, Flash, XML

Opt

HTML

  • HTML: generates an HTML form and send it to the client. cfgrid and cftree child controls can be in Flash or applet format.
  • Flash: generates a Flash form and send it to the client. All controls are in Flash format.
  • XML: generates XForms-compliant XML and save the results in a variable specified by the name attribute. By default, ColdFusion also applies an XSL skin and displays the result. For more information, see the skin attribute.

skin

Flash,
XML

Opt

Flash: haloGreen

XML:

default.xsl

Flash: Use a Macromedia halo color to stylize the output. The skin determines the color used for highlighted and selected elements.

  • haloSilver
  • haloBlue
  • haloGreen
  • haloOrange

XML: Specfies whether to apply an XSL skin and display the resulting HTML to the client. Can be any of the following:

  • ColdFusion MX skin name: applies the specified skin.
  • XSL file name: applies the skin located in the specified path.
  • "none": does not apply an XSL skin. Your CFML page must process the XML that ColdFusion saves in the variable specified by the name attribute and display any results.
  • (omitted) or "default": uses the ColdFusion MX default skin.

You can specify the following ColdFusion MX skins (located in the cf_webroot\CFIDE\scripts\xsl directory):

  • basic
  • basiccss
  • beige
  • blue
  • bluegray
  • lightgray
  • red
  • silver

A filename can be any of the following:

  • absolute URL
  • URL relative to the web root
  • absolute file path
  • name of a file in the scripts folder or a subdirectory of the cf_webroot\CFIDE\scripts directory. In this case, do not specify the .xsl suffix.

style

HTML, Flash, XML

Opt

 

Styles to apply to the form. In HTML or XML format, ColdFusion passes the style attribute to the browser or XML.

In Flash format, must be a style specification in CSS format. For detailed information on specifying Flash styles, see Creating Forms in Macromedia Flash in ColdFusion MX Developer's Guide.

preserveData

HTML
XML

Opt

no

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

  • false: uses values specified in the control tag attributes.
  • true: uses corresponding submitted values.

Applies to these controls:

  • cfinput, cfslider, cftextinput: overrides the 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.)

onLoad

HTML
XML

Opt

 

JavaScript to execute when the form loads.

onReset

HTML
XML

Opt

 

JavaScript to execute when the user clicks a reset button.

onSubmit

HTML

Flash

XML

Opt

 

JavaScript or ActionScript function to execute to preprocess data before form is submitted. See ColdFusion MX Developer's Guide. If any child tags specify onSubmit field validation, ColdFusion does the validation before executing this JavaScript.

scriptSrc

HTML, Flash
XML

Opt

See Description

Specifies the URL, relative to the web root, of the directory that contains the cfform.js file with the client-side JavaScript used by this tag and its child tags. For XML format forms, this directory is also the default directory for XSLT skins.

This attribute is useful if the file is not in the default location. This attribute may be required in some hosting environments and configurations that block access to the /CFIDE directory.

The default location is set in the ColdFusion MX Administrator; by default, it is /CFIDE/scripts/cfform.js.

If the Administrator has an empty default value, ColdFusion looks for the script in the directory that contains the ColdFusion page.

codeBase

applets in HTML and XML

Opt

See Description

URL of downloadable JRE plug-in for Internet Explorer; used for cfgrid, cfslider, and cftree Java applet controls.

Default: /CFIDE/classes/cf-j2re-win.cab

archive

applets in HTML and

XML

Opt

See Description

URL of downloadable Java classes for cfgrid, cfslider, and cftree applet controls.

Default: /CFIDE/classes/cfapplets.jar

height

Flash

XML

Opt

100%

The height of the form. Use a number to specify pixels. In Flash, you can use a percentage value, such as "height=60%" to specify a percentage of the available width. The displayed height might be less than the specified size.

Note: The width and height attributes are required for Flash forms, if they are used inside of a table.

width

Flash

XML

Opt

100%

The width of the form. Use a number to specify pixels. In Flash, you can use a percentage value, such as "width=60%" to specify a percentage of the available width.

Note: The width and height attributes are required for Flash forms, if they are used inside of a table.

onError

Flash

Opt

 

Applies only for onSubmit or onBlur validation; has no effect for onServer validation.

An ActionScript expression or expressions to execute if the user submits a form with one or more validation errors.

wMode

Flash

Opt

Window

Specifies how the Flash form appears relative to other displayable content that occupies the same space on an HTML page.

  • window: the Flash form is the topmost layer on the page and obscures anything that would share the space, such as drop-down dynamic HTML lists.
  • transparent: the Flash form honors the z-index of dhtml so you can float items above it. If the Flash form is above any item, transparent regions in the form show the content that is below it.
  • opaque: the Flash form honors the z-index of dhtml so you can float items above it. If the Flash form is above any item, it blocks any content that is below it.

accessible

Flash

Opt

No

Specifies whether to include support screen readers in the Flash form. Screen reader support adds approximately 80KB to the SWF file sent to the client.

preloader

Flash

Opt

true

Specifies whether to display a progress bar when loading the Flash form.

timeout

Flash

Opt

0

Integer number of seconds for which to keep the form data in the Flash cache on the server. A value of 0 prevents the data from being cached. For more information, see Caching data in Flash forms in ColdFusion MX Developer's Guide.

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:

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:

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

Field Contents

name

The name attribute of the control's CFML tag.

field

The internal name used by Flash for the field. name (for example, _level0.field1)

value

The value in the field.

message

The message attribute of the control's CFML tag.

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:

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