CFTEXTAREA  
Description

Puts a multiline text entry box in a cfform tag and controls its display characteristics.

 
Category

Forms tags

 
Syntax
<cftextarea 
name = "name"
label = "text"
required = "yes" or "no"
style = "style specification"
validate = "data type"
validateAt= one or more of "onBlur", "onServer", "onSubmit"
message = "text"
range = "min_value, max_value"
maxlength = "number"
pattern = "regexp"
onValidate = "script name"
onError = "script name"
disabled = "true" "false" or no attribute value
value = "text"
onKeyUp = "JavaScript or ActionScript"
onKeyDown = "JavaScript or ActionScript"
onMouseUp = "JavaScript or ActionScript"
onMouseDown = "JavaScript or ActionScript"
onChange = "JavaScript or ActionScript"
onClick = "JavaScript or ActionScript"
visible = "Yes" or "No"
enabled = "Yes" or "No"
tooltip = "Tip text"
height = "number of pixels" Flash only
width = "number of pixels" Flash only
>
   text
</cftextarea>
 
See also

cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfselect, cfslider, cftree; Chapter 26, "Introduction to Retrieving and Formatting Data," in ColdFusion MX Developer's Guide

 
History

ColdFusion MX 7: Added this tag.

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

Note: Attributes that are marked as Flash only are not handled by the skins provided with ColdFusion MX. They are, however, included in the generated XML.

Note: Attributes that are marked as Flash only are not handled by the skins provided with ColdFusion MX. They are, however, included in the generated XML.
 
Usage

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

If you put text in the tag body, the control displays all text characters between the cftextarea opening and closing tags; therefore, if you use line feeds or white space to format your source text, they appear in the control.

If the cfform preserveData attribute is "yes", and the form posts back to the same page, the posted value (not the value of the value attribute) of the cftextinput control is used.

 
Validation

For a detailed description of the validation attribute and the types of validation supported by ColdFusion, see the Usage section of the cfinput tag reference. For more details on ColdFusion MX validation techniques, see Chapter 28, "Validating Data" in ColdFusion MX Developer's Guide.

 
Flash form data binding

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 value of the text that the user enters in the from the userName field in the greeting in the comment text box. The user can change or replace this message with a typed entry. 

<cfformitem type="text">
Enter your name here</cfformitem>
<cftextarea name="userName" height="20" Width="500"/> 
<cftextarea name="comment" html height="300" Width="500" 
   bind="Hello {userName.text}!
 Enter your comments here." />
 
Example

This example has two cftextarea controls. When you submit the form, ColdFusion copies the text from the first control into the second. The onBlur maxlength validation prevents you from entering more than 100 characters. The > character that closes the cftextarea opening tag, the text in the tag body, and the cftextarea closing tag are on a single line to ensure that only the desired text displays, but the line is split in this example for formatting purposes. 

<h3>cftextarea Example</h3>
<cfparam name="text2" default="">
<cfif isdefined("form.textarea1") AND (form.textarea1 NEQ "")>
   <cfset text2=form.textarea1>
</cfif>

<cfform name="form1">
   <cftextarea name="textarea1" wrap="virtual" rows="5" cols="25"
   validate="maxlength" validateAt="onBlur" maxlength="100" 
   >Replace this text. Maximum length is 100 Characters, and this text is
currently 99 characters long.</cftextarea>
   <cftextarea name="textarea2" wrap="virtual" rows="5" cols="50" 
value="#text2#" /><br><br>
   <input type="submit" value="submit field"><br>
</cfform>
NAME  
  Required;
 
  All
 

Name of the cftextinput control.
LABEL  
  Optional;
 
  Flash and XML
 

Label to put beside the control on a form.
STYLE  
  Optional;
 
  All
 

In HTML or XML format forms, ColdFusion passes the style attribute to the browser or XML.

In Flash format forms, must be a style specification in CSS format, with the same syntax and contents as used in Macromedia Flex for the corresponding Flash element.
REQUIRED  
  Optional;
 
  All
 
Default value: "no"
  • yes: the field must contain text.
  • no: the field can be empty.
