CFINPUT |
Description
Used within the cfform tag, to place radio buttons, check boxes, or text boxes on a form. Provides input validation for the specified control type.
Category
Forms tags

Syntax

    <cfinput
       type = "input_type"
       name = "name"
       value = "initial_value"
       required = "Yes" or "No"
       range = "min_value, max_value"
       validate = "data_type"
       onValidate = "javascript_function"
       pattern = "regexp"
       message = "validation_msg"
       onError = "text"
       size = "integer"
       maxLength = "integer"
       checked
       passThrough = "HTML_attributes">

See also
cfapplet, cfform, cfgrid, cfselect, cfslider, cftextinput, cftree
History
ColdFusion MX 6.1: Changed the requirements for the validate = "creditcard" option: it requires that the text entry have 13-16 digits.
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.
<em>

In addition to the listed attributes, you can use the following HTML attributes in the cfform tag without using the passThrough attribute. The tag does not use these attributes, but includes them in the HTML of the form tag that it generates and returns to the browser:

- class
- id
- onBlur
- onChange
- onClick
- onDblclick
- onFocus
- style
- tabIndex

Usage
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.
If cfinput check box or radio type values match the submitted value for the control, ColdFusion checks their values. If no value matches, nothing is checked.
To add other HTML <input> tag attributes and values to this tag, use the passThrough attribute. They are passed through ColdFusion to the browser when creating a form. The supported HTML attributes are: CLASS, ID, MAXLENGTH, MESSAGE, ONBLUR, ONCHANGE, ONCLICK, ONDBLCLICK, ONFOCUS, SIZE, STYLE, and TABINDEX.

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

    passThrough = "readonly = " "YES " " "

For more information, see cfform. For information on using JavaScript regular expressions with this tag, see Chapter 27, "Building Dynamic Forms," in Developing ColdFusion MX Applications.

Example

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

TYPE |
| Optional

Default value: "text"

- text: creates a text entry box control
- radio: creates a radio button control
- checkbox: creates a check box control
- password: creates a password entry control

NAME |
| Required
Name for form input element.

VALUE |
| Optional
Initial value for form input element.

REQUIRED |
| Optional

Default value: "No"

- Yes
- No

RANGE |
| Optional
Minimum and maximum value range, separated by a comma. If type = "text" or "password", this applies only to numeric data.

VALIDATE |
| Optional

Verifies a value's format:

- date: US date mm/dd/yyyy
- eurodate: European date dd/mm/yyyy
- time: time hh:mm:ss
- float: floating point entry
- integer: integer entry
- telephone: telephone ###-###-####. Separator: hyphen or blank. Area code and exchange must begin with a digit 1 - 9.
- zipcode: (U.S. formats only) 5-digit ##### or 9-digit #####-####. Separator: hyphen or blank.
- creditcard: must be a 13 to 16 digit integer after stripping blanks and dashes; uses the mod10 algorithm.
- social_security_number: ###-##-####. Separator: hyphen or blank.
- regular_expression: matches input against regular expression specified by the pattern attribute.

ONVALIDATE |
| Optional
Custom JavaScript function to validate user input. The form object, input object, and input object values are passed to the routine, which should return True if validation succeeds, and False otherwise. If used, the validate attribute is ignored.

PATTERN |
| Required if validate = "regular_expression"
JavaScript regular expression pattern to validate input. Omit leading and trailing slashes. For examples and syntax, see Chapter 27, "Building Dynamic Forms," in Developing ColdFusion MX Applications.

MESSAGE |
| Optional
Message text to display if validation fails.

ONERROR |
| Optional
Custom JavaScript function to execute if validation fails.

SIZE |
| Optional
Size of input control. Ignored, if type = "radio" or "checkbox".

MAXLENGTH |
| Optional
Maximum length of text entered, if type = "Text" or "password".

CHECKED |
| Optional

Selects a control. No value is required.

Applies if type = "radio" or "checkbox".

Optional: you can enter the following values:

- true (equivalent to checked)
- false (equivalent to omitting the attribute)

PASSTHROUGH |
| Optional

Passes one or more arbitrary attribute-value pairs to the HTML code that is generated for the tag. You can use either of the following formats to include the quotation marks around the attribute value:

    passthrough="ID=""myID"""
    passthrough='ID="myID"'

The second format, which surrounds all the attribute-value pairs to be passed through in single quotation marks is clearer, particularly when you pass multiple HTML attributes.