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:

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:

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:

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
Event Handling Tags	`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.

Using the HTML 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

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 this release, the id attribute is not required for a component tag except in these situations:

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:

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:

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:

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:

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:

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.

The second tag renders this HTML, assuming that LoginBean.name is duke and LoginBean.password is 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.

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.

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

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:

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
Date	`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
DateTime	`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`
Number	`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.
Text	`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
Time	`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:

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.

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:

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:

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:

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.

<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:

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:

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:

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:

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.

The UISelectBoolean Component

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 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:

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:

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:

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:

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:

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.

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.

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

The selectitems Tag

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:

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

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:

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.