Download FAQ History |  | API Search Feedback

> ## Using the JavaServer Faces Tag Libraries

> JavaServer Faces technology provides two tag libraries: the `html_basic` tag library and the `jsf-core` tag library. The `html_basic` tag library defines tags for representing common HTML user interface components. The `jsf-core` tag library defines all of the other tags, including tags for registering listeners and validators on components. The tags in `jsf-core` are independent of any rendering technology and can therefore be used with any render kit. Using these tag libraries is similar to using any other custom tag library. This section assumes that you are familiar with the basics of Custom Tags in JSP Pages.

> ### Declaring the JavaServer Faces Tag Libraries

> To use the JavaServer Faces tag libraries, you need to include these taglib directives at the top of each page containing the tags defined by these tag libraries:

>     <%@ taglib uri="http://java.sun.com/jsf/html/" prefix="h" %>
>     <%@ taglib uri="http://java.sun.com/jsf/core/" prefix="f" %>

> The `uri` attribute value uniquely identifies the tag library. The `prefix` attribute value is used to distinguish tags belonging to the tag library. For example, the `form` tag must be referenced in the page with the `h` prefix, like this:

>     <h:form ...>

> When you reference any of the JavaServer Faces tags from within a JSP page, you must enclose them in the `use_faces` tag, which is defined in the `jsf_core` library:

>     <f:use_faces>
>       ... other faces tags, possibly mixed with other content ...
>     </f:use_faces>

> You can enclose other content within the `use_faces` tag, including HTML and other JSP tags, but all JavaServer Faces tags must be enclosed within the `use_faces` tag.

> ### Using the Core Tags

> The tags defined by the `jsf-core` TLD represent a set of tags for performing core actions that are independent of a particular render kit. The jsf-core tags are listed in Table 21-8.

> Table 21-8 The jsf-core Tags
> | Tags | Functions
> --- | --- | ---
> Event Handling Tags | `action_listener` | Registers an action listener on a parent component
> `valuechanged_listener` | Registers a value-changed listener on a parent component
> Attribute Configuration Tag | `attribute` | Adds configurable attributes to a parent components
> Facet Tag | `facet` | Signifies a nested component that has a special relationship to its enclosing tag
> Parameter Substitution Tag | `parameter` | Substitutes parameters into a `MessageFormat` instance and to add query string name/value pairs to a URL.
> Container For Form Tags | `use_faces` | Encloses all JavaServer Faces tags on this page.
> Validator Tags | `validate_doublerange` | Registers a `DoubleRangeValidator` on a component
> `validate_length` | Registers a `LengthValidator` on a component
> `validate_longrange` | Registers a `LongRangeValidator` on a component
> `validate_required` | Registers a `RequiredValidator` on a component
> `validate_stringrange` | Registers a `StringRangeValidator` on a component
> `validator` | Registers a custom `Validator` on a component

> These tags are used in conjunction with component tags and are therefore explained in other sections of this tutorial. Table 21-9 lists which sections explain how to use which `jsf-core` tags.

> Table 21-9 Where the jsf-core Tags are Explained
> Tags | Where Explained
> --- | ---
> Event-Handling Tags | Handling Events
> `attribute` Tag | Using the Standard Converters
> `facet` Tag | Using the panel_grid Tag
> `parameter` Tag | Submitting ActionEvents, Linking to a URL, and Using the output_message Tag
> `use_faces` Tag | Declaring the JavaServer Faces Tag Libraries
> Validator Tags | Performing Validation

> ### Using the HTML Tags

> The tags defined by `html_basic` 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 20-2, and is organized according to the `UIComponent` classes from which the tags are derived.

> This section does not explain every tag attribute, only the most commonly-used ones. Please refer to `html_basic.tld` file in the `lib` directory of your download for a complete list of tags and their attributes.

> In general, most of the component tags have these attributes in common:

> - `id`: uniquely identifies the component
> - `valueRef`: identifies the data source mapped to the component
> - `key`: identifies a key in a resource bundle.
> - `bundle`: identifies a resource bundle

> In this release, 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.

> `UIOutput` and subclasses of `UIOutput` have a `valueRef` attribute, which is always optional, except in the case of `SelectItems`. Using the `value-ref` attribute to bind to a data source is explained more in section Using the Core Tags.

> #### The UIForm Component

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

>     <h:form formName="imageMapForm"
>     ... other faces tags and other content...
>     </h:form>

> The `formName` attribute is passed to the application, where it is used to select the appropriate business logic.

> The `form` tag can also include HTML markup to layout 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.

> #### 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 `Hyperlink` as `UICommand` component renderers.

