Download PDF Home History |  | API Search Feedback FAQ

> ## Using the HTML Component Tags

> The tags defined by the JavaServer Faces standard HTML render kit tag library represent HTML form controls and other basic HTML elements. These controls display data or accept data from the user. This data is collected as part of a form and is submitted to the server, usually when the user clicks a button. This section explains how to use each of the component tags shown in Table 17-2, and is organized according to the `UIComponent` classes from which the tags are derived.

> The next section explains the more important tag attributes that are common to most component tags. Please refer to the TLD documentation at `http://java.sun.com/j2ee/javaserverfaces/1.1/docs/tlddocs/index.html` for a complete list of tags and their attributes.

> For each of the components discussed in the following sections, Writing Component Properties explains how to write a bean property bound to a particular UI component or its value.

> ### UI Component Tag Attributes

> In general, most of the component tags support these attributes:

> - `id`: Uniquely identifies the component
> - `immediate`: If set to `true`, indicates that any events, validation, and conversion associated with the component should happen in the apply request values phase rather than a later phase.
> - `rendered`: Specifies a condition in which the component should be rendered. If the condition is not satisfied, the component is not rendered.
> - `style`: Specifies a Cascading Style Sheet (CSS) style for the tag.
> - `styleClass`: Specifies a CSS stylesheet class that contains definitions of the styles.
> - `value`: Identifies an external data source and binds the component's value to it.
> - `binding`: Identifies a bean property and binds the component instance to it.

> All of the UI component tag attributes (except `id` and `var`) are value-binding-enabled, which means that they accept JavaServer Faces EL expressions. These expressions allow you to use mixed literals and JSP 2.0 expression language syntax and operators. See Expression Language for more information about the JSP 2.0 expression language.

> #### The id Attribute

> The `id` attribute is not required for a component tag except in these situations:

> - Another component or a server-side class must refer to the component.
> - The component tag is impacted by a JSTL conditional or iterator tag (for more information, see Flow Control Tags).

> If you don't include an `id` attribute, the JavaServer Faces implementation automatically generates a component ID.

> #### The immediate Attribute

