|
cfform
DescriptionBuilds
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 Adobe Flash content, and generate
the form by using XML and XSLT.
Syntax<cfform
accessible = "yes|no"
action = "form action"
archive = "URL"
codeBase = "URL"
format = "HTML|Flash|XML"
height = "pixels|percent"
id = "HTML id" method = "POST|GET"
name = "name"
onError = "JavaScript function name or ActionScript code"
onLoad = "load event script" onReset = "reset event script" onSubmit = "JavaScript"
onSuccess = "JavaScript function name"
preloader = "yes|no"
preserveData = "yes|no"
scriptSrc = "path"
skin = "Flash skin|XSL skin"
style = "style specification"
timeout = "seconds"
width = "pixels|percent"
wMode = "window|transparent|opaque">
...
</cfform>
Note: You can specify
this tag’s attributes in an attributeCollection attribute
whose value is a structure. Specify the structure name in the attributeCollection attribute
and use the tag’s attribute names as structure keys.
See alsocfajaximport, cfapplet, cfcalendar, cfformgroup, cfformitem, cfgrid, cfinput, cfselect, cfslider, cftextarea, cftree; Requesting
and Presenting Information in the Developing ColdFusion Applications
HistoryColdFusion
8:
ColdFusion
MX 7:
Added ability to set the default value of the scriptSrc attribute
in the ColdFusion 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.
AttributesThe
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
|
accessible
|
Flash
|
Opt
|
no
|
Specifies whether to include support screen
readers in the Flash form. Screen reader support adds approximately
80 KB to the SWF file sent to the client.
|
action
|
Flash
HTML
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.
|
archive
|
applets in HTML and XML
|
Opt
|
/CFIDE/classes/cfapplets.jar
|
URL of downloadable Java classes for cfgrid, cfslider, and cftree applet
controls.
|
codeBase
|
applets in HTML and XML
|
Opt
|
/CFIDE/classes/cf-j2re-win.cab
|
URL of downloadable JRE plug-in for Internet
Explorer; used for cfgrid, cfslider,
and cftree Java applet controls.
|
format
|
Flash
HTML
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.
|
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.
|
id
|
|
|
name attribute value
|
the HTML id of the form.
|
method
|
Flash
HTML
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.
|
name
|
Flash
HTML
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 is assigned
serially to the forms on a page.
|
onError
|
Flash
HTML
|
Opt
|
|
For Flash format forms: 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.
For HTML format
forms: Applies only to forms inside cfdiv, cflayout, cfpod,
or cfwindow controls. The name of a JavaScript
function that runs if an asynchronous form submission fails. For
more information, see the Usage section.
|
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
|
Flash
HTML
XML
|
Opt
|
|
JavaScript or ActionScript function to execute
to preprocess data before form is submitted. If any child tags specify onSubmit field
validation, ColdFusion does the validation before executing this
JavaScript.
|
onSuccess
|
HTML
|
Opt
|
|
Applies only to forms inside cfdiv, cflayout, cfpod,
or cfwindow controls. The name of a JavaScript
function that runs when an asynchronous form submission succeeds.
For more information see the Usage section.
|
preloader
|
Flash
|
Opt
|
yes
|
Specifies whether to display a progress
bar when loading the Flash form.
|
preserveData
|
HTML
XML
|
Opt
|
no
|
When the cfformaction attribute
posts back to the page that contains the form, this attribute determines
whether to override the control values with the 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 cftreeitemexpand attribute.
If yes, expands previously-selected elements. The cftreecompletePath 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.)
|
scriptSrc
|
Flash
HTML
XML
|
Opt
|
See Description
|
Specifies the URL, relative to the web root,
of the directory that contains ColdFusion JavaScript files, including
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.
When you use this
attribute, the specified directory must have the same structure
as the /CFIDE/scripts directory. For example, if you specify scriptsrc="/resources/myScripts",
the JavaScript files used by ColdFusion AJAX features must be in
the /resources/myScripts/ajax directory.
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 location is
set in the ColdFusion Administrator; by default, it is /CFIDE/scripts.
Notes:
If
you specify this attribute, copy the CF_RunActiveContent.js file
from the CFIDE/scripts directory to the specified directory.
You
can have only one scriptsrc attribute on a page, including
any cfajaximport tag scriptsrcattribute.
If you have multiple cfform tags, you can specify
the scriptsrc attribute in a cfajaximport tag and it applies to
all HTML format forms.
|
skin
|
Flash
XML
|
Opt
|
Flash: haloGreen
XML:
default.xsl
|
Flash: Use
a halo color to stylize the output. The skin determines the color
used for highlighted and selected elements.
haloSilver
haloBlue
haloGreen
haloOrange
XML: Specifies
whether to apply an XSL skin and display the resulting HTML to the
client. Can be any of the following:
ColdFusion
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
default skin.
You can specify the following
ColdFusion skins (located in the cf_webroot\\x
basic
basiccss
beige
blue
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 Flash in the Developing ColdFusion Applications.
|
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 the Developing ColdFusion Applications.
|
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.
|
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.
|
Note: Attributes that are not
marked as supported in XML are not handled by the skins provided
with ColdFusion. They are, however, included in the generated XML
as html namespace attributes to the form tag.
UsageThis tag
requires an end tag.
You can use the following ColdFusion
form control tags in 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 multiline
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. 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 the Developing ColdFusion Applications.
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 formsIf 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:
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 tab navigator 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 attributesIn 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>
Using forms in cfdiv, cflayout, cffpod, and cfwindow controlsThe cfdiv, cflayout, cffpod,
and cfwindow tags create AJAX-based controls that
can serve as containers for interactive forms. When you use such
a structure, you do not want submitting form information to cause
a new page to be displayed; instead, you want dynamic code to modify
the existing page without causing a complete reload. You can do
this by using the onSuccess and onError attributes.
The
function specified by the onSuccess attribute gets
called if the form data is submitted successfully. This function
is responsible for updating the pod, layout, or window to reflect
the results of the submission, for example, to display additional
data or pop up a confirmation window. This function must not take any
arguments
The function specified by the onError attribute
gets called if an error occurs when the form data is submitted.
This function is responsible for handling the error, such as displaying
an error message. This function must take two arguments: an error
number and an error message.
Incorporating interactive fields in PDF formsColdFusion lets you use
the cfform tag to create PDF forms that contain
static and interactive form fields. The cfform tag
must exist within a cfdocument tag (where format="pdf").
Only one cfform tag can exist within a cfdocument tag.
Completed
forms can be posted to the server as an HTTP Post, or the entire
PDF can be submitted as binary stream. If the PDF is submitted,
you can use the cffile tag to save completed PDF
form to a hard drive:
<cffile action="write" file="c:\savedpdf.pdf" output="#PDF.content#">
The
output can be manipulated and extracted by using the tag.
Only
the following cfform attributes are supported in
generating PDF forms:
action
format
method
name
onSubmit
skin
style
To embed an existing PDF form generated
by LiveCycle Designer or Acrobat, use the tag.
Example<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 formThe 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>
A simple PDF form<cfdocument format="pdf">
<cfdocumentsection ../>
...
...
<cfform type="html/xform">
<cfinput type="textbox" name="employeeName" value="#fullName#" readonly="true">
<cfinput type="textbox" name="employeeID" value="#id#" readonly>
<cfselect name="contributionPercentage" options="#optionsStruct#" required="true">
<cfinput type="submit" name="SubmitAsHTTPPost">
<cfinput type="submit" name="SubmitAsPDF" submitType="PDF">
</cfform>
...
...
<cfdocumentsection ../>
</cfdocument>
|