Adobe ColdFusion 8

cftextarea

Description

Puts a multiline text entry box in a cfform tag and controls its display characteristics. Optionally, displays a rich text editor with configurable controls for formatting HTML text.

Category

Forms tags

Syntax

<cftextarea 
    name="name"
    basepath="path"
    bind="bind expression"
    bindAttribute="attribute name"
    bindOnLoad="false|true"
    disabled="true|false" or no attribute value
    enabled="yes|no"
    fontFormats="comma separated list"
    fontNames="comma separated list"
    fontSizes="comma separated list"
    height="number of pixels"
    html="no|yes"
    label="text"
    maxlength="number"
    message="text"
    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="regexp"
    range="minimum value, maximum value"
    required="yes|no"
    richtext="no|yes"
    skin="default|silver|office2003|custom skin"
    sourceForToolTip="URL"
    style="style specification"
    stylesXML="path"
    templatesXML"path"
    toolbar="default|basic|custom toolbar"
    toolbarOnFocus"no|yes"
    tooltip="tip text"
    validate="data type"
    validateAt= one or more of "onBlur, onServer, onSubmit"
    value="text"
    visible="yes|no"
    width="number of pixels"
    wrap="off|hard|soft|virtual|physical">

        text

</cftextarea>

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

Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

See also

cfajaximport, cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfselect, cfslider, cftree; "Introduction to Retrieving and Formatting Data" and "Using Ajax form controls and features" in the ColdFusion Developer's Guide

History

ColdFusion 8:

  • Added support for the bind attribute in HTML format forms, including the bindAttribute, bindOnLoad, and onBindError attributes.
  • Added support for tool tips in HTML format, including the sourceForTooltip attribute.
  • Added support for a rich text editor in HTML format, including the richtext, basepath, fontFormats, fontNames, fontSizes, skin, stylesXML, templatesXML, toolbar, and toolbarOnFocus attributes and support for the height and width attributes.

ColdFusion MX 7: Added this tag.

Attributes

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 not marked as All or XML are not handled by the skins provided with ColdFusion. They are, however, included in the generated XML.

Attribute

Req/Opt;

Format

Default

Description

name

Required;

All

 

Name of the cftextinput control.

basepath

Optional; HTML

/CFIDE/scripts/ajax/FCKEditor

Path to the directory that contains the rich text editor. The editor configuration files are at the top level of this directory.

Meaningful only if the richText attribute is true.

bind

Optional;

Flash,

HTML

 

A bind expression that dynamically sets an attribute of the control. For details, see Usage.

bindAttribute

Optional;

HTML

value

Specifies the HTML tag attribute whose value is set by the bind attribute. You can only specify attributes in the browser's HTML DOM tree, not ColdFusion-specific attributes.

Ignored if there is no bind attribute.

bindOnLoad

Optional;

HTML

no

A Boolean value that specifies whether to execute the bind attribute expression when first loading the form. Ignored if there is no bind attribute.

disabled

Optional;

All

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

enabled

Optional;

Flash

yes

Boolean value that specifies whether the control is enabled. A disabled control appears in light gray. The inverse of the disabled attribute.

fontFormats

Optional; HTML

All valid formats

A comma separated list of the font names to display in the rich text editor Formats selector. The formats specify the HTML tags to apply to typed or selected text. You can specify any subset of the following list: "p,div,pre,address,h1,h2,h3,h4,h5,h6".

fontNames

Optional; HTML

All valid font names

A comma separated list of the font names to display in the rich text editor Font selector. You can specify any subset of the following list: "Arial,Comic Sans MS,Courier New,Tahoma,Times New Roman,Verdana".

FontSizes

Optional; HTML

See Description

A comma separated list of the font sizes to display in the rich text editor Size selector. List entries must have the format of numeric font size/descriptive text. For example, to display the text "small font" to indicate a font size of 1, specify "1/small font". By default, the following values appear in the selector: 1/xx-small,2/x-small,3/small,4/medium,5/large,6/x-large,7/xx-large.

height

Optional;

Flash,

HTML

 

In Flash forms, height of the control, in pixels.

In HTML forms, this attribute has an effect only if you specify richtext="true"; in this case, it is the height, in pixels, of the control, including the control bar and text box.

html

Optional;

Flash

no

Boolean value that specifies whether the text area contains HTML.

label

Optional;

Flash and XML

 

Label to put beside the control on a form.

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.

message

Optional;

All

 

Message text to display if validation fails.

onBindError

Optional;

HTML

See Description

The name of a JavaScript function to execute if evaluating a bind expression results in an error. The function must take two attributes: an HTTP status code and a message. (The status code is -1 if the error is not an HTTP error.)