> ##### Using the command_button Tag

> Most pages in the `cardemo` example use the `command_button` tag. When the button is clicked, the data from the current page is processed, and the next page is opened. Here is the `buyButton` `command_button` tag from `buy.jsp`:

>     <h:command_button key="buy" bundle="carDemoBundle"
>               commandName="customer" action="success" />

> Clicking the button will cause `Customer.jsp` to open. This page allows you to fill in your name and shipping information.

> The `key` attribute references the localized message for the button's label. The `bundle` attribute references the `ResourceBundle` that contains a set of localized messages. For more information on localizing JavaServer Faces applications, see Performing Localization.

> The `commandName` attribute refers to the name of the command generated by the event of clicking the button. The `commandName` is used by the `ActionEventListener` to determine how to process the command. See Handling Events for more information on how to implement event listeners to process the event generated by button components.

> The `action` attribute represents a literal outcome value returned when the button is clicked. The outcome is passed to the default `NavigationHandler`, which matches the outcome against a set of navigation rules defined in the application configuration file.

> A `command_button` tag can have an `actionRef` attribute as an alternative to the `action` attribute. The `actionRef` attribute is a value reference expression that points to an `Action`, whose invoke method performs some processing and returns the logical outcome.

> See section Navigating Between Pages for information on how to use the `action` and `actionRef` attributes.

> The `cardemo` application uses the `commandName` and the `action` attributes together. This is because it uses the outcome from the `action` attribute to navigate between pages, but it also uses the `commandName` attribute to point to a listener that performs some other processing. In practice, this extra processing should be performed by the `Action` object, and the `actionRef` attribute should be used to point to the `Action` object. The `commandName` attribute and its associated listener should only be used to process UI changes that don't result in a page being loaded.

> ##### Using the command_hyperlink Tag

> The `command_hyperlink` tag represents an HTML hyperlink and is rendered as an HTML `<a>` element. The `command_hyperlink` tag can be used for two purposes:

> - To submit `ActionEvents` to the application. See Handling Events and Navigating Between Pages for more information.
> - To link to a particular URL
> Submitting ActionEvents

> Like the `command_button` tag, the `command_hyperlink` tag can be used to submit `ActionEvents`. To submit an `ActionEvent` for the purpose of navigating between pages, the tag needs one of these attributes:

> - `action`, which indicates a logical outcome for determining the next page to be accessed
> - `actionRef`, which refers to the bean property that returns an Action in response to the event of clicking the hyperlink

> The `action` attribute represents a literal outcome value returned when the hyperlink is clicked. The outcome is passed to the default `NavigationHandler`, which matches the outcome against a set of navigation rules defined in the application configuration file.

> The `actionRef` attribute is a value reference expression that points to an `Action`, whose `invoke` method performs some processing and returns the logical outcome.

> See section Navigating Between Pages for information on how to use the `action` and `actionRef` attributes.

> To submit an `ActionEvent` for the purpose of making UI changes, the tag needs both of these attributes:

> - `commandName`: the logical name of the command
> - `commandClass`: the name of the listener that handles the event

> The `commandName` attribute refers to the name of the command generated by the event of clicking the hyperlink. The `commandName` is used by the `ActionEventListener` to determine how to process the command. See Handling Events for more information on how to implement event listeners to process the event generated by button components.

> The `commandName` attribute and its associated listener should only be used to process UI changes that don't result in a page being loaded. See Registering Listeners on Components for more information on using the `commandName` attribute.

> In addition to these attributes, the tag also needs a `label` attribute, which is the text that the user clicks to generate the event.

> A `command_hyperlink` tag can contain `parameter` tags that will cause an HTML `<input type=hidden>` element to be rendered. This `input` tag represents a hidden control that stores the name and value specified in the `parameter` tags between client/server exchanges so that the server-side classes can retrieve the value. The following two tags show `command_hyperlink` tags that submit `ActionEvents`. The first tag does not use parameters; the second tag does use parameters.

>     <h:command_hyperlink id="commandParamLink" commandName="login"
>       commandClass="LoginListener" label="link text"/>
>     <h:command_hyperlink id="commandParamLink" commandName="login"
>       commandClass="LoginListener" label="Login">
>       <f:parameter id="Param1" name="name"
>         valueRef="LoginBean.name"/>
>       <f:parameter id="Param2" name="value"
>         valueRef="LoginBean.password"/>
>     </h:command_hyperlink>

> The first tag renders this HTML:

