|
cftextarea
DescriptionPuts
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.
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"
secureUpload="true|false"
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 alsocfajaximport, 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 Developing ColdFusion Applications
HistoryColdFusion
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.
AttributesThe
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 must 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 Developing ColdFusion Applications.
|
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
|
|
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 Developing ColdFusion Applications.
|
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 Developing ColdFusion Applications.
|
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 Developing ColdFusion Applications.
|
secureUpload
|
Optional
|
true
|
If true, enables secure upload using FCKeditor.
For
secure upload, you must have sessionManagement set
to yes. Secure upload does not work if sessionManagement is
set to false.
If you do not use FCKeditor,
Adobe recommends that you set config.enabled=false in
the config.cfm available in the FCKeditor folder in cf_webRoot.
|
templatesXML
|
Optional; HTML
|
/CFIDE/scripts/ajax/FCKEditor/fcktemplates.xml
|
The path of 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 Developing ColdFusion Applications.
|
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 Developing ColdFusion Applications.
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:
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,
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 <cftextareaname="description"value="Enteradescription."/>.
|
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.
|
UsageFor 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.
ValidationFor
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 Developing ColdFusion Applications.
Flash form data bindingThe bind attribute
lets you populate form fields using the contents of other form fields.
To specify text from another Flash form field in a cftextareabind 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 bindingThe 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 Developing ColdFusion Applications.
ExampleThis
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>
|