JSF 1.2 Text Area Component Properties Window
See Also
You see the Properties window for a Text Area component
when you select the component on a page that you are editing in the Visual Designer.
Most of the Text Area component's properties are both JSP attributes and properties of the TextArea
Java component in the page bean.
This JavaServer Faces 1.2 component has the following properties.
General
- id.
Type: String
The name of the Text Area component in the page bean and the JSP file.
Appearance
Data
- converter.
Type: Converter
A JavaServer Faces converter that produces the correct type of value for the text
property. If the user enters the wrong type of value, such as a word instead of a number for an Integer converter, the converter sends a message that you can display in a Message component. The component will pick the correct converter for the text
property if one is available, making it unnecessary to set this property in most cases. If the text
property is bound to a value whose type is not on the list of converters, you must supply your own converter and set this property.
- If you use an Enum converter with this component, you must edit the converter's Java declaration to use an
enum
class as a parameter, as described in Enum Converter.
- required.
Type: boolean
If selected, the user must enter a value in the field before the page can be submitted. If you add a Message component to the page and link its for
property to this component, an error message will be displayed if the user tries to submit the page without entering a value.
- validatorExpression.
Type: MethodExpression
Indicates the JavaServer Faces validator expression that is used when the value is submitted. A validator ensures
that the correct value is entered by a user. If the conditions defined by the validator are not met, the validator sends a message that you can display in a Message component.
Choose a validator from the drop down list. If you choose (null)
, no validator is called. If you choose a validator, you might also want to select the required
property to ensure that the user enters a value.
- You can define your own validation method, for example, by right-clicking the component and choosing Edit Event Handler > validate. If you define your own method, any value you might have set in this property is overridden.
Events
Set the event properties by right-clicking the component in the Visual Designer and choosing Edit Event Handler > eventname.
- valueChange. Indicates the name of the component value change listener method that is called when the value of the component changes. You typically define this method in the page bean by right-clicking the component in the Navigator window and choosing Edit Event Handler > processValueChange. The default name for the method is
component-id_processValueChange
, where component-id is the value of the id
property.
- validate. Indicates the name of the method that is called to validate the value of the component.
If you want to code a validate method rather than choosing a JavaServer Faces validator for the validatorExpression
property, right-click the component and choose Edit Event Handler > validate. The default name for the method is component-id_validate
, where component-id is the value of the component's id
property. When you define this method in this way, the validator
and validate
properties are automatically set for you. If you define a validator, you might also want to select the required
property to ensure that the user enters a value.
- Setting this property also sets the value of the
validatorExpression
property. If you define your own validate method, do not separately change the value of the validatorExpression
property, or you could lose the connection to your validate method.
Behavior
- autoSave.
Type: long
Indicates how often to check for changes and automatically save the Text Area component for server side processing using the JavaServer Faces Extensions partial lifecycle. The value of this property is an interval measured in milliseconds. Data is submitted only if the Text Area component has been modified during this interval. The default value, 0, indicates that auto-save is turned off. A negative number has the same effect as zero.
- autoValidate.
Type: boolean
Selecting this property causes an AJAX request to the validator on the component to be triggered by the JavaScript OnBlur event, and, if the validation passes, the contents of the Text Area component to be submitted for server side processing using the JavaServer Faces Extensions partial lifecycle.
By default, this property is unselected (false) and no auto-validation occurs. Setting autoValidate
also sets the ajaxify
property to true. Additionally, if you set autoValidate
, you must provide a validator for this component. (What happens if you set it and there's no validator?) See the validatorExpression property above for more information on providing a validator.
- disabled.
Type: boolean
If selected, indicates that the component should never receive focus or be included in a submit. Use this property when the component does not apply to the page. See the note under the readOnly
property concerning the effects of using the disabled
property versus the effects of using the readOnly
property.
- readOnly.
Type: boolean
If selected, makes it impossible for the user to enter values, but still makes it possible for the component's value to be submitted.
Use this property when the component does apply but must not be changed.
- A readonly field is included when the page is submitted, in contrast to a disabled field, which is not included when the page is submitted. If you use the
disabled
property, JavaServer Faces does not detect that any value at all was submitted.
- toolTip.
Type: String
Rendered as the HTML title
attribute of the component, which is readable by a screen reader and can be displayed as a tool tip.
- If the component is disabled, the tooltip will not display in most browsers.
- trim.
Type: boolean
If selected, any leading spaces or trailing spaces will be trimmed prior to conversion to the destination data type. This property is selected by default.
- visible.
Type: boolean
Indicates whether or not the component can be seen by the user on the rendered HTML page. This property is selected by default. If you deselect this property, the component's HTML code is rendered on the page, but the component is not visible in the browser because it is hidden by a style setting. Because the HTML code is rendered, the component can still be processed on form submissions, and users who view source in the browser can see the HTML code. In addition, your web application can use client-side JavaScript to show or hide the component.
- If you need to completely hide the component, for example, because it contains sensitive information that certain users should not see, deselect the
rendered
property.
Accessibility
- tabIndex.
Type: String
Optionally specifies the position of the component in the tab order of the document, determining when the component will get focus if the user tabs through the document. The value must be an integer between 0 and 32767. Equivalent to the tabindex
attribute of the HTML <input>
tag.
JavaScript
- onBlur.
Type: String
JavaScript to be executed when the component loses focus.
- onChange.
Type: String
JavaScript to be executed when the component loses focus and its value was modified after it gained focus.
- onClick.
Type: String
JavaScript to be executed when the user clicks the component.
- onDblClick.
Type: String
JavaScript to be executed when the user double-clicks the component.
- onFocus.
Type: String
JavaScript to be executed when the component gains focus.
- onKeyDown.
Type: String
JavaScript to be executed when the component has focus and a key is pressed.
- onKeyPress.
Type: String
JavaScript to be executed when the component has focus and a key is pressed and released.
- onKeyUp.
Type: String
JavaScript to be executed when the component has focus and a key is released.
- onMouseDown.
Type: String
JavaScript to be executed when the mouse cursor is over the component and the user presses down on the mouse button.
- onMouseMove.
Type: String
JavaScript to be executed when the user moves the mouse cursor within the component.
- onMouseOut.
Type: String
JavaScript to be executed when the user moves the mouse cursor away from the component after it has been over the component.
- onMouseOver.
Type: String
JavaScript to be executed when the user moves the mouse cursor onto the component.
- onMouseUp.
Type: String
JavaScript to be executed when the mouse cursor is over the component and the user releases the mouse button.
- onSelect.
Type: String
JavaScript to be executed when the user selects text in the component.
Advanced
- immediate.
Type: boolean
If this property is selected, when the user activates the component, the code in the page bean is executed before the validation, updating of model values, and so on. Essentially, code execution happens right away on the server, which then returns the page. A simpler way of getting this functionality is to associate the component with a virtual form, and then right-click the component and choose Auto-Submit on Change.
The most common example of an immediate action is a Cancel button. You make it immediate so that the normal validation and update steps can be skipped, but the action handler can still do whatever is necessary. Typically, the action handler will navigate back to some previous page. In some designs the action handler might also enqueue an informational message like "Transaction cancelled". It is possible to do more: for example, an application might record the fact that the user cancelled the current operation.
- rendered.
Type: boolean
If selected, the component is to be rendered and processed on any subsequent page submission. If not selected, the component doesn't appear on the page at all, not even as a hidden component. You can bind this property to a JavaBeans property that determines when the component does get rendered. To bind this property, click the ellipsis button (...) to the right of the property and choose Use Binding in the dialog box.
- See Also
- Text Area Component
- Working With Components
- Component Tasks: Quick Reference
Legal Notices