>     <a href="#"
>     onmousedown="document.forms[0].commandParamLink.value='login';
>     document.forms[0].submit()" class="hyperlinkClass">
>       link text</a>
>       <input type="hidden" name="commandParamLink"/>

> The second tag renders this HTML, assuming that `LoginBean.name` is `duke` and `LoginBean.password` is `redNose`:

>     <a href="#"
>     onmousedown="document.forms[0].commandParamLink.value='login';
>     document.forms[0].submit()" class="hyperlinkClass">
>       link text</a>
>       <input type="hidden" name="commandParamLink"/>
>       <input type="hidden" name="name" value="duke"/>
>       <input type="hidden" name="value" value="redNose"/>

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

> Linking to a URL

> To use `command_hyperlink` to link to a URL, your `command_hyperlink` tag must specify the `href` attribute, indicating the page to which to link.

> A `command_hyperlink` that links to a URL can also contain `parameter` tags. The `parameter` tags for this kind of `command_hyperlink` tag allow the page author to add query strings to the URL. The following two tags show `command_hyperlink` tags that link to a URL. The first tag does not use parameters; the second tag does use parameters.

>     <h:command_hyperlink id="hrefLink" href="welcome.html"
>       image="duke.gif"/>
>     <h:command_hyperlink id="hrefParamLink" href="welcome.html"
>       image="duke.gif">
>       <f:parameter id="Param1" name="name"
>         valueRef="LoginBean.name"/>
>       <f:parameter id="Param2" name="value"
>         valueRef="LoginBean.password"/>
>     </h:command_hyperlink>

> The first tag renders this HTML:

>     <a href="hello.html"><img src="duke.gif"></a>

> The second tag renders the following HTML, assuming that `LoginBean.name` is duke and `LoginBean.password` is redNose:

>     <a href="hello.html?name=duke&value=redNose">
>       <img src="duke.gif"></a>

> #### The UIGraphic Component

> The `UIGraphic` component displays an image. The `cardemo` application has many examples of `graphic_image` tags. Here is the `graphic_image` tag used with the image map on `ImageMap.jsp`:

>     <h:graphic_image id="mapImage" url="/world.jpg"
>       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 with the `currentValue` method or indirectly from a model object. 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 `usemap` attribute refers to the image map defined by the custom `UIMap` component on the same page. See Creating Custom UI Components for more information on the image map.

> #### The UIInput and UIOutput Components

> The `UIInput` component displays a value to a 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.

> Both `UIInput` and `UIOutput` components can be rendered in several different ways. Since the components have some common functionality, they share many of the same renderers.

> Table 21-10 lists the common renderers of `UIInput` and `UIOutput`. Recall from The Component Rendering Model that the tags are composed of the component and the renderer. For example, the `input_text` tag refers to a `UIInput` component that is rendered with the `Text` Renderer.

> Table 21-10 UIInput and UIOutput Renderers
> Renderer | Tag | Function
> --- | --- | ---
> Date | `input_date` | Accepts a `java.util.Date` formatted with a `java.text.Date` instance
> `output_date` | Displays a `java.util.Date` formatted with a `java.text.Date` instance
> DateTime | `input_datetime` | Accepts a `java.util.Date` formatted with a `java.text.DateTime` instance
> `output_datetime` | Displays a `java.util.Date` formatted with a `java.text.DateTime` instance
> Number | `input_number` | Accepts a numeric data type (`java.lang.Number` or primitive), formatted with a `java.text.NumberFormat`
> `output_number` | Accepts a numeric data type (`java.lang.Number` or primitive), formatted with a `java.text.NumberFormat`
> Text | `input_text` | Accepts a text string of one line.
> `output_text` | Displays a text string of one line.
> Time | `input_time` | Accepts a `java.util.Date`, formatted with a `java.text.DateFormat` time instance
> `output_time` | Displays a `java.util.Date`, formatted with a `java.text.DateFormat` time instance

> In addition to the renderers listed in Table 21-10, `UIInput` and `UIOutput` each support other renderers that the other component does not support. These are listed in Table 21-11.

> Table 21-11 Additional UIInput and UIOutput Renderers
> Component | Renderer | Tag | Function
> --- | --- | --- | ---
> `UIInput` | `Hidden` | `input_hidden` | Allows a page author to include a hidden variable in a page
> `Secret` | `input_secret` | Accepts one line of text with no spaces and displays it as a set of asterisks as it is typed
> `TextArea` | `input_textarea` | Accepts multiple lines of text
> `UIOutput` | `Errors` | `output_errors` | Displays error messages for an entire page or error messages associated with a specified client identifier
> `Label` | `output_label` | Displays a nested component as a label for a specified input field
> `Message` | `output_message` | Displays a localized message