VALIDATE  
  Optional;
 
  All
 

The type or types of validation to do. Available validation types and algorithms depend on the format. For details, see the Usage section of the cfinput tag reference.
VALIDATEAT  
  Optional;
 
  HTML and XML
 
Default value: "onSubmit"

How to do the validation; one or more of the following:

  • onSubmit
  • onServer
  • onBlur

For Flash format forms, onSubmit and onBlur are identical; validation is done when the user submits the form. For multiple values, use a comma-delimited list.

For details, see the Usage section of the cfinput tag reference.
MESSAGE  
  Optional;
 
  All
 

Message text to display if validation fails.
RANGE  
  Optional;
 
  All
 

Minimum and maximum allowed numeric values. ColdFusion uses this attribute only if you specify range in the validate attribute.

If you specify a single number or a single number followed by a comma, it is treated as a minimum, with no maximum. If you specify a comma followed by a number, the maximum is set to the specified number, with no minimum.
MAXLENGTH  
  Optional;
 
  All
 

The maximum length of text that can be entered. ColdFusion uses this attribute only if you specify maxlength in the validate attribute.
PATTERN  
  Required if validate = "regular_expression"
 
  HTML and XML.
 

JavaScript regular expression pattern to validate input. Omit leading and trailing slashes. ColdFusion uses this attribute only if you specify regex in the validate attribute. For examples and syntax, see Chapter 27, "Building Dynamic Forms with cfform Tags" in ColdFusion MX Developer's Guide.
ONVALIDATE  
  Optional;
 
  HTML and XML
 

Custom JavaScript function to validate user input. The JavaScript DOM form object, input object, and input object value are passed to routine, which should return True if validation succeeds, False otherwise. If you specify this attribute, ColdFusion ignores the validate attribute.
ONERROR  
  Optional;
 
  HTML and XML
 

Custom JavaScript function to execute if validation fails.

DISABLED  
  Optional;
 
  All
 
Default value: "not disabled"

Disables user input, making the control read-only. To disable input, specify disabled without an attribute, or disabled="Yes" (or any ColdFusion positive Boolean value, such as True). To enable input, omit the attribute or specify disabled="No" (or any ColdFusion negative Boolean value, such as False).
VALUE  
  Optional;
 
  All
 

Initial value to display in text control. You can specify an initial value as an attribute or in the tag body, but not in both places. If you specify the value as an attribute, you must put the closing cftextarea tag immediately after the opening cftextarea tag, with no spaces or line feeds between, or place a closing slash at the end of the opening cftextarea tag; for example <cftextarea name="description" value="Enter a description." />.
BIND  
  Optional;
 
  Flash
 

A Flex bind expression that populates the field with information from other form fields. For details, see Usage.
ONKEYUP  
  Optional;
 
  All
 
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a keyboard key in the control."
ONKEYDOWN  
  Optional;
 
  All
 
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) ActionScript to run when the user presses a keyboard key in the control."
ONMOUSEUP  
  Optional;
 
  All
 
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) to run when the user presses a mouse button in the control."
ONMOUSEDOWN  
  Optional;
 
  All
 
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a mouse button in the control."
ONCHANGE  
  Optional;
 
  All
 
Default value: "JavaScript (HTML/XML) or ActionScript (Flash) to run when the control changes due to user action."
ONCLICK  
  Optional;
 
  All
 
Default value: "JavaScript (HTML/XML) to run when the user clicks the control. Not supported for Flash forms."
ENABLED  
  Optional;
 
  Flash
 
Default value: "Yes" Default value: "Boolean value specifying whether the control is enabled. A disabled control appears in light gray. The inverse of the disabled attribute."
VISIBLE  
  Optional;
 
  Flash
 
Default value: "Yes" Default value: "Boolean value specifying whether to show the control. Space that would be occupied by an invisible control is blank."
TOOLTIP  
  Optional;
 
  Flash
 
Default value: "Text to display when the mouse pointer hovers over the control."
HEIGHT  
  Optional;
 
  Flash
 
  The height of the control, in pixels.
 
WIDTH  
  Optional;
 
  Flash
 
  The width of the control, in pixels.