webuijsf
Tag textArea


Use the webuijsf:textArea tag to create a multiple-line input field for text.

HTML Elements and Layout

The textArea component renders an HTML <textarea> element.

Configuring the webuijsf:textArea Tag

Use the text attribute to associate the component with a model object that represents the current value, by setting the attribute's value to a JavaServer Faces EL expression that evaluates to a backing bean or a backing bean property.

To optionally specify a label for the component, use the label attribute, or specify a label facet.

Facets

Theme Identifiers

The input element has a style class "TxtAra", or "TxtAraDis" when the field is disabled. If a label attribute is specified, the label element's class attribute is set to "LstAln" followed by "LblLvl1Txt", "LblLvl2Txt" or "LblLvl3Txt" depending on the label level.

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

getInputElement() Use this function to access the HTML <input> element that is rendered by the component.
getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
refresh(execute)
Use this function to asynchronously refresh the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • className
  • dir
  • disabled
  • id
  • label
  • lang
  • onClick
  • onDblClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • readOnly
  • required
  • size
  • style
  • tabIndex
  • title
  • valid
  • value
  • visible
submit(execute)
Use this function to asynchronously submit the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run. If omitted, the component on which the function has been invoked, is submitted.
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. For example, you can listen for the refresh event topic using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
            // Do something...
        }
    }

    // Subscribe to refresh event.
    var domNode = document.getElementById("form1:test1");
    domNode.subscribe(domNode.event.refresh.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id to process the event for
<Node>.event.refresh.endTopic

Event topic published after asynchronously refreshing the component. Supported properties include:

  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id to process the event for
<Node>.event.submit.endTopic

Event topic published after asynchronously submitting the component. Supported properties include:

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

Examples

Example 1: Text area with label and required icon

This example uses a backing bean FieldTest with a property string. The tag generates a label followed by text input field. The required attribute is set to true, which causes an icon to be rendered next to the label to indicate that the application user must enter a value in the text field. The icon, label and input elements are enclosed by a span.

     <webuijsf:textArea id="textArea" label="Enter a value:" 
text="#{FieldTest.string}"
required="true"/>

Example 2: Update client-side textArea properties using the getProps and setProps functions

This example shows how to toggle the disabled state of a text field client side using the getProps and setProps functions. When the user clicks the radio button, the text area is either disabled or enabled.
<webuijsf:radioButton id="rb1" name="rb1" label="Toggle Field Disabled" onClick="toggleDisabled()"/>
<webuijsf:textArea id="field1" text="My Text Field" />

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:field1"); // Get field
return domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle disabled state
}
</webuijsf:script>
Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 3: Asynchronously update textArea using refresh function

This example shows how to asynchronously update a text area using the refresh function. When the user clicks on the radio button, the text field is asynchronously updated with new data.
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Text Field" onClick="refreshField()"/>
<webuijsf:textArea id="field1" text="#{MyBean.text}" />

<webuijsf:script>
    function refreshField() {
        var domNode = document.getElementById("form1:field1"); // Get field
        return domNode.refresh(); // Asynchronously refresh field
    }
</webuijsf:script>


Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")

Example 4: Asynchronously submit textArea using submit function

This example shows how to asynchronously submit a text area using the submit function. When the user clicks on the radio button, the input value is updated server-side
<webuijsf:radioButton id="rb1" name="rb1" label="submit Text Field" onClick="submitField()"/>
<webuijsf:textArea id="field1" text="#{MyBean.text}" /> // Field used to asynchronously update text.

webuijsf:script>
    function
submitField() {
        var domNode = document.getElementById("form1:field1"); // Get field
        return domNode.submit();
    }
</webuijsf:script>

Note that the submit function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: submit("form1:id1,form2:id2,...")



Tag Information
Tag Classcom.sun.webui.jsf.component.TextAreaTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
submitFormfalsefalsejava.lang.String

SubmitForm attribute is disabled for TextArea. TextArea uses enter key to open new line.

maxLengthfalsefalsejava.lang.String The maximum number of characters that can be entered for this field.
rowsfalsefalsejava.lang.String

Number of rows used to render the textarea. You should set a value for this attribute to ensure that it is rendered correctly in all browsers. Browsers vary in the default number of rows used for textarea fields.

autoSavefalsefalsejava.lang.String Attribute indicating to turn on/off the Auto-save functionality of the TextArea.
Auto-save will submit the content of the modified textArea for server side processing that will be processed using JSFX partial lifecycle cycle. Only modified data will be submitted, that is textArea data will be submitted every autoSave milliseconds only if it has been modified within last interval.
AutoSave is specified in milliseconds. Value of 0 or less is interpreted as no auto-save.
By default auto-save = 0, meaning no auto-save will be activated.
onDblClickfalsefalsejava.lang.String

Scripting code executed when a mouse double click occurs over this component.

trimfalsefalsejava.lang.String

Flag indicating that any leading and trailing blanks will be trimmed prior to conversion to the destination data type. Default value is true.

onKeyPressfalsefalsejava.lang.String

Scripting code executed when the user presses and releases a key while the component has focus.

onSelectfalsefalsejava.lang.String

Scripting code executed when some text in this component value is selected.