> All of the tags listed in Table 21-10--except for the `input_text` and `output_text` tags--display or accept data of a particular format specified in the `java.text` or `java.util` packages. You can also apply the `Date`, `DateTime`, `Number`, and `Time` renderers associated with these tags to convert data associated with the `input_text`, `output_text`, `input_hidden`, and `input_secret` tags. See Performing Data Conversions for more information on using these renderers as converters.

> The rest of this section explains how to use selected tags listed in the two tables above. These tags are: `input_datetime`, `output_datetime`, `output_label`, `output_message`, `input_secret`, `output_text`, and `input_text`.

> The `output_errors` tag is explained in Performing Validation. The tags associated with the `Date`, `Number`, and `Time` renderers are defined in a similar way to those tags associated with the `DateTime` renderer. The `input_hidden` and `input_textarea` tags are similar to the `input_text` tag. Refer to the `html_basic` TLD in your download to see what attributes are supported for these extra tags.

> ##### Using the input_datetime and output_datetime Tags

> The `DateTime` renderer can render both `UIInput` and `UIOutput` components. The `input_datetime` tag displays and accepts data in a `java.text.SimpleDateFormat`. The `output_datetime` tag displays data in a `java.text.SimpleDateFormat`. This section shows you how to use the `output_datetime` tag. The `input_datetime` tag is written in a similar way.

> The `output_datetime` and `input_datetime` tags have the following attributes and values for formatting data:

> - `dateStyle`: `short(default), medium, long, full`
> - `timeStyle`: `short(default), medium, long, full`
> - `timezone`: `short(default), long`
> - `formatPattern`: a String specifying the format of the data

> See `java.text.SimpleDateFormat` and `java.util.TimeZone` for information on specifying the style of `dateStyle`, `timeStyle`, and `timezone`. You can use the first three attributes in the same tag simultaneously or separately. Or, you can simply use `formatPattern` to specify a `String` pattern to format the data. The following tag is an example of using the `formatPattern` attribute:

>     <h:output_datetime
>       formatPattern="EEEEEEEE, MMM d, yyyy hh:mm:ss a z"
>       valueRef="LoginBean.date"/>

> One example of a date and time that this tag can display is:

>     Saturday, Feb 22, 2003 18:10:15 pm PDT

> You can also display the same date and time with this tag:

>     <h: output_datetime dateStyle="full" timeStyle="long"
>       valueRef="LoginBean.date" />

> The application developer is responsible for ensuring that the `LoginBean.date` property is the proper type to handle these formats.

> The tags corresponding to the `Date`, `Number`, and `Time` renderers are written in a similar way. See the `html_basic` TLD in the `lib` directory of your installation to look up the attributes supported by the tags corresponding to these renderers.

> ##### Using the output_text and input_text Tags

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

> The following attributes, supported by both `output_text` and `input_text`, are likely to be the most commonly used:

> - `id`: Identifies the component associated with this tag
> - `valueRef`: Identifies the model object property bound to the component
> - `converter`: Identifies one of the renderers that will be used to convert the component's local data to the model object property data specified in the `valueRef` attribute. See Performing Data Conversions for more information on how to use this attribute.
> - `value`: Allows the page author to specify the local value of the component.

> The `output_text` tag also supports the `key` and `bundle` attributes, which are used to fetch the localized version of the component's local value. See Performing Localization for more information on how to use these attributes.

> Here is an example of an `input_text` tag from the `Customer.jsp` page:

>     <h:input_text valueRef="CustomerBean.firstName" />

> The `valueRef` value refers to the `firstName` property on the `CustomerBean` model object. After the user submits the form, the value of the `firstName` property in `CustomerBean` will be set to the text entered in the field corresponding to this tag.

> ##### Using the output_label Tag

> The `output_label` tag is used to attach a label to a specified input field for accessibility purposes. Here is an example of an `output_label` tag:

>     <h:output_label for="firstName">
>       <h:output_text id="firstNameLabel" value="First Name"/>
>     </h:output_label>
>     ...
>     <h:input_text id="firstName" />

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

> ##### Using the output_message Tag

> The `output_message` tag allows a page author to display concatenated messages as a `MessageFormat` pattern. Here is an example of an `output_message` tag:

>     <h:output_message
>       value="Goodbye, {0}. Thanks for ordering your {1} " >
>       <f:parameter id="param1" valueRef="LoginBean.name"/>
>       <f:parameter id="param2" valueRef="OrderBean.item" />
>     </h:output_message>

