cfinput

Description

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

Category

Forms tags

Syntax

<cfinput  
    name = "name" 
    autosuggest = "list or bind expression" 
    autosuggestBindDelay = "integer number if seconds" 
    autosuggestMinLength = "integer" 
    bind = "bind expression" 
    bindAttribute = "attribute name" 
    bindOnLoad = "no|yes" 
    checked = "yes|no" 
    dayNames = "day of week labels separated by commas" 
    delimiter = "character" 
    disabled = "disabled" 
    enabled = "yes|no" 
    firstDayOfWeek = "day name" 
    height = "number of pixels" 
    id = "HTML id" 
    label = "text" 
    matchContains = "true|false" 
    mask = "masking pattern" 
    maxLength = "number" 
    maxResultsDisplayed = "number" 
    message = "text" 
    monthNames = "month labels" 
    onBindError = "JavaScript function name" 
    onChange = "JavaScript or ActionScript" 
    onClick = "JavaScript or ActionScript" 
    onError = "script name" 
    onKeyDown = "JavaScript or ActionScript" 
    onKeyUp = "JavaScript or ActionScript" 
    onMouseDown = "JavaScript or ActionScript" 
    onMouseUp = "JavaScript or ActionScript" 
    onValidate = "script name" 
    pattern = "regular expression" 
    range = "minimum value, maximum value" 
    required = "yes|no" 
    showAutosuggestLoadingIcon = "yes|no" 
    size = "integer" 
    sourceForToolTip = "URL" 
    src = "image URL" 
    style = "style specification" 
    tooltip = "text" 
    type = "input type" 
    typeahead = "no|yes" 
    validate = "data type" 
    validateAt = "onBlur|onServer|onSubmit" 
    value = "initial value" 
    visible = "yes|no" 
    width = "integer number of pixels">

Some attributes apply to only specific display formats. For details, see the Attributes table.

In HTML format forms, standard HTML input control attributes not listed above are passed to the HTML and have their normal effect.

See also

cfajaximport, cfapplet,cfcalendar,cfform, cfformgroup, cfformitem, cfgrid, cfselect, cfslider, cftextarea, cftree, Using Ajax form controls and features in Using Ajax User Interface Components and Features in the Developing ColdFusion Applications

History

ColdFusion 8

• Added autosuggest, autosuggestBindDelay, autosuggestMinLength, delimiter, maxResultsDisplayed, showAutosuggestLoadingIcon, and typeahead attributes.

• Added support for the bind attribute in HTML forms and the bindAttribute and bindOnload, and onBindError attributes.

• Added the sourceForTooltip attribute

• Added support for datefield value of the type attribute in HTML forms.

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 validate 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.

Attributes

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.

Usage

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

If the cfformpreserveData 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 Building Dynamic Forms with cfform Tags in the Developing ColdFusion Applications.

Validation

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

Validation methods

ColdFusion provides four methods of validation of cfinputtext 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 lets you 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 Validating form data using hidden fields in the Developing ColdFusion Applications.

Validation types

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.

Type	Description
date	If validateAt="onServer", allows any date format that returns true in the IsDate function; otherwise, same as USdate.
USdate	A US date of the format mm/dd/yy mm-dd-yy or mm.dd.yy, with 1-2 digit days and months, 1-4 digit years.
eurodate	A date of the format dd/mm/yy, with 1-2 digit days and months, 1-4 digit years. The format can use /, -, or . characters as delimiters.
time	Time format hh:mm:ss
floatornumeric	A number; allows integers.
integer	An integer.
range	A numeric range.
boolean	A value that can be converted to a Boolean value: Yes, No, True, False, or a number.
telephone	Standard U.S. telephone formats. Allows an initial 1 long-distance designator and up to 5-digit extensions, optionally starting with x.
zipcode	U.S. 5- or 9-digit ZIP code format #####-####. The separator can be a hyphen (-) or a space.
creditcard	Strips blanks and dashes; verifies number using mod10 algorithm. Number must have 13-16 digits.
ssnorsocial_security_number	US. Social Security number format, ###-##-####. The separator can be a hyphen (-) or a space.
email	A valid e-mail address of the form name@server.domain. ColdFusion validates the format only; it does not check that entry is a valid active e-mail address.
URL	A valid URL pattern; supports http, https, ftp file, mailto, and news URLs.
guid	A unique identifier that follows the Microsoft/DCE format, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x is a hexadecimal number.
uuid	A universally unique identifier (UUID) that follows the ColdFusion format, xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx, where x is a hexadecimal number.
maxlength	Limits the input to a maximum number of characters.
noblanks	Does not allow fields that consist only of blanks.
regexorregular_expression	Matches input against the pattern attribute. Valid in HTML and XML format only; ignored in Flash format.
SubmitOnce	Used only with submit and image types; prevents the user from submitting the same form multiple times before until the next page loads (for example, submitting an order a second time before getting the first order confirmation). Valid in HTML and XML format only; ignored in Flash format.

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 Data validation types in the Developing ColdFusion Applications.