onFocusfalsefalsejava.lang.String

Scripting code executed when this component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse.

renderedfalsefalsejava.lang.String Indicates whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
columnsfalsefalsejava.lang.String

Number of character columns used to render this field. The default is 20.

autoCompletefalsefalsejava.lang.String Attribute indicating to turn on/off the autocomplete functionality of the TextField. Autocomplete would trigger the AJAX request to the component.
Autocomplete will submit the content of the text field for server side processing that will be processed using JSFX partial lifecycle cycle. Providing of autoComplete options remains responsibility of the developer. Specifically, autoCompleteExpression needs to be set
By default autocomplete is off.
idfalsetruejava.lang.StringNo Description
onKeyUpfalsefalsejava.lang.String

Scripting code executed when the user releases a key while the component has focus.

onMouseUpfalsefalsejava.lang.String

Scripting code executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

stylefalsefalsejava.lang.String

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

onClickfalsefalsejava.lang.String

Scripting code executed when a mouse click occurs over this component.

onBlurfalsefalsejava.lang.String

Scripting code executed when this element loses focus.

onMouseDownfalsefalsejava.lang.String

Scripting code executed when the user presses a mouse button while the mouse pointer is on the component.

toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

converterfalsefalsejava.lang.String Specifies a method to translate native property values to String and back for this component. The converter attribute value must be one of the following:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
requiredfalsefalsejava.lang.String Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
disabledfalsefalsejava.lang.String

Flag indicating that the user is not permitted to activate this component, and that the component's value will not be submitted with the form.

validatorExpressionfalsefalsejava.lang.String Used to specify a method in a backing bean to validate input to the component. The value must be a JavaServer Faces EL expression that resolves to a public method with return type void. The method must take three parameters:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

onMouseOutfalsefalsejava.lang.String

Scripting code executed when a mouse out movement occurs over this component.

autoCompleteExpressionfalsefalsejava.lang.String Use the autoCompleteExpression to specify the method that will filter an autoCompleteExpression list, i.e. to produce new set of options to be rendered as autoComplete prompts ( see autoCompleteExpression) . When autoComplete mechanism is enabled ( by specifying autoComplete attribute), autoCompleteExpression method will be called using the Ajax mechanism in the background every time user changes the content of the field. Note that this requires autoCompleteExpression method to perform well. Also, it is recommended to limit number of options available to user as the return of this method - both for usability and in order to increase download speed.
The value of autoCompleteExpression must be an EL expression and it must evaluate to the name of a public method that is defined by com.sun.webui.jsf.model.AutoComplete, something like: public Options[] getOptions(String filter) { ... } In this example, expression would look like this: < webuijsf:textField autoComplete = "true" autoCompleteExpression ="#{AutoCompleteBean.getOptions}" text="#{AutoCompleteBean.text}" label = "AutoComplete" id = "tf" />
autoValidatefalsefalsejava.lang.String Attribute indicating to turn on/off the autovalidate functionality of the TextField. Autovalidate would trigger the AJAX request to the validator on the component. Setting autoValidate neccessitates that component is ajaxified, and so it will be accomplished automatically when autoValidate is set to true.
Autovalidate will submit the content of the text field for server side processing that will be processed using JSFX partial lifecycle cycle. Validation of the data remains responsibility of the developer. For example, validatorExpression still needs to be set
By default autovalidate is off.
onMouseOverfalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer into the boundary of this component.

htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

textfalsefalsejava.lang.String

Literal value to be rendered in this input field. If this property is specified by a value binding expression, the corresponding value will be updated if validation succeeds.

immediatefalsefalsejava.lang.String Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.
labelfalsefalsejava.lang.String

If set, a label is rendered adjacent to the component with the value of this attribute as the label text.

onChangefalsefalsejava.lang.String

Scripting code executed when the element value of this component is changed.

visiblefalsefalsejava.lang.String

Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page.

onKeyDownfalsefalsejava.lang.String

Scripting code executed when the user presses down on a key while the component has focus.

readOnlyfalsefalsejava.lang.String

Flag indicating that modification of this component by the user is not currently permitted, but that it will be included when the form is submitted.

labelLevelfalsefalsejava.lang.String

Sets the style level for the generated label, provided the label attribute has been set. Valid values are 1 (largest), 2 and 3 (smallest). The default value is 2.

valueChangeListenerExpressionfalsefalsejava.lang.String Specifies a method to handle a value-change event that is triggered when the user enters data in the input component. The attribute value must be a JavaServer Faces EL expression that resolves to a backing bean method. The method must take a single parameter of type javax.faces.event.ValueChangeEvent, and its return type must be void. The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.
tabIndexfalsefalsejava.lang.String

Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.

notifyfalsefalsejava.lang.String The comma separated list of absolute client IDs to notify during text field events.

Currently, this feature is only supported by label and alert components. For example, when the label attribute of the textField tag is not used. Or, when an alert is used in the page to display validation messages.

During auto-validation, the text field will notify the label and alert associated with the given client IDs. If the user's input is found to be invalid, the label will change text color and display an error indicator. Likewise, if there are any messages associated with the event, the alert will display the assocaited summary, detail, and error indicator.


Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.