> The `value` attribute specifies the `MessageFormat` pattern. The `parameter` tags specify the substitution parameters for the message. The `valueRef` for `param1` maps to the user's name in the `LoginBean`. This value replaces `{0}` in the message. The `valueRef` for `param2` maps to the item the user ordered in the `OrderBean`. This value replaces `{1}` in the message. Make sure you put the `parameter` tags in the proper order so that the data is inserted in the correct place in the message.

> Instead of using `valueRef`, a page author can hardcode the data to be substituted in the message by using the `value` attribute on the `parameter` tag.

> ##### Using the input_secret Tag

> The `input_secret` tag renders an `<input type="password">` HTML tag. When the user types a string in this field, a row of asterisks is displayed instead of the string the user types. Here is an example of an `input_secret` tag:

>     <h:input_secret redisplay="false"
>       valueRef="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

> A `UIPanel` component is used as a layout container for its children. When using the renderers from the HTML render kit, a `UIPanel` is rendered as an HTML table. Table 21-12 lists all of the renderers and tags corresponding to the `UIPanel` component.

> Table 21-12 UIPanel Renderers and Tags
> Renderer | Tag | Renderer Attributes | Function
> --- | --- | --- | ---
> `Data` | `panel_data` | `var` | Iterates over a collection of data, rendered as a set of rows
> `Grid` | `panel_grid` | `columnClasses, columns, footerClass, headerClass, panelClass, rowClasses` | Displays a table
> `Group` | `panel_group` |  | Groups a set of components under one parent
> `List` | `panel_list` | `columnClasses, footerClass, headerClass, panelClass, rowClasses` | Displays a table of data that comes from a `Collection`, `array`, `Iterator`, or `Map`

> The `panel_grid` and `panel_list` tags are used to represent entire tables. The `panel_data` tags and `panel_group` tags are used to represent rows in the tables. To represent individual cells in the rows, the `output_text` tag is usually used, but any output component tag can be used to represent a cell.

> A `panel_data` tag can only be used in a `panel_list`. A `panel_group` can be used in both `panel_grid` tags and `panel_list` tags. The next two sections show you how to create tables with `panel_grid` and `panel_list`, and how to use the `panel_data` and `panel_group` tags to generate rows for the tables.

> ##### Using the panel_grid Tag

> The `panel_grid` tag has a set of attributes that specify CSS stylesheet classes: the `columnClasses`, `footerClass`, `headerClass`, `panelClass`, and `rowClasses`. These stylesheet attributes are not required.

> The `panel_grid` tag 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 `panel_grid` must have a header as its first child. Similarly, if a `footerClass` is specified, the `panel_grid` must have a footer as its last child.

> The `cardemo` application includes one `panel_grid` tag on the `buy.jsp` page:

>     <h:panel_grid id="choicesPanel" columns="2"
>       footerClass="subtitle" headerClass="subtitlebig"
>       panelClass="medium"
>       columnClasses="subtitle,medium">
>       <f:facet name="header">
>         <h:panel_group>
>           <h:output_text  key="buyTitle" bundle="carDemoBundle"/>
>         </h:panel_group>
>       </f:facet>
>       <h:output_text key="Engine" bundle="carDemoBundle" />
>       <h:output_text
>         valueRef=
>           "CurrentOptionServer.currentEngineOption"/>
>       ...
>       <h:output_text  key="gpsLabel" bundle="carDemoBundle"  />
>       <h:output_text  valueRef="CurrentOptionServer.gps" />
>       <f:facet name="footer">
>         <h:panel_group>
>           <h:output_text  key="yourPriceLabel"
>             bundle="carDemoBundle"  />
>           <h:output_text
>             valueRef="CurrentOptionServer.packagePrice" />
>         </h:panel_group>
>       </f:facet>
>     </h:panel_grid>

> This `panel_grid` is rendered to a table that lists all of the options that the user chose on the previous page, `more.jsp`. This `panel_grid` uses stylesheet classes to format the table. The CSS classes are defined in the `stylesheet.css` file in the <`JWSDP_HOME`>`/jsf/samples/cardemo/web` directory of your installation. The `subtitlebig` definition is:

>     .subtitlebig {
>       font-family: Arial, Helvetica, sans-serif;
>       font-size: 14px;
>       color: #93B629;
>       padding-top: 10;
>       padding-bottom: 10;
>     }

> Since the `panel_grid` tag specifies a `headerClass` and a `footerClass`, the `panel_grid` must contain a header and footer. Usually, a `facet` tag is used to represent headers and footers. This is because header and footer data is usually static.

