Used within the cfform tag, to place input controls that support input validation on a form.

Forms tags

cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfselect, cfslider, cftextarea, cftree

ColdFusion MX 7:

• Added support for button, file, hidden, image, reset, and submit controls.
• Added support for generating Flash and XML controls (specified in the cfform tag).
• Added datefield type (Flash forms only) and the supporting daynames and monthnames attributes.
• Added bind, enabled, height, label, tooltip, visible, and width attributes for use in Flash forms.
• Added support for onBlur and onServer validation, including the validateAt attribute.
• Added USdate, range, boolean, email, URL, uuid, guid, maxlength, noblanks, and submitOnce validation attribute values.
• Added support for preventing multiple submissions.
• Added the mask attribute.
• Deprecated the passthrough attribute. The tag now supports all HTML input tag attributes directly.

ColdFusion MX: Changed the cfform tag preserveData attribute behavior: if it is set to True, ColdFusion checks radio and check box values only if their value matches the posted value for the control. (In earlier releases, if the posted value did not match any of the cfinput check boxes or radio buttons for the control, the checked attribute was used.

The following table lists attributes that ColdFusion uses directly. The tag also supports all HTML form tag attributes that are not on this list, and passes them directly to the browser.

<em>

For this tag to work properly. the browser must be JavaScript-enabled.

If the cfform preserveData attribute is true and the form posts back to the same page, the posted value of the cfinput control is used, instead of its Value or Checked attribute.

You can use the keyboard to access and select dates from a datefield Flash input: press Tab to go to the field and press the Spacebar to open the menu. Use the Up, Down, Left, and Right Arrow keys to change the selected date. Use the Home and End keys to reach the first and last enabled date in a month, respectively. Use the Page Up and Page Down keys to reach the previous and next month, respectively.

For more information, see cfform. For information on using JavaScript regular expressions with this tag, see Chapter 27, "Building Dynamic Forms with cfform Tags" in ColdFusion MX Developer's Guide.

The following sections describe how to do validation in cfinput tags.

Validation methods ColdFusion provides four methods of validation of cfinput text and password fields.

You can specify one or a combination of the following in the validateAt attribute:

• onSubmit The form page on the browser includes JavaScript functions that perform validation before the form is submitted to the server. In Flash format forms, this option is identical to onBlur.
• onBlur In HTML format the form page on the browser includes JavaScript functions that perform validation when the field loses the focus. In Flash format, the attribute is equivalent to onSubmit. OnBlur validation uses the same algorithms as onSubmit validation. OnBlur validation was added in ColdFusion MX 7.
• onServer ColdFusion performs the validation on the server. Some onServer algorithms vary from the onSubmit algorithms. OnServer Date and Time validation allow more patterns than onSubmit validation. OnServer validation was added in ColdFusion MX 7, and automatically generates hidden fields to support the validation.

You can also omit a validate attribute and specify the type of validation for the field in a separate hidden form field. This form of validation is equivalent to onServer validation, but it allows you to specify separate messages for each validation that you do on the field. It is backward compatible with previous ColdFusion releases. For more information on hidden form field validation, see cfform and "Validating form data using hidden fields" in Chapter 28, "Validating form data using hidden fields," in ColdFusion MX Developer's Guide.

validation types You can use the following values in the validate attribute to specify input validation for all validation methods. Most attributes apply only to password or text fields. You can specify multiple validation types in a comma-delimited list, but only some combinations are meaningful.

Validation differences The preceding table describes the general validation behavior. The underlying validation code must differ depending on the validation method and the form type. As a result, the algorithms used vary in some instances, including the following:

• The validation algorithms used for date/time values varies between onSubmit/OnBlur and OnServer.
• The algorithms used for onSubmit/OnBlur validation in Flash vary from those used for HTML/XML format, and generally follow simpler rules.

The table describes the onSubmit/OnBlur behavior in HTML format. For detailed information on the OnServer validation algorithms, see "Data validation types" in Chapter 28, "Data validation types," in ColdFusion MX Developer's Guide.

For more information on validation, including discussions of the advantages and disadvantages of different validation types, see Chapter 28, "Validating Data" in ColdFusion MX Developer's Guide.

The mask attribute controls the format of data that can be entered into a field. You can combine masking and validation on a field.

• In HTML and Flash form format the mask can control the format of data entered into a text field.
• In Flash format, the mask can also control the format of the date chosen using the datefield input control.

In text fields, ColdFusion automatically inserts any literal mask characters, such as - characters in telephone numbers. Users type only the variable part of the field.

The following pattern enforces entry of a part number of the format EB-1234-c1-098765, where the user starts the entry by typing the first numeric character, such as 3. ColdFusion fills in the preceding EA prefix and all - characters. The user must enters four numbers, followed by two alphanumeric characters, followed by six numbers.

<cfinput type="text" name="newPart" mask="EB-9999-XX-999999" />

For tags with type="datefield" (and cfcalendar tags), the number of pattern characters determines the format of the output, as follows:

The following pattern specifies that the Flash forms sends the date selected using a datefield input control to ColdFusion as text in the format 04/29/2004:

<cfinput name="startDate" type="datefield" label="date:" mask="mm/dd/yyyy"/>

The bind attribute lets you populate form fields using the contents of other form fields. To specify text from another field in a cftextarea bind attribute, use the following format:

{sourceTagName.text}

For example, the following line uses the values from the firstName and lastName fields to construct an email address. (The user can change or replace this value with a typed entry.)

         <cfinput type="text" name="email" label="email"
            bind="{firstName.text}.{lastName.text}@mm.com">

<!--- This example shows the use of cfinput within a cfform to ensure simple
validation of text items. --->
<cfform action = "cfinput.cfm">
<!--- Phone number validation. --->
Phone Number Validation (enter a properly formatted phone number): <br>
<cfinput 
   type = "Text" name = "MyPhone" 
   message = "Enter telephone number, formatted xxx-xxx-xxxx (e.g. 617-761-
2000)"
   validate = "telephone" required = "yes">
   <font size = -1 color = red>Required</font>
<!--- Zip code validation. --->
<p>Zip Code Validation (enter a properly formatted zip code):<br>
<cfinput 
   type = "Text" name = "MyZip" 
   message = "Enter zip code, formatted xxxxx or xxxxx-xxxx" 
   validate = "zipcode" required = "yes">
   <font size = -1 color = red>Required</font>
<!--- Range validation. --->
<p>Range Validation (enter an integer from 1 to 5): <br>
<cfinput 
   type = "Text" name = "MyRange" range = "1,5" 
   message = "You must enter an integer from 1 to 5" 
   validate = "integer" required = "no">
<!--- Date validation. --->
<p>Date Validation (enter a properly formatted date):<br>
<cfinput 
   type = "Text" name = "MyDate" 
   message = "Enter a correctly formatted date (dd/mm/yy)" 
   validate = "date" required = "no">
<input 
   type = "Submit" name = "" 
   value = "send my information">
</cfform>