For more information on validation, including discussions of the advantages and disadvantages of different validation types, see Validating Data in the Developing ColdFusion Applications.

Masking input data

In HTML and Flash forms, the mask attribute controls the format of data that can be entered into a text field or that is selected in a datefield input control calendar. In HTML format, it does not prevent users from typing a date that does not follow the mask into a datefield input control. You can combine masking and validation on a field.

In text fields, ColdFusion automatically inserts any literal mask characters, such as hyphen (-) 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 EB 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 when the user selects a date in the calendar, as follows:

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

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

Flash form data binding

The bind attribute lets you populate form fields by using the contents of other form fields. To specify text from another field in a Flash format cfinput tag 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 e-mail 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">

HTML form data binding

The bind attribute lets you set cfinput attributes dynamically. For example, you can automatically fill an email field text-input value based on name and domain field values.

In HTML format, the bind attribute specifies a bind expression, which can have any for the following forms:

• A Bind parameter or string that contains one or more bind parameters. A bind parameter specifies a form control value or other attribute and, optionally, an event. In its most basic form, a bind parameter consists of the name or id attribute of the control to which you are binding in braces ({ }) The value of the control attributes specified in the bind parameters determine the value of the cfinput control attribute.

• A CFC or JavaScript function, or URL, typically using one or more bind parameters as function parameters. The data returned by the function or URL sets the cfinput attribute value.

For details of using HTML form data binding, see Binding data to form fields in the Developing ColdFusion Applications.

Example: without binding

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

Example: with binding

The following example uses binding to generate a default e-mail address based on input controls with a first, last and domain names, and fills in the e-mail text-input field with the result.

The CFML page contains the following code:

<h3>CFC bind using onkeyup() event</h3> 
<ul> 
    <li>When you type in the First Name field, the first initial appears in 
            the Email control.</li> 
    <li>Each key you enter in the Last Name and Domain fields appears in the 
            Email control.</li> 
</ul> 
 
<cfform name="mycfform"> 
    First Name<font color="#FF0000">*</font>:&nbsp;&nbsp;&nbsp; 
        <cfinput type="text" name="firstname" required="yes"><br> 
    Last Name<font color="#FF0000">*</font>:&nbsp;&nbsp;&nbsp; 
        <cfinput type="text" name="lastname" required="yes"><br> 
    Domain<font color="#FF0000">* 
        </font>:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
        <cfinput type="text" name="domain" required="yes"><br> 
    <br> 
        <cfinput type="text" name="email1" 
            bind="cfc:bindFcns.getEmailId({firstname@keyup},{lastname@keyup}, 
                {domain@keyup})">  
    <br><br> 
<font color="#FF0000">*</font> indicates the field is required. 
</cfform>

The bindFcns CFC contains the following code:

<cfcomponent> 
    <cffunction name="getEmailId" access="remote"> 
        <cfargument name="firstname">  
        <cfargument name="lastname">  
        <cfargument name="domain">  
        <cfreturn "#left(firstname,1)#.#lcase(arguments.lastname)#@# 
    lcase(domain)#"> 
    </cffunction> 
</cfcomponent>