> A facet is used to represent a component that is independent of the parent-child relationship of the page's component tree. Since header and footer data is static, the elements representing headers and footers should not be updated like the rest of the components in the tree.

> This `panel_grid` uses a `facet` tag for both the headers and footers. Facets can only have one child, and so a `panel_group` tag is needed to group more than one element within a `facet`. In the case of the `header` facet, a `panel_group` tag is not really needed. This tag could be written like this:

>     <f:facet name="header">
>       <h:output_text key="buyTitle" bundle="carDemoBundle"/>
>     </f:facet>

> The `panel_group` tag is needed within the `footer` facet tag because the footer requires two cells of data, represented by the two `output_text` tags within the `panel_group` tag:

>     <f:facet name="footer">
>       <h:panel_group>
>         <h:output_text  key="yourPriceLabel"
>           bundle="carDemoBundle"  />
>         <h:output_text
>           valueRef="CurrentOptionServer.packagePrice" />
>       </h:panel_group>
>     </f:facet>

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

> In between the `header` and `footer` facet tags, are the `output_text` tags, each of which represents a cell of data in the table:

>     <h:output_text key="Engine" bundle="carDemoBundle" />
>     <h:output_text
>       valueRef=
>         "CurrentOptionServer.currentEngineOption"/>
>     ...
>     <h:output_text  key="gpsLabel" bundle="carDemoBundle"  />
>     <h:output_text  valueRef="CurrentOptionServer.gps" />

> Again, the data represented by the `output_text` tags is grouped into rows according to the value of the columns attribute of the `output_text` tag. The `columns` attribute in the example is set to "2". So from the list of `output_text` tags representing the table data, the data from the odd `output_text` tags is rendered in the first column and the data from the even `output_text` tags is rendered in the second column.

> ##### Using the panel_list Tag

> The `panel_list` tag has the same set of stylesheet attributes as `panel_grid`, but it does not have a `columns` attribute. The number of columns in the table equals the number of `output_text` (or other component tag) elements within the `panel_data` tag, which is nested inside the `panel_list` tag. The `panel_data` tag iterates over a `Collection`, `array`, `Iterator`, or `Map` of model objects. Each `output_text` tag nested in a `panel_data` tag maps to a particular property of each of the model objects in the list. Here is an example of a `panel_list` tag:

>     <h:panel_list id="Accounts" >
>       <f:facet name="header">
>         <h:panel_group>
>           <h:output_text id="acctHead" value="Account Id"/>
>           <h:output_text id="nameHead" value="Customer Name"/>
>           <h:output_text id="symbolHead" value="Symbol"/>
>           <h:output_text id="tlSlsHead" value="Total Sales"/>
>         </h:panel_group>
>       </f:facet>
>       <h:panel_data id="tblData" var="customer"
>         valueRef="CustomerListBean">
>         <h:output_text id="acctId"
>           valueRef="customer.acctId"/>
>         <h:output_text id="name" valueRef="customer.name"/>
>         <h:output_text id="symbol"
>           valueRef="customer.symbol"/>
>         <h:output_text id="tlSls"
>           valueRef="customer.totalSales"/>
>       </h:panel_data>
>     </h:panel_list>

> This example uses a `facet` tag, and a set of `output_text` tags nested inside a `panel_group` tag to represent a header row. See the previous section for a description of using facets and `panel_group` tags.

> The component represented by the `panel_data` tag maps to a bean that is a `Collection`, `array`, `Iterator`, or `Map` of beans. The `valueRef` attribute refers to this bean, called `CustomerListBean`. The `var` attribute refers to the current bean in the `CustomerListBean` list. In this example, the current bean in the list is called `customer`. Each component represented by an output_text tag maps to a property on the `customer` bean.

> The `panel_data` tag's purpose is to iterate over the model objects and allow the `output_text` tags to render the data from each bean in the list. Each iteration over the list of beans will produce one row of data.

> One example table that can be produced by this `panel_list` tag is:

> Table 21-13 Example Accounts Table
> Account Id | Customer Name | Symbol | Total Sales
> --- | --- | --- | ---
> 123456 | Sun Microsystems, Inc. | SUNW | 2345.60
> 789101 | ABC Company | ABC | 458.21

> #### The UISelectBoolean Component

> The `UISelectBoolean` class defines components that have a `boolean` value. The `selectboolean_checkbox` tag is the only tag that JavaServer Faces technology provides for representing boolean state. The `more.jsp` page has a set of `selectboolean_checkbox` tags. Here is the one representing the cruisecontrol component:

