Text components allow users to view and edit text in web applications. The basic types of text components are as follows:
Label, which displays read-only text
Text field, which allows users to enter text, often to be submitted as part of a form
Text area, which is a type of text field that allows users to enter multiple lines of text
Password field, which is a type of text field that displays a set of characters, such as asterisks, instead of the password text that the user enters
Figure 7–2 shows examples of these text components.
Text components can be categorized as either input or output. A JavaServer Faces output component is rendered as read-only text. An example is a label. A JavaServer Faces input component is rendered as editable text. An example is a text field.
The input and output components can each be rendered in various ways to display more specialized text.
Table 7–3 lists the tags that represent the input components.
Table 7–3 Input Tags
Tag |
Function |
---|---|
Allows a page author to include a hidden variable in a page |
|
The standard password field: accepts one line of text with no spaces and displays it as a set of asterisks as it is typed |
|
The standard text field: accepts a one-line text string |
|
The standard text area: accepts multiple lines of text |
The input tags support the tag attributes shown in Table 7–4 in addition to those described in Common Component Tag Attributes. Note that this table does not include all the attributes supported by the input tags but just those that are used most often. For the complete list of attributes, refer to the documentation at http://download.oracle.com/javaee/6/javaserverfaces/2.0/docs/pdldocs/facelets/.
Table 7–4 Input Tag Attributes
Attribute |
Description |
---|---|
Identifies a converter that will be used to convert the component’s local data. See Using the Standard Converters for more information on how to use this attribute. |
|
converterMessage |
Specifies an error message to display when the converter registered on the component fails. |
dir |
Specifies the direction of the text displayed by this component. Acceptable values are LTR, meaning left-to-right, and RTL, meaning right-to-left. |
label |
Specifies a name that can be used to identify this component in error messages. |
lang |
Specifies the code for the language used in the rendered markup, such as en_US. |
required |
Takes a boolean value that indicates whether the user must enter a value in this component. |
requiredMessage |
Specifies an error message to display when the user does not enter a value into the component. |
Identifies a method expression pointing to a backing bean method that performs validation on the component’s data. See Referencing a Method That Performs Validation for an example of using the f:validator tag. |
|
f:validatorMessage |
Specifies an error message to display when the validator registered on the component fails to validate the component’s local value. |
Identifies a method expression that points to a backing bean method that handles the event of entering a value in this component. See Referencing a Method That Handles a Value-Change Event for an example of using valueChangeListener. |
Table 7–5 lists the tags that represent the output components.
Table 7–5 Output Tags
Tag |
Function |
---|---|
Displays a localized message |
|
The standard read-only label: displays a component as a label for a specified input field |
|
Displays an <a href> tag that links to another page without generating an action event |
|
Displays a one-line text string |
The output tags support the converter tag attribute in addition to those listed in Common Component Tag Attributes.
The rest of this section explains how to use some of the tags listed in Table 7–3 and Table 7–5. The other tags are written in a similar way.
The h:inputText tag is used to display a text field. A similar tag, the h:outputText tag, displays a read-only, single-line string. This section shows you how to use the h:inputText tag. The h:outputText tag is written in a similar way.
Here is an example of an h:inputText tag:
<h:inputText id="name" label="Customer Name" size="50" value="#{cashier.name}" required="true" requiredMessage="#{customMessages.CustomerName}"> <f:valueChangeListener type="com.sun.bookstore6.listeners.NameChanged" /> </h:inputText>
The label attribute specifies a user-friendly name that will be used in the substitution parameters of error messages displayed for this component.
The value attribute refers to the name property of a backing bean named CashierBean. This property holds the data for the name component. After the user submits the form, the value of the name property in CashierBean will be set to the text entered in the field corresponding to this tag.
The required attribute causes the page to reload, displaying errors, if the user does not enter a value in the name text field. The JavaServer Faces implementation checks whether the value of the component is null or is an empty string.
If your component must have a non-null value or a String value at least one character in length, you should add a required attribute to your tag and set its value to true. If your tag has a required attribute that is set to true and the value is null or a zero-length string, no other validators that are registered on the tag are called. If your tag does not have a required attribute set to true, other validators that are registered on the tag are called, but those validators must handle the possibility of a null or zero-length string. See Validating Null and Empty Strings for more information.
The h:inputSecret tag renders an <input type="password"> HTML tag. When the user types a string into this field, a row of asterisks is displayed instead of the text typed by the user. Here is an example:
<h:inputSecret redisplay="false" value="#{LoginBean.password}" />
In this example, the redisplay attribute is set to false. This will prevent the password from being displayed in a query string or in the source file of the resulting HTML page.
The h:outputLabel tag is used to attach a label to a specified input field for the purpose of making it accessible. The following page uses an h:outputLabel tag to render the label of a check box:
<h:selectBooleanCheckbox id="fanClub" binding="#{cashier.specialOffer}" /> <h:outputLabel for="fanClub" binding="#{cashier.specialOfferText}" > <h:outputText id="fanClubLabel" value="#{bundle.DukeFanClub}" /> </h:outputLabel> ...
The for attribute of the h:outputLabel tag maps to the id of the input field to which the label is attached. The h:outputText tag nested inside the h:outputLabel tag represents the label component. The value attribute on the h:outputText tag indicates the text that is displayed next to the input field.
Instead of using an h:outputText tag for the text displayed as a label, you can simply use the h:outputLabel tag’s value attribute. The following code snippet shows what the previous code snippet would look like if it used the value attribute of the h:outputLabel tag to specify the text of the label:
<h:selectBooleanCheckbox id="fanClub" binding="#{cashier.specialOffer}" /> <h:outputLabel for="fanClub" binding="#{cashier.specialOfferText}" value="#{bundle.DukeFanClub}" /> </h:outputLabel> ...
The h:outputLink tag is used to render a hyperlink that, when clicked, loads another page but does not generate an action event. You should use this tag instead of the h:commandLink tag if you always want the URL specified by the h:outputLink tag’s value attribute to open and do not want any processing to be performed when the user clicks the link. Here is an example:
<h:outputLink value="javadocs"> Documentation for this demo </h:outputLink>
The text in the body of the outputLink tag identifies the text that the user clicks to get to the next page.
The h:outputFormat tag allows display of concatenated messages as a MessageFormat pattern, as described in the API documentation for java.text.MessageFormat. Here is an example of an outputFormat tag:
<h:outputFormat value="Hello, {0}!"> <f:param value="#{hello.name}"/> </h:outputFormat>
The value attribute specifies the MessageFormat pattern. The param tag specifies the substitution parameters for the message. The value of the parameter replaces the {0} in the sentence. If the value of "#{hello.name}" is “Bill”, the message displayed in the page is as follows:
Hello, Bill! |
An h:outputFormat tag can include more than one param tag for those messages that have more than one parameter that must be concatenated into the message. If you have more than one parameter for one message, make sure that you put the param tags in the proper order so that the data is inserted in the correct place in the message. Here is the preceding example modified with an additional parameter:
<h:outputFormat value="Hello, {0}! You are visitor number {1} to the page."> <f:param value="#{hello.name}" /> <f:param value="#{bean.numVisitor}"/> </h:outputFormat>
The value of {1} is replaced by the second parameter. The parameter is an EL expression, bean.numVisitor, where the property numVisitor of the backing bean bean keeps track of visitors to the page. This is an example of a value-expression-enabled tag attribute accepting an EL expression. The message displayed in the page is now as follows:
Hello, Bill! You are visitor number 10 to the page. |