> `UIInput` components and command components (those that implement `ActionSource`, such as buttons and hyperlinks`)` can set the `immediate` attribute to `true` to force events, validations, and conversions to be processed during the apply request values phase of the life cycle. Page authors need to carefully consider how the combination of an input component's `immediate` value and a command component's `immediate` value determines what happens when the command component is activated.

> Assume that you have a page with a button and a field for entering the quantity of a book in a shopping cart. If both the button's and the field's `immediate` attributes are set to `true`, the new value of the field will be available for any processing associated with the event that is generated when the button is clicked. The event associated with the button and the event, validation, and conversion associated with the field are all handled during the apply request values phase.

> If the button's `immediate` attribute is set to `true` but the field's `immediate` attribute is set to `false`, the event associated with the button is processed without updating the field's local value to the model layer. This is because any events, conversion, or validation associated with the field occurs during its usual phases of the life cycle, which come after the apply request values phase.

> The `bookshowcart.jsp` page of the Duke's Bookstore application has examples of components using the `immediate` attribute to control which component's data is updated when certain buttons are clicked. The `quantity` field for each book has its `immediate` attribute set to `false`. (The `quantity` fields are generated by the `UIData` component. See The UIData Component, for more information.) The `immediate` attribute of the Continue Shopping hyperlink is set to `true`. The `immediate` attribute of the Update Quantities hyperlink is set to `false`.

> If you click the Continue Shopping hyperlink, none of the changes entered into the quantity input fields will be processed. If you click the Update Quantities hyperlink, the values in the quantity fields will be updated in the shopping cart.

> #### The rendered Attribute

> A component tag uses a Boolean JavaServer Faces expression language (EL) expression, along with the `rendered` attribute, to determine whether or not the component will be rendered. For example, the `check` `commandLink` component on the `bookcatalog.jsp` page is not rendered if the cart contains no items:

>     <h:commandLink id="check"
>       ...
>       rendered="#{cart.numberOfItems > 0}">
>       <h:outputText
>         value="#{bundle.CartCheck}"/>
>     </h:commandLink>

> #### The style and styleClass Attributes

> The `style` and `styleClass` attributes allow you to specify Cascading Style Sheets (CSS) styles for the rendered output of your component tags. The UIMessage and UIMessages Components describes an example of using the `style` attribute to specify styles directly in the attribute. A component tag can instead refer to a CSS stylesheet class. The `dataTable` tag on the `bookcatalog.jsp` page of the Duke's Bookstore application references the style class `list-background`:

>     <h:dataTable id="books"
>       ...
>       styleClass="list-background"
>       value="#{bookDBAO.books}"
>       var="book">

> The stylesheet that defines this class is `stylesheet.css`, which is included in the application. For more information on defining styles, please the see Cascading Style Sheets Specification at `http://www.w3.org/Style/CSS/`.

> #### The value and binding Attributes

> A tag representing a component defined by `UIOutput` or a subclass of `UIOutput` uses `value` and `binding` attributes to bind its component's value or instance respectively to an external data source. Binding Component Values and Instances to External Data Sources explains how to use these attributes.

> ### The UIForm Component

> A `UIForm` component represents an input form that has child components representing data that is either presented to the user or submitted with the form. The `form` tag encloses all the controls that display or collect data from the user. Here is an example:

>     <h:form>
>     ... other JavaServer Faces tags and other content...
>     </h:form>

> The `form` tag can also include HTML markup to lay out the controls on the page. The `form` tag itself does not perform any layout; its purpose is to collect data and to declare attributes that can be used by other components in the form. A page can include multiple `form` tags, but only the values from the form that the user submits will be included in the postback.

> ### The UIColumn Component

> The `UIColumn` component represents a column of data in a `UIData` component. While the `UIData` component is iterating over the rows of data, it processes the `UIColumn` component for each row. `UIColumn` has no renderer associated with it and is represented on the page with a `column` tag. Here is an example `column` tag from the `bookshowcart.jsp` page of the Duke's Bookstore example:

>     <h:dataTable id="items"
>       ...
>       value="#{cart.items}"
>       var="item">
>       ...
>       <h:column>
>         <f:facet name="header">
>           <h:outputText value="#{bundle.ItemQuantity}"/>
>         </f:facet>
>         <h:inputText
>           ...
>           value="#{item.quantity}">
>           <f:validateLongRange minimum="1"/>
>         </h:inputText>
>       </h:column>
>       ...
>     </h:dataTable>

> The `UIData` component in this example iterates through the list of books (`cart.items`) in the shopping cart and displays their titles, authors, and prices. The `column` tag shown in the example renders the column that displays text fields that allow customers to change the quantity of each book in the shopping cart. Each time `UIData` iterates through the list of books, it renders one cell in each column.

> ### The UICommand Component

> The `UICommand` component performs an action when it is activated. The most common example of such a component is the button. This release supports `Button` and `Link` as `UICommand` component renderers.

> In addition to the tag attributes listed in Using the HTML Component Tags, the `commandButton` and `commandLink` tags can use these attributes:

> - `action`, which is either a logical outcome `String` or a method-binding expression that points to a bean method that returns a logical outcome `String`. In either case, the logical outcome `String` is used by the default `NavigationHandler` instance to determine what page to access when the `UICommand` component is activated.
> - `actionListener`, which is a method-binding expression that points to a bean method that processes an action event fired by the `UICommand` component.

> See Referencing a Method That Performs Navigation for more information on using the `action` attribute.

> See Referencing a Method That Handles an Action Event for details on using the `actionListener` attribute.

> #### Using the commandButton Tag

> The `bookcashier.jsp` page of the Duke's Bookstore application includes a `commandButton` tag. When a user clicks the button, the data from the current page is processed, and the next page is opened. Here is the `commandButton` tag from `bookcashier.jsp`:

>     <h:commandButton value="#{bundle.Submit}"
>       action="#{cashier.submit}"/>

> Clicking the button will cause the `submit` method of `CashierBean` to be invoked because the `action` attribute references the `submit` method of the `CashierBean` backing bean. The `submit` method performs some processing and returns a logical outcome. This is passed to the default `NavigationHandler`, which matches the outcome against a set of navigation rules defined in the application configuration resource file.

> The `value` attribute of the preceding example `commandButton` tag references the localized message for the button's label. The `bundle` part of the expression refers to the `ResourceBundle` that contains a set of localized messages. The `Submit` part of the expression is the key that corresponds to the message that is displayed on the button. For more information on referencing localized messages, see Using Localized Messages. See Referencing a Method That Performs Navigation for information on how to use the `action` attribute.

> #### Using the commandLink Tag

> The `commandLink` tag represents an HTML hyperlink and is rendered as an HTML `<a>` element. The `commandLink` tag is used to submit an action event to the application. See Implementing Action Listeners for more information on action events.

> A `commandLink` tag must include a nested `outputText` tag, which represents the text the user clicks to generate the event. The following tag is from the `chooselocale.jsp` page from the Duke's Bookstore application.

>     <h:commandLink id="NAmerica" action="bookstore"
>       actionListener="#{localeBean.chooseLocaleFromLink}">
>       <h:outputText value="#{bundle.English}" />
>     </h:commandLink>

> This tag will render the following HTML:

>     <a id="_id3:NAmerica" href="#"
>       onclick="document.forms['_id3']['_id3:NAmerica'].
>       value='_id3:NAmerica';
>       document.forms['_id3'].submit();
>       return false;">English</a>

> Note: Notice that the `commandLink` tag will render JavaScript. If you use this tag, make sure your browser is JavaScript-enabled.

> ### The UIData Component

> The `UIData` component supports data binding to a collection of data objects. It does the work of iterating over each record in the data source. The standard `Table` renderer displays the data as an HTML table. The `UIColumn` component represents a column of data within the table. Here is a portion of the `dataTable` tag used by the `bookshowcart.jsp` page of the Duke's Bookstore example:

>     <h:dataTable id="items"
>       columnClasses="list-column-center, list-column-left,
>         list-column-right, list-column-center"
>       footerClass="list-footer"
>       headerClass="list-header"
>       rowClasses="list-row-even, list-row-odd"
>       styleClass="list-background"
>       value="#{cart.items}"
>       var="item">
>       <h:column >
>         <f:facet name="header">
>           <h:outputText value="#{bundle.ItemQuantity}" />
>         </f:facet>
>         <h:inputText id="quantity" size="4"
>           value="#{item.quantity}" >
>           ...
>         </h:inputText>
>         ...
>       </h:column>
>       <h:column>
>         <f:facet name="header">
>           <h:outputText value="#{bundle.ItemTitle}"/>
>         </f:facet>
>         <h:commandLink action="#{showcart.details}">
>           <h:outputText value="#{item.item.title}"/>
>         </h:commandLink>
>       </h:column>
>       ...
>       <f:facet name="footer"
>         <h:panelGroup>
>           <h:outputText value="#{bundle.Subtotal}"/>
>           <h:outputText value="#{cart.total}" />
>             <f:convertNumber type="currency" />
>           </h:outputText>
>         </h:panelGroup>
>       </f:facet>
>     </h:dataTable>

> Figure 18-1 shows a data grid that this `dataTable` tag can display.

> Figure 18-1 Table on the `bookshowcart.jsp` Page

> The example `dataTable` tag displays the books in the shopping cart as well as the quantity of each book in the shopping cart, the prices, and a set of buttons, which the user can click to remove books from the shopping cart.

> The `facet` tag inside the first `column` tag renders a header for that column. The other column tags also contain `facet` tags. Facets can have only one child, and so a `panelGroup` tag is needed if you want to group more than one component within a `facet`. Because the facet tag representing the footer includes more than one tag, the `panelGroup` is needed to group those tags.

> A `facet` tag is usually used to represent headers and footers. In general, a facet is used to represent a component that is independent of the parent-child relationship of the page's component tree. In the case of a data grid, header and footer data is not repeated like the other rows in the table, and therefore, the elements representing headers and footers are not updated as are the other components in the tree.

> This table is a classic use case for a `UIData` component because the number of books might not be known to the application developer or the page author at the time the application is developed. The `UIData` component can dynamically adjust the number of rows of the table to accommodate the underlying data.

> The `value` attribute of a `dataTable` tag references the data to be included in the table. This data can take the form of

> - A list of beans
> - An array of beans
> - A single bean
> - A `javax.faces.model.DataModel`
> - A `java.sql.ResultSet`
> - A `javax.servlet.jsp.jstl.sql.ResultSet`
> - A `javax.sql.RowSet`

> All data sources for `UIData` components have a `DataModel` wrapper. Unless you explicitly construct a `DataModel` wrapper, the JavaServer Faces implementation will create one around data of any of the other acceptable types. See Writing Component Properties for more information on how to write properties for use with a `UIData` component.

> The `var` attribute specifies a name that is used by the components within the `dataTable` tag as an alias to the data referenced in the `value` attribute of `dataTable`.

> In the `dataTable` tag from the `bookshowcart.jsp` page, the `value` attribute points to a list of books. The `var` attribute points to a single book in that list. As the `UIData` component iterates through the list, each reference to `item` points to the current book in the list.

> The `UIData` component also has the ability to display only a subset of the underlying data. This is not shown in the preceding example. To display a subset of the data, you use the optional `first` and `rows` attributes.

> The `first` attribute specifies the first row to be displayed. The `rows` attribute specifies the number of rows--starting with the first row--to be displayed. For example, if you wanted to display records 2 through 10 of the underlying data, you would set `first` to 2 and `rows` to 9. When you display a subset of the data in your pages, you might want to consider including a link or button that causes subsequent rows to display when clicked. By default, both `first` and `rows` are set to zero, and this causes all the rows of the underlying data to display.

> The `dataTable` tag also has a set of optional attributes for adding styles to the table:

> - `columnClasses`: Defines styles for all the columns
> - `footerClass`: Defines styles for the footer
> - `headerClass`: Defines styles for the header
> - `rowClasses`: Defines styles for the rows
> - `styleClass`: Defines styles for the entire table

> Each of these attributes can specify more than one style. If `columnClasses` or `rowClasses` specifies more than one style, the styles are applied to the columns or rows in the order that the styles are listed in the attribute. For example, if `columnClasses` specifies styles `list-column-center` and `list-column-right` and if there are two columns in the table, the first column will have style `list-column-center`, and the second column will have style `list-column-right`.

> If the `style` attribute specifies more styles than there are columns or rows, the remaining styles will be assigned to columns or rows starting from the first column or row. Similarly, if the `style` attribute specifies fewer styles than there are columns or rows, the remaining columns or rows will be assigned styles starting from the first style.

> ### The UIGraphic Component

> The `UIGraphic` component displays an image. The Duke's Bookstore application uses a `graphicImage` tag to display the map image on the `chooselocale.jsp` page:

>     <h:graphicImage id="mapImage" url="/template/world.jpg"
>       alt="#{bundle.chooseLocale}" usemap="#worldMap" />

> The `url` attribute specifies the path to the image. It also corresponds to the local value of the `UIGraphic` component so that the URL can be retrieved, possibly from a backing bean. The URL of the example tag begins with a /, which adds the relative context path of the Web application to the beginning of the path to the image.

> The `alt` attribute specifies the alternative text displayed when the user mouses over the image. In this example, the `alt` attribute refers to a localized message. See Performing Localization for details on how to localize your JavaServer Faces application.

> The `usemap` attribute refers to the image map defined by the custom component, `MapComponent`, which is on the same page. See Chapter 20 for more information on the image map.

> ### The UIInput and UIOutput Components

> The `UIInput` component displays a value to the user and allows the user to modify this data. The most common example is a text field. The `UIOutput` component displays data that cannot be modified. The most common example is a label.

> The `UIInput` and `UIOutput` components can each be rendered in four ways. Table 18-3 lists the renderers of `UIInput` and `UIOutput`. Recall from Component Rendering Model that the tags are composed of the component and the renderer. For example, the `inputText` tag refers to a `UIInput` component that is rendered with the `Text` renderer.

> Table 18-3 UIInput and UIOutput Renderers
> Component | Renderer | Tag | Function
> --- | --- | --- | ---
> `UIInput` | `Hidden` | `inputHidden` | Allows a page author to include a hidden variable in a page
> `Secret` | `inputSecret` | Accepts one line of text with no spaces and displays it as a set of asterisks as it is typed
> Text | `inputText` | Accepts a text string of one line
> `TextArea` | `inputTextarea` | Accepts multiple lines of text
> `UIOutput` | `Label` | `outputLabel` | Displays a nested component as a label for a specified input field
> `Link` | `outputLink` | Displays an `<a href>` tag that links to another page without generating an action event
> `OutputMessage` | `outputFormat` | Displays a localized message
> Text | `outputText` | Displays a text string of one line

> The `UIInput` component supports the following tag attributes in addition to the tag attributes described at the beginning of Using the HTML Component Tags. The `UIOutput` component supports the first of the following tag attributes in addition to those listed in Using the HTML Component Tags.

> - `converter`: 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.
> - `validator`: Identifies a method-binding 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 `validator` tag.
> - `valueChangeListener`: Identifies a method-binding 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`.

> The rest of this section explains how to use selected tags listed in Table 18-3. The other tags are written in a similar way.

> #### Using the outputText and inputText Tags

> The `Text` renderer can render both `UIInput` and `UIOutput` components. The `inputText` tag displays and accepts a single-line string. The `outputText` tag displays a single-line string. This section shows you how to use the `inputText` tag. The `outputText` tag is written in a similar way.

> Here is an example of an `inputText` tag from the `bookcashier.jsp` page:

>     <h:inputText id="name" size="50"
>       value="#{cashier.name}"
>       required="true">
>       <f:valueChangeListener type="listeners.NameChanged" />
>     </h:inputText>

> The `value` attribute refers to the `name` property of `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 with errors displayed if the user does not enter a value in the `name` text field. See Requiring a Value for more information on requiring input for a component.

> #### Using the outputLabel Tag

> The `outputLabel` tag is used to attach a label to a specified input field for accessibility purposes. The `bookcashier.jsp` page uses an `outputLabel` tag to render the label of a checkbox:

>     <h:selectBooleanCheckbox
>       id="fanClub"
>       rendered="false"
>       binding="#{cashier.specialOffer}" />
>     <h:outputLabel for="fanClub"
>       rendered="false"
>       binding="#{cashier.specialOfferText}"  >
>       <h:outputText id="fanClubLabel"
>         value="#{bundle.DukeFanClub}" />
>     </h:outputLabel>
>     ...

> The `for` attribute of the `outputLabel` tag maps to the `id` of the input field to which the label is attached. The `outputText` tag nested inside the `outputLabel` tag represents the actual label component. The `value` attribute on the `outputText` tag indicates the text that is displayed next to the input field.

> Instead of using an `outputText` tag for the text displayed as a label, you can simply use the `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 `outputLabel` tag to specify the text of the label.

>     <h:selectBooleanCheckbox
>       id="fanClub"
>       rendered="false"
>       binding="#{cashier.specialOffer}" />
>       <h:outputLabel for="fanClub"
>         rendered="false"
>         binding="#{cashier.specialOfferText}"
>         value="#{bundle.DukeFanClub}" />
>       </h:outputLabel>
>     ...

> #### Using the outputLink Tag

> The `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 `commandLink` tag if you always want the URL--specified by the `outputLink` tag's `value` attribute--to open and do not have to perform any processing when the user clicks on the link. The Duke's Bookstore application does not utilize this tag, but here is an example of it:

>     <h:outputLink value="javadocs">
>       <f:verbatim>Documentation for this demo</f:verbatim>
>     </h:outputLink>

> As shown in this example, the `outputLink` tag requires a nested `verbatim` tag, which identifies the text the user clicks to get to the next page.

> You can use the `verbatim` tag on its own when you want to simply output some text on the page.

> #### Using the outputFormat Tag

> The `outputFormat` tag allows a page author to display concatenated messages as a `MessageFormat` pattern, as described in the API documentation for `java.text.MessageFormat` (see `http://java.sun.com/j2se/1.4.2/docs/api/java/text/MessageFormat.html`). Here is an example of an `outputFormat` tag from the `bookshowcart.jsp` page of the Duke's Bookstore application:

>     <h:outputFormat value="#{bundle.CartItemCount}">
>       <f:param value="#{cart.numberOfItems}"/>
>     </h:outputFormat>

> The `value` attribute specifies the `MessageFormat` pattern. The `param` tag specifies the substitution parameters for the message.

> In the example `outputFormat` tag, the `value` for the parameter maps to the number of items in the shopping cart. When the message is displayed on the page, the number of items in the cart replaces the `{0}` in the message corresponding to the `CartItemCount` key in the `bundle` resource bundle:

>     Your shopping cart contains " + "{0,choice,0#no items|1#one
>     item|1< {0} items

> This message represents three possibilities:

> - Your shopping cart contains no items.
> - Your shopping cart contains one item.
> - Your shopping cart contains `{0}` items.

> The value of the parameter replaces the `{0}` from the message in the sentence in the third bullet. This is an example of a value-binding-enabled tag attribute accepting a complex JSP 2.0 EL expression.

> An `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.

> A page author can also hardcode the data to be substituted in the message by using a literal value with the `value` attribute on the `param` tag.

> #### Using the inputSecret Tag

> The `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 the user types. The Duke's Bookstore application does not include this tag, but here is an example of one:

>     <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 UIPanel Component

> The `UIPanel` component is used as a layout container for its children. When you use the renderers from the HTML render kit, `UIPanel` is rendered as an HTML table. This component differs from `UIData` in that `UIData` can dynamically add or delete rows to accommodate the underlying data source, whereas `UIPanel` must have the number of rows predetermined. Table 18-4 lists all the renderers and tags corresponding to the `UIPanel` component.

> Table 18-4 UIPanel Renderers and Tags
> Renderer | Tag | Renderer Attributes | Function
> --- | --- | --- | ---
> `Grid` | `panelGrid` | `columnClasses, columns, footerClass, headerClass, panelClass, rowClasses` | Displays a table
> `Group` | `panelGroup` |  | Groups a set of components under one parent

> The `panelGrid` tag is used to represent an entire table. The `panelGroup` tag is used to represent rows in a table. Other UI component tags are used to represent individual cells in the rows.

> The `panelGrid` tag has a set of attributes that specify CSS stylesheet classes: `columnClasses`, `footerClass`, `headerClass`, `panelClass`, and `rowClasses`. These stylesheet attributes are not required. It also has a `columns` attribute. The `columns` attribute is required if you want your table to have more than one column because the `columns` attribute tells the renderer how to group the data in the table.

> If a `headerClass` is specified, the `panelGrid` must have a header as its first child. Similarly, if a `footerClass` is specified, the `panelGrid` must have a footer as its last child.

> The Duke's Bookstore application includes three `panelGrid` tags on the `bookcashier.jsp` page. Here is a portion of one of them:

>     <h:panelGrid columns="3" headerClass="list-header"
>       rowClasses="list-row-even, list-row-odd"
>       styleClass="list-background"
>       title="#{bundle.Checkout}">
>       <f:facet name="header">
>         <h:outputText value="#{bundle.Checkout}"/>
>       </f:facet>
>       <h:outputText value="#{bundle.Name}" />
>       <h:inputText id="name" size="50"
>         value="#{cashier.name}"
>         required="true">
>         <f:valueChangeListener
>           type="listeners.NameChanged" />
>       </h:inputText>
>       <h:message styleClass="validationMessage" for="name"/>
>       <h:outputText value="#{bundle.CCNumber}"/>
>       <h:inputText id="ccno" size="19"
>         converter="CreditCardConverter" required="true">
>         <bookstore:formatValidator
>           formatPatterns="9999999999999999|
>             9999 9999 9999 9999|9999-9999-9999-9999"/>
>       </h:inputText>
>       <h:message styleClass="validationMessage"  for="ccno"/>
>       ...
>     </h:panelGrid>

> This `panelGrid` tag is rendered to a table that contains controls for the customer of the bookstore to input personal information. This `panelGrid` tag uses stylesheet classes to format the table. The CSS classes are defined in the `stylesheet.css` file in the <`INSTALL`>/j2eetutorial14`/examples/web/bookstore6/web/` directory. The `list-header` definition is

>     .list-header {
>       background-color: #ffffff;
>       color: #000000;
>       text-align: center;
>     }

> Because the `panelGrid` tag specifies a `headerClass`, the `panelGrid` must contain a header. The example `panelGrid` tag uses a `facet` tag for the header. Facets can have only one child, and so a `panelGroup` tag is needed if you want to group more than one component within a `facet`. Because the example `panelGrid` tag has only one cell of data, a `panelGroup` tag is not needed.

> A `panelGroup` tag can also be used to encapsulate a nested tree of components so that the tree of components appears as a single component to the parent component.

> The data represented by the nested component tags is grouped into rows according to the value of the columns attribute of the `panelGrid` tag. The `columns` attribute in the example is set to `"3"`, and therefore the table will have three columns. In which column each component is displayed is determined by the order that the component is listed on the page modulo 3. So if a component is the fifth one in the list of components, that component will be in the 5 modulo 3 column, or column 2.

> ### The UISelectBoolean Component

> The `UISelectBoolean` class defines components that have a `boolean` value. The `selectBooleanCheckbox` tag is the only tag that JavaServer Faces technology provides for representing `boolean` state. The Duke's Bookstore application includes a `selectBooleanCheckbox` tag on the `bookcashier.jsp` page:

>     <h:selectBooleanCheckbox
>       id="fanClub"
>       rendered="false"
>       binding="#{cashier.specialOffer}" />
>     <h:outputLabel
>       for="fanClub"
>       rendered="false"
>       binding="#{cashier.specialOfferText}">
>       <h:outputText
>         id="fanClubLabel"
>         value="#{bundle.DukeFanClub}" />
>     </h:outputLabel>

> This example tag displays a checkbox to allow users to indicate whether they want to join the Duke Fan Club. The label for the checkbox is rendered by the `outputLabel` tag. The actual text is represented by the nested `outputText` tag. Binding a Component Instance to a Bean Property discusses this example in more detail.

> ### The UISelectMany Component

> The `UISelectMany` class defines a component that allows the user to select zero or more values from a set of values. This component can be rendered as a set of checkboxes, a list box, or a menu. This section explains the `selectManyCheckbox` tag. The `selectManyListbox` tag and `selectManyMenu` tag are written in a similar way.

> A list box differs from a menu in that it displays a subset of items in a box, whereas a menu displays only one item at a time until you select the menu. The `size` attribute of the `selectManyListbox` tag determines the number of items displayed at one time. The list box includes a scrollbar for scrolling through any remaining items in the list.

> #### Using the selectManyCheckbox Tag

> The `selectManyCheckbox` tag renders a set of checkboxes, with each checkbox representing one value that can be selected. Duke's Bookstore uses a `selectManyCheckbox` tag on the `bookcashier.jsp` page to allow the user to subscribe to one or more newsletters:

>     <h:selectManyCheckbox
>       id="newsletters"
>       layout="pageDirection"
>       value="#{cashier.newsletters}">
>       <f:selectItems
>         value="#{newsletters}"/>
>     </h:selectManyCheckbox>

> The `value` attribute of the `selectManyCheckbox` tag identifies the `CashierBean` backing bean property, `newsletters`, for the current set of newsletters. This property holds the values of the currently selected items from the set of checkboxes. You are not required to provide a value for the currently selected items. If you don't provide a value, the first item in the list is selected by default.

> The `layout` attribute indicates how the set of checkboxes are arranged on the page. Because layout is set to `pageDirection`, the checkboxes are arranged vertically. The default is `lineDirection`, which aligns the checkboxes horizontally.

> The `selectManyCheckbox` tag must also contain a tag or set of tags representing the set of checkboxes. To represent a set of items, you use the `selectItems` tag. To represent each item individually, you use a `selectItem` tag for each item. The UISelectItem, UISelectItems, and UISelectItemGroup Components explains these two tags in more detail.

> ### The UIMessage and UIMessages Components

> The `UIMessage` and `UIMessages` components are used to display error messages. Here is an example `message` tag from the `guessNumber` application, discussed in Steps in the Development Process:

>     <h:inputText id="userNo" value="#{UserNumberBean.userNumber}">
>       <f:validateLongRange minimum="0" maximum="10" />
>     ...
>     <h:message
>       style="color: red;
>       font-family: 'New Century Schoolbook', serif;
>       font-style: oblique;
>       text-decoration: overline" id="errors1" for="userNo"/>

> The `for` attribute refers to the ID of the component that generated the error message. The `message` tag will display the error message wherever it appears on the page.

> The `style` attribute allows you to specify the style of the text of the message. In the example in this section, the text will be red, New Century Schoolbook, serif font family, and oblique style, and a line will appear over the text.

> If you use the `messages` tag instead of the `message` tag, all error messages will display.

> ### The UISelectOne Component

> A `UISelectOne` component allows the user to select one value from a set of values. This component can be rendered as a list box, a set of radio buttons, or a menu. This section explains the `selectOneMenu` tag. The `selectOneRadio` and `selectOneListbox` tags are written in a similar way. The `selectOneListbox` tag is similar to the `selectOneMenu` tag except that `selectOneListbox` defines a `size` attribute that determines how many of the items are displayed at once.

> #### Using the selectOneMenu Tag

> The `selectOneMenu` tag represents a component that contains a list of items, from which a user can choose one item. The menu is also commonly known as a drop-down list or a combo box. The following code snippet shows the `selectOneMenu` tag from the `bookcashier.jsp` page of the Duke's Bookstore application. This tag allows the user to select a shipping method:

>     <h:selectOneMenu   id="shippingOption"
>       required="true"
>       value="#{cashier.shippingOption}">
>       <f:selectItem
>         itemValue="2"
>         itemLabel="#{bundle.QuickShip}"/>
>       <f:selectItem
>         itemValue="5"
>         itemLabel="#{bundle.NormalShip}"/>
>       <f:selectItem
>         itemValue="7"
>         itemLabel="#{bundle.SaverShip}"/>
>     </h:selectOneMenu>

> The `value` attribute of the `selectOneMenu` tag maps to the property that holds the currently selected item's value. You are not required to provide a value for the currently selected item. If you don't provide a value, the first item in the list is selected by default.

> Like the `selectOneRadio` tag, the `selectOneMenu` tag must contain either a `selectItems` tag or a set of `selectItem` tags for representing the items in the list. The next section explains these two tags.

> ### The UISelectItem, UISelectItems, and UISelectItemGroup Components

> `UISelectItem` and`UISelectItems` represent components that can be nested inside a `UISelectOne` or a `UISelectMany` component. `UISelectItem` is associated with a `SelectItem` instance, which contains the value, label, and description of a single item in the `UISelectOne` or `UISelectMany` component.

> The `UISelectItems` instance represents either of the following:

> - A set of `SelectItem` instances, containing the values, labels, and descriptions of the entire list of items
> - A set of `SelectItemGroup` instances, each of which represents a set of `SelectItem` instances

> Figure 18-2 shows an example of a list box constructed with a `SelectItems` component representing two `SelectItemGroup` instances, each of which represents two categories of beans. Each category is an array of `SelectItem` instances.

> Figure 18-2 An Example List Box Created Using `SelectItemGroup` Instances

> The `selectItem` tag represents a `UISelectItem` component. The `selectItems` tag represents a `UISelectItems` component. You can use either a set of `selectItem` tags or a single `selectItems` tag within your `selectOne` or `selectMany` tag.

> The advantages of using the `selectItems` tag are as follows:

> - You can represent the items using different data structures, including `Array`, `Map` and `Collection`. The data structure is composed of `SelectItem` instances or `SelectItemGroup` instances.
> - You can concatenate different lists together into a single `UISelectMany` or `UISelectOne` component and group the lists within the component, as shown in Figure 18-2.
> - You can dynamically generate values at runtime.

> The advantages of using `selectItem` are as follows:

> - The page author can define the items in the list from the page.
> - You have less code to write in the bean for the `selectItem` properties.

> For more information on writing component properties for the `UISelectItems` components, see Writing Component Properties. The rest of this section shows you how to use the `selectItems` and `selectItem` tags.

> #### Using the selectItems Tag

> Here is the `selectManyCheckbox` tag from the section The UISelectMany Component:

>     <h:selectManyCheckbox
>       id="newsletters"
>       layout="pageDirection"
>       value="#{cashier.newsletters}">
>       <f:selectItems
>         value="#{newsletters}"/>
>     </h:selectManyCheckbox>

> The `value` attribute of the `selectItems` tag is bound to the `newsletters` managed bean, which is configured in the application configuration resource file. The `newsletters` managed bean is configured as a list:

>     <managed-bean>
>       <managed-bean-name>newsletters</managed-bean-name>
>       <managed-bean-class>
>         java.util.ArrayList</managed-bean-class>
>       <managed-bean-scope>application</managed-bean-scope>
>       <list-entries>
>         <value-class>javax.faces.model.SelectItem</value-class>
>         <value>#{newsletter0}</value>
>         <value>#{newsletter1}</value>
>         <value>#{newsletter2}</value>
>         <value>#{newsletter3}</value>
>       </list-entries>
>     </managed-bean>
>     <managed-bean>
>     <managed-bean-name>newsletter0</managed-bean-name>
>     <managed-bean-class>
>       javax.faces.model.SelectItem</managed-bean-class>
>     <managed-bean-scope>none</managed-bean-scope>
>     <managed-property>
>       <property-name>label</property-name>
>       <value>Duke's Quarterly</value>
>     </managed-property>
>     <managed-property>
>       <property-name>value</property-name>
>       <value>200</value>
>     </managed-property>
>     </managed-bean>
>     ...

> As shown in the `managed-bean` element, the `UISelectItems` component is a collection of `SelectItem` instances. See Initializing Array and List Properties for more information on configuring collections as beans.

> You can also create the list corresponding to a `UISelectMany` or `UISelectOne` component programmatically in the backing bean. See Writing Component Properties for information on how to write a backing bean property corresponding to a `UISelectMany` or `UISelectOne` component.

> The arguments to the `SelectItem` constructor are:

> - An `Object` representing the value of the item
> - A `String` representing the label that displays in the `UISelectMany` component on the page
> - A `String` representing the description of the item

> UISelectItems Properties describes in more detail how to write a backing bean property for a `UISelectItems` component.

> #### Using the selectItem Tag

> The `selectItem` tag represents a single item in a list of items. Here is the example from Using the selectOneMenu Tag:

>     <h:selectOneMenu
>       id="shippingOption" required="true"
>       value="#{cashier.shippingOption}">
>       <f:selectItem
>         itemValue="2"
>         itemLabel="#{bundle.QuickShip}"/>
>       <f:selectItem
>         itemValue="5"
>         itemLabel="#{bundle.NormalShip}"/>
>       <f:selectItem
>         itemValue="7"
>         itemLabel="#{bundle.SaverShip}"/>
>     </h:selectOneMenu>

> The `itemValue` attribute represents the default value of the `SelectItem` instance. The `itemLabel` attribute represents the `String` that appears in the drop-down menu component on the page.

> The `itemValue` and `itemLabel` attributes are value-binding-enabled, meaning that they can use value-binding expressions to refer to values in external objects. They can also define literal values, as shown in the example `selectOneMenu` tag.

Download PDF Home History |  | API Search Feedback FAQ

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.