>     <h:selectboolean_checkbox id="cruisecontrol"
>       title="Cruise Control"
>       valueRef="CurrentOptionServer.cruiseControlSelected" >
>       <f:valuechanged_listener
>         type="cardemo.PackageValueChanged"/>
>     </h:selectboolean_checkbox>

> The `id` attribute value refers to the component object. The `label` attribute value is what is displayed next to the checkbox. The `valueRef` attribute refers to the model object property associated with the component. The property that a `selectboolean_checkbox` tag maps to should be of type `boolean`, since a checkbox represents a boolean value.

> #### The UISelectMany Component

> The `UISelectMany` class defines components that allow the user to select zero or more values from a set of values. This component can be rendered as a checkboxlist, a listbox, or a menu. This section explains the `selectmany_checkboxlist` and `selectmany_menu` tags. The `selectmany_listbox` tag is similar to the `selectmany_menu` tag, except `selectmany_listbox` does not have a size attribute since a listbox displays all items at once.

> ##### Using the selectmany_checkboxlist Tag

> The `selectmany_checkboxlist` tag renders a set of checkboxes with each checkbox representing one value that can be selected. The cardemo does not have an example of a `selectmany_checkboxlist` tag, but this tag can be used to render the checkboxes on the `more.jsp` page:

>     <h:selectmany_checkboxlist
>       valueRef="CurrentOptionServer.currentOptions">
>       <h:selectitem itemLabel="Sunroof"
>         valueRef="CurrentOptionServer.sunRoofSelected">
>       <f:valuechanged_listener
>         type="cardemo.PackageValueChanged" />
>       </h:selectitem>
>       <h:selectitem itemLabel="Cruise Control"
>         valueRef=
>           "CurrentOptionServer.cruiseControlSelected" >
>       <f:valuechanged_listener
>         type="cardemo.PackageValueChanged" />
>       </h:selectitem>
>     </h:selectmany_checkboxlist>

> The `valueRef` attribute identifies the model object property, `currentOptions`, for the current set of options. This property holds the values of the currently selected items from the set of checkboxes.

> The `selectmany_checkboxlist` 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, use a `selectitem` tag for each item. The UISelectItem and UISelectItems Classes section explains these two tags in more detail.

> ##### Using the selectmany_menu Tag

> The `selectmany_menu` tag represents a component that contains a list of items, from which a user can choose one or more items. The menu is also commonly known as a drop-down list or a combo box. The tag representing the entire list is the `selectmany_menu` tag. Here is an example of a `selectmany_menu` tag:

>     <h:selectmany_menu  id="fruitOptions"
>       valueRef="FruitOptionBean.chosenFruits">
>       <h:selectitems
>         valueRef="FruitOptionBean.allFruits"/>
>     </h:selectmany_menu>

> The attributes of the `selectmany_menu` tag are the same as those of the `selectmany_checkboxlist` tag. Again, the `valueRef` of the `selectmany_menu` tag maps to the property that holds the currently selected items' values. A `selectmany_menu` tag can also have a size attribute, whose value specifies how many items will display at one time in the menu. When the size attribute is set, the menu will render with a scrollbar for scrolling through the displayed items.

> Like the `selectmany_checkboxlist` tag, the `selectmany_menu` tag must contain either a `selectitems` tag or a set of `selectitem` tags for representing the items in the list. The `valueRef` attribute of the `selectitems` tag in the example maps to the property that holds all of the items in the menu. The UISelectItem and UISelectItems Classes explains these two tags.

> #### The UISelectOne Component

> The `UISelectOne` class defines components that allow the user to select one value from a set of values. This component can be rendered as a listbox, a radio button, or a menu. The `cardemo` example uses the `selectone_radio` and `selectone_menu` tags. The `selectone_listbox` tag is similar to the `selectone_menu` tag, except `selectone_listbox` does not have a `size` attribute since a listbox displays all items at once. This section explains how to use the `selectone_radio` and `selectone_menu` tags.

> ##### Using the selectone_radio Tag

> The `selectone_radio` tag renders a set of radio buttons, one for each value that can be selected. Here is a `selectone_radio` tag from `more.jsp` that allows you to select a brake option:

>     <h:selectone_radio  id="currentBrake"
>       valueRef="CurrentOptionServer.currentBrakeOption">
>       <f:valuechanged_listener
>         type="cardemo.PackageValueChanged"/>
>       <h:selectitems
>         valueRef="CurrentOptionServer.brakeOption"/>
>     </h:selectone_radio>

> The `id` attribute of the `selectone_radio` tag uniquely identifies the radio group. The id is only required if another component, model object, or listener must refer to this component; otherwise, the JavaServer Faces implementation will generate a component id for you.

