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.

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

History

New in ColdFusion MX: if the cfform tag preserveData attribute is set to True, ColdFusion checks radio and checkbox 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 checkboxes or radio buttons for the control, the checked attribute was used.

Attributes

Attribute Req/Opt Default Description

type
Optional
text

text: creates a text entry box control

radio: creates a radio button control

checkbox: creates a checkbox control

password: creates a password entry control

name
Required

Name for form input element.

value
Optional

Initial value for form input element.

required
Optional
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: strips 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 the "Building Dynamic Forms" chapter in Developing ColdFusion 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

HTML attributes that are not supported by cfinput. If you specify an attribute and value, they are passed to the HTML code generated for the tag.

Attribute	Req/Opt	Default	Description
type	Optional	text	text: creates a text entry box control radio: creates a radio button control checkbox: creates a checkbox control password: creates a password entry control
name	Required		Name for form input element.
value	Optional		Initial value for form input element.
required	Optional	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: strips 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 the "Building Dynamic Forms" chapter in Developing ColdFusion 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		HTML attributes that are not supported by `cfinput`. If you specify an attribute and value, they are passed to the HTML code generated for the tag.

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 checkbox 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 Developing ColdFusion MX Applications with CFML.

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>