If you omit this attribute, and have specified a global error handler (by using the ColdFusion.setGlobalErrorHandler function), it displays the error message; otherwise a default error pop-up displays.

onChange

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) to run when the control changes due to user action.

onClick

Optional;

HTML and XML

 

JavaScript to run when the user clicks the control.

onError

Optional;

HTML and XML

 

Custom JavaScript function to execute if validation fails.

onKeyDown

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) ActionScript to run when the user presses a keyboard key in the control.

onKeyUp

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a keyboard key in the control.

onMouseDown

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) to run when the user releases a mouse button in the control.

onMouseUp

Optional;

All

 

JavaScript (HTML/XML) or ActionScript (Flash) to run when the user presses a mouse button in the control.

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 the function, which should return True if validation succeeds, False otherwise. If you specify this attribute, ColdFusion ignores 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 "Building Dynamic Forms with cfform Tags" in the ColdFusion Developer's Guide.

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.

required

Optional;

All

no

  • yes: the field must contain text.
  • no: the field can be empty.

richText

Optional; HTML

no

A Boolean value specifying whether this control is a rich text editor with tool bars to control the text formatting. For detailed information on using the rich text editor, see "Using the rich text editor" in the ColdFusion Developer's Guide.

skin

Optional; HTML

default

Specifies the skin to be used for the rich text editor. By default, the valid values are Default, silver, and office2003. You can also create custom skins that you can then specify in this attribute. For more information, see "Using the rich text editor" in the ColdFusion Developer's Guide.

sourceForTooltip

Optional; HTML

 

The URL of a page to display as a tool tip. The page can include CFML and HTML to control the contents and format, and the tip can include images.

If you specify this attribute, an animated icon appears with the text "Loading..." while the tip is being loaded.

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 Flex for the corresponding Flash element.

stylesXML

Optional; HTML

/CFIDE/scripts/ajax/FCKEditor/fckstyles.xml

The path of the file that defines the styles in the rich text editor Styles selector. Relative paths start at the directory that contains the fckeditor.html file, normally cf_webRoot/CFIDE/scripts/ajax/FCKeditor/editor. You can specify an absolute path starting at the web root, such as /myApps/RTEeditor.mystyles.xml. For information on configuring styles, see "Using the rich text editor" in the ColdFusion Developer's Guide.

templatesXML

Optional; HTML

/CFIDE/scripts/ajax/FCKEditor/fcktemplates.xml

The pathof the file that defines the templates that are displayed when you click the rich text editor Templates icon. For pathing details, see stylesXML. For information on configuring templates, see "Using the rich text editor" in the ColdFusion Developer's Guide.

toolbar

Optional; HTML

default

Specifies the rich text editor toolbar. By default, the valid values for this attribute are: Default, a complete set of controls, and Basic, a minimal configuration. You can add configurations; for details see "Using the rich text editor" in the ColdFusion Developer's Guide.

Note: This attribute's value is case sensitive.

toolbarOnFocus

Optional; HTML

no

A Boolean value that specifies whether the rich text editor toolbar expands and displays its controls only when the rich text editor has the focus.

tooltip

Optional; Flash, HTML

 

Text to display when the mouse pointer hovers over the control. Can include HTML formatting.

Ignored if you specify a sourceForTooltip attribute.

validate

Optional;

All

 

The type or types of validation to perform. 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

onSubmit

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

  • onSubmit
  • onServer
  • onBlur

For Flash format forms, onSubmit and onBlur are identical; for both, 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.

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

visible

Optional;

Flash

yes

Boolean value that specifies whether to show the control. Space that would be occupied by an invisible control is blank.

width

Optional;

Flash,

HTML

 

The width of the control, in pixels.

In HTML forms, this attribute has an effect only if you specify richtext="true".

wrap

Optional

All

 
  • hard: wraps long lines, and sends the carriage return to the server.
  • off: does not wrap long lines.
  • physical: wraps long lines, and transmits the text at all wrap points.
  • soft: wraps long lines, but does not send the carriage return to the server.
  • virtual: wraps long lines, but does not send the carriage return to the server.

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 validation techniques, see "Validating Data" in the ColdFusion 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 Flash form 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.

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

HTML form data binding

The bind attribute lets you set any cftextarea attribute dynamically from the value of another form control or by calling a CFC or JavaScript function. By default it sets the control's value attribute, but you can specify a different attribute to set by using the bindAttribute attribute. For more information on binding, see "Binding data to form fields" in the ColdFusion Developer's Guide.

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>