> The `valueRef` attribute identifies the model object property for `brakeOption`, which is `currentBrakeOption`. This property holds the value of the currently selected item from the set of radio buttons. The `currentBrakeOption` property can be any of the types supported by JavaServer Faces technology.

> The `selectone_radio` tag must also contain a tag or set of tags representing the list of items contained in the radio group. To represent a set of tags, you use the `selectitems` tag. To represent each item individually, use a `selectitem` tag for each item. The UISelectItem and UISelectItems Classes explains these two tags in more detail.

> ##### Using the selectone_menu Tag

> The `selectone_menu` 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 tag representing the entire list is the `selectone_menu` tag. Here is the `selectone_menu` tag from the `more.jsp` page:

>     <h:selectone_menu  id="currentEngine"
>       valueRef="CurrentOptionServer.currentEngineOption">
>       <f:valuechanged_listener
>         type="cardemo.PackageValueChanged" />
>       <h:selectitems
>         valueRef="CurrentOptionServer.engineOption"/>
>     </h:selectone_menu>

> The attributes of the `selectone_menu` tag are the same as those of the `selectone_radio` tag. Again, the `valueRef` of the `selectone_menu` tag maps to the property that holds the currently selected item's value. A `selectone_menu` tag can also have a `size` attribute, whose value specifies how many items will display at one time in the menu. When the `size` attribute is set, the menu will render with a scrollbar for scrolling through the displayed items.

> Like the `selectone_radio` tag, the `selectone_menu` tag must contain either a `selectitems` tag or a set of `selectitem` tags for representing the items in the list. The UISelectItem and UISelectItems Classes section explains these two tags.

> #### The UISelectItem and UISelectItems Classes

> The `UISelectItem` and the `UISelectItems` classes represent components that can be nested inside a `UISelectOne` or a `UISelectMany` component. The `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` class represents a set of `SelectItem` instances, containing the values, labels, and descriptions of the entire list of items.

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

> The advantages of using `selectitems` are

> - You can represent the items using different data structures, including `Array`, `Map`, `List`, and `Collection`. The data structure is composed of `SelectItem` instances.
> - You can dynamically generate a list of values at runtime.

> The advantages of using `selectitem` are:

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

> For more information on writing model object properties for the UI`SelectItems` components, see Writing Model Object Properties. The rest of this section shows you how to use the `selectitems` and `selectitem` tags.

> ##### The selectitems Tag

> Here is the `selectone_menu` tag from the section The UISelectOne Component:

>     <h:selectone_menu  id="currentEngine"
>       valueRef="CurrentOptionServer.currentEngineOption">
>       <f:valuechanged_listener
>         type="cardemo.PackageValueChanged" />
>       <h:selectitems
>         valueRef="CurrentOptionServer.engineOption"/>
>     </h:selectone_menu>

> The `id` attribute of the `selectitems` tag refers to the `UISelectItems` component object.

> The `valueRef` attribute binds the `selectitems` tag to the `engineOption` property of `CurrentOptionServer`.

> In the `CurrentOptionServer`, the `engineOption` property has a type of `ArrayList`:

>     engineOption = new ArrayList(engines.length);

> `UISelectItems` is a collection of `SelectItem` instances. You can see this by noting how the `engineOption` `ArrayList` is populated:

>     for (i = 0; i < engines.length; i++) {
>       engineOption.add(new SelectItem(engines[i], engines[i],
>                 engines[i]));
>     }

> The arguments to the `SelectItem` constructor are:

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

> The section UISelectItems Properties describes in more detail how to write a model object property for a `UISelectItems` component

> ##### The selectitem Tag

> The `cardemo` application contains a few examples of `selectitem` tags, but let's see how the `engineOption` tag would look if you used `selectitem` instead of `selectitems`:

>     <h:selectone_menu id="engineOption"
>     valueRef="CurrentOptionServer.currentEngineOption">
>       <h:selectitem
>         itemValue="v4" itemLabel="v4"/>
>       <h:selectitem
>         itemValue="v6" itemLabel="v6"/>
>       <h:selectitem
>         itemValue="v8" itemLabel="v8"/>
>     </h:selectone_menu>

> The `selectone_menu` tag is exactly the same and maps to the same property, representing the currently selected item.

> The `itemValue` attribute represents the default value of the `SelectItem` instance. The `itemLabel` attribute represents the `String` that appears in the dropdown list component on the page.

> You can also use a `valueRef` attribute instead of the `itemValue` attribute to refer to a bean property that represents the item's value.

Download FAQ History |  | API Search Feedback

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