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 thejsf-core
tag library. Thehtml_basic
tag library defines tags for representing common HTML user interface components. Thejsf-core
tag library defines all of the other tags, including tags for registering listeners and validators on components. The tags injsf-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. Theprefix
attribute value is used to distinguish tags belonging to the tag library. For example, theform
tag must be referenced in the page with theh
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 thejsf_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 theuse_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.
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 Tagsattribute
Tagfacet
Tagparameter
Tag Linking to a URL, anduse_faces
Tag Validator Tags
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 theUIComponent
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 thelib
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:
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 ofUIOutput
have avalueRef
attribute, which is always optional, except in the case ofSelectItems
. Using thevalue-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. Theform
tag encloses all of the controls that display or collect data from the user. Here is theform
tag from theImageMap.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. Theform
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 supportsButton
andHyperlink
asUICommand
component renderers.Using the command_button Tag
Most pages in the
cardemo
example use thecommand_button
tag. When the button is clicked, the data from the current page is processed, and the next page is opened. Here is thebuyButton
command_button
tag frombuy.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. Thebundle
attribute references theResourceBundle
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. ThecommandName
is used by theActionEventListener
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 defaultNavigationHandler
, which matches the outcome against a set of navigation rules defined in the application configuration file.A
command_button
tag can have anactionRef
attribute as an alternative to theaction
attribute. TheactionRef
attribute is a value reference expression that points to anAction
, whose invoke method performs some processing and returns the logical outcome.See section Navigating Between Pages for information on how to use the
action
andactionRef
attributes.The
cardemo
application uses thecommandName
and theaction
attributes together. This is because it uses the outcome from theaction
attribute to navigate between pages, but it also uses thecommandName
attribute to point to a listener that performs some other processing. In practice, this extra processing should be performed by theAction
object, and theactionRef
attribute should be used to point to theAction
object. ThecommandName
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. Thecommand_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 ActionEventsLike the
command_button
tag, thecommand_hyperlink
tag can be used to submitActionEvents
. To submit anActionEvent
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 defaultNavigationHandler
, 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 anAction
, whoseinvoke
method performs some processing and returns the logical outcome.See section Navigating Between Pages for information on how to use the
action
andactionRef
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. ThecommandName
is used by theActionEventListener
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 thecommandName
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 containparameter
tags that will cause an HTML<input type=hidden>
element to be rendered. Thisinput
tag represents a hidden control that stores the name and value specified in theparameter
tags between client/server exchanges so that the server-side classes can retrieve the value. The following two tags showcommand_hyperlink
tags that submitActionEvents
. 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
isduke
andLoginBean.password
isredNose
:<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 submitsActionEvents
will render JavaScript. If you use this tag, make sure your browser is JavaScript-enabled.
Linking to a URLTo use
command_hyperlink
to link to a URL, yourcommand_hyperlink
tag must specify thehref
attribute, indicating the page to which to link.A
command_hyperlink
that links to a URL can also containparameter
tags. Theparameter
tags for this kind ofcommand_hyperlink
tag allow the page author to add query strings to the URL. The following two tags showcommand_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:
The second tag renders the following HTML, assuming that
LoginBean.name
is duke andLoginBean.password
is redNose:The UIGraphic Component
The
UIGraphic
component displays an image. Thecardemo
application has many examples ofgraphic_image
tags. Here is thegraphic_image
tag used with the image map onImageMap.jsp
:The
url
attribute specifies the path to the image. It also corresponds to the local value of theUIGraphic
component so that the URL can be retrieved with thecurrentValue
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 customUIMap
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. TheUIOutput
component displays data that cannot be modified. The most common example is a label.Both
UIInput
andUIOutput
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
andUIOutput
. Recall from The Component Rendering Model that the tags are composed of the component and the renderer. For example, theinput_text
tag refers to aUIInput
component that is rendered with theText
Renderer.
In addition to the renderers listed in Table 21-10,
UIInput
andUIOutput
each support other renderers that the other component does not support. These are listed in Table 21-11.
All of the tags listed in Table 21-10--except for the
input_text
andoutput_text
tags--display or accept data of a particular format specified in thejava.text
orjava.util
packages. You can also apply theDate
,DateTime
,Number
, andTime
renderers associated with these tags to convert data associated with theinput_text
,output_text
,input_hidden
, andinput_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
, andinput_text
.The
output_errors
tag is explained in Performing Validation. The tags associated with theDate
,Number
, andTime
renderers are defined in a similar way to those tags associated with theDateTime
renderer. Theinput_hidden
andinput_textarea
tags are similar to theinput_text
tag. Refer to thehtml_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 bothUIInput
andUIOutput
components. Theinput_datetime
tag displays and accepts data in ajava.text.SimpleDateFormat
. Theoutput_datetime
tag displays data in ajava.text.SimpleDateFormat
. This section shows you how to use theoutput_datetime
tag. Theinput_datetime
tag is written in a similar way.The
output_datetime
andinput_datetime
tags have the following attributes and values for formatting data:See
java.text.SimpleDateFormat
andjava.util.TimeZone
for information on specifying the style ofdateStyle
,timeStyle
, andtimezone
. You can use the first three attributes in the same tag simultaneously or separately. Or, you can simply useformatPattern
to specify aString
pattern to format the data. The following tag is an example of using theformatPattern
attribute:One example of a date and time that this tag can display is:
You can also display the same date and time with this tag:
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
, andTime
renderers are written in a similar way. See thehtml_basic
TLD in thelib
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 bothUIInput
andUIOutput
components. Theinput_text
tag displays and accepts a single-line string. Theoutput_text
tag displays a single-line string. This section shows you how to use theinput_text
tag. Theoutput_text
tag is written in a similar way.The following attributes, supported by both
output_text
andinput_text
, are likely to be the most commonly used:
id
: Identifies the component associated with this tagvalueRef
: Identifies the model object property bound to the componentconverter
: Identifies one of the renderers that will be used to convert the component's local data to the model object property data specified in thevalueRef
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 thekey
andbundle
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 theCustomer.jsp
page:The
valueRef
value refers to thefirstName
property on theCustomerBean
model object. After the user submits the form, the value of thefirstName
property inCustomerBean
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 anoutput_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 theid
of the input field to which the label is attached. Theoutput_text
tag nested inside theoutput_label
tag represents the actual label. Thevalue
attribute on theoutput_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 aMessageFormat
pattern. Here is an example of anoutput_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 theMessageFormat
pattern. Theparameter
tags specify the substitution parameters for the message. ThevalueRef
forparam1
maps to the user's name in theLoginBean
. This value replaces{0}
in the message. ThevalueRef
forparam2
maps to the item the user ordered in theOrderBean
. This value replaces{1}
in the message. Make sure you put theparameter
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 thevalue
attribute on theparameter
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 aninput_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, aUIPanel
is rendered as an HTML table. Table 21-12 lists all of the renderers and tags corresponding to theUIPanel
component.
The
panel_grid
andpanel_list
tags are used to represent entire tables. Thepanel_data
tags andpanel_group
tags are used to represent rows in the tables. To represent individual cells in the rows, theoutput_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 apanel_list
. Apanel_group
can be used in bothpanel_grid
tags andpanel_list
tags. The next two sections show you how to create tables withpanel_grid
andpanel_list
, and how to use thepanel_data
andpanel_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: thecolumnClasses
,footerClass
,headerClass
,panelClass
, androwClasses
. These stylesheet attributes are not required.The
panel_grid
tag also has acolumns
attribute. Thecolumns
attribute is required if you want your table to have more than one column because thecolumns
attribute tells the renderer how to group the data in the table.If a
headerClass
is specified, thepanel_grid
must have a header as its first child. Similarly, if afooterClass
is specified, thepanel_grid
must have a footer as its last child.The
cardemo
application includes onepanel_grid
tag on thebuy.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
. Thispanel_grid
uses stylesheet classes to format the table. The CSS classes are defined in thestylesheet.css
file in the <JWSDP_HOME
>/jsf/samples/cardemo/web
directory of your installation. Thesubtitlebig
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 aheaderClass
and afooterClass
, thepanel_grid
must contain a header and footer. Usually, afacet
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 afacet
tag for both the headers and footers. Facets can only have one child, and so apanel_group
tag is needed to group more than one element within afacet
. In the case of theheader
facet, apanel_group
tag is not really needed. This tag could be written like this:The
panel_group
tag is needed within thefooter
facet tag because the footer requires two cells of data, represented by the twooutput_text
tags within thepanel_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
andfooter
facet tags, are theoutput_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 theoutput_text
tag. Thecolumns
attribute in the example is set to "2". So from the list ofoutput_text
tags representing the table data, the data from the oddoutput_text
tags is rendered in the first column and the data from the evenoutput_text
tags is rendered in the second column.Using the panel_list Tag
The
panel_list
tag has the same set of stylesheet attributes aspanel_grid
, but it does not have acolumns
attribute. The number of columns in the table equals the number ofoutput_text
(or other component tag) elements within thepanel_data
tag, which is nested inside thepanel_list
tag. Thepanel_data
tag iterates over aCollection
,array
,Iterator
, orMap
of model objects. Eachoutput_text
tag nested in apanel_data
tag maps to a particular property of each of the model objects in the list. Here is an example of apanel_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 ofoutput_text
tags nested inside apanel_group
tag to represent a header row. See the previous section for a description of using facets andpanel_group
tags.The component represented by the
panel_data
tag maps to a bean that is aCollection
,array
,Iterator
, orMap
of beans. ThevalueRef
attribute refers to this bean, calledCustomerListBean
. Thevar
attribute refers to the current bean in theCustomerListBean
list. In this example, the current bean in the list is calledcustomer
. Each component represented by an output_text tag maps to a property on thecustomer
bean.The
panel_data
tag's purpose is to iterate over the model objects and allow theoutput_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 aboolean
value. Theselectboolean_checkbox
tag is the only tag that JavaServer Faces technology provides for representing boolean state. Themore.jsp
page has a set ofselectboolean_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. Thelabel
attribute value is what is displayed next to the checkbox. ThevalueRef
attribute refers to the model object property associated with the component. The property that aselectboolean_checkbox
tag maps to should be of typeboolean
, 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 theselectmany_checkboxlist
andselectmany_menu
tags. Theselectmany_listbox
tag is similar to theselectmany_menu
tag, exceptselectmany_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 aselectmany_checkboxlist
tag, but this tag can be used to render the checkboxes on themore.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 theselectitems
tag. To represent each item individually, use aselectitem
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 theselectmany_menu
tag. Here is an example of aselectmany_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 theselectmany_checkboxlist
tag. Again, thevalueRef
of theselectmany_menu
tag maps to the property that holds the currently selected items' values. Aselectmany_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, theselectmany_menu
tag must contain either aselectitems
tag or a set ofselectitem
tags for representing the items in the list. ThevalueRef
attribute of theselectitems
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. Thecardemo
example uses theselectone_radio
andselectone_menu
tags. Theselectone_listbox
tag is similar to theselectone_menu
tag, exceptselectone_listbox
does not have asize
attribute since a listbox displays all items at once. This section explains how to use theselectone_radio
andselectone_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 aselectone_radio
tag frommore.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 theselectone_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 forbrakeOption
, which iscurrentBrakeOption
. This property holds the value of the currently selected item from the set of radio buttons. ThecurrentBrakeOption
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 theselectitems
tag. To represent each item individually, use aselectitem
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 theselectone_menu
tag. Here is theselectone_menu
tag from themore.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 theselectone_radio
tag. Again, thevalueRef
of theselectone_menu
tag maps to the property that holds the currently selected item's value. Aselectone_menu
tag can also have asize
attribute, whose value specifies how many items will display at one time in the menu. When thesize
attribute is set, the menu will render with a scrollbar for scrolling through the displayed items.Like the
selectone_radio
tag, theselectone_menu
tag must contain either aselectitems
tag or a set ofselectitem
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 theUISelectItems
classes represent components that can be nested inside aUISelectOne
or aUISelectMany
component. TheUISelectItem
is associated with aSelectItem
instance, which contains the value, label, and description of a single item in theUISelectOne
orUISelectMany
component. TheUISelectItems
class represents a set ofSelectItem
instances, containing the values, labels, and descriptions of the entire list of items.The
selectitem
tag represents aUISelectItem
component. Theselectitems
tag represents aUISelectItems
component. You can use either a set ofselectitem
tags or a singleselectitems
tag within yourselectone
orselectmany
tags.The advantages of using
selectitems
areThe advantages of using
selectitem
are: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 theselectitems
andselectitem
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 theselectitems
tag refers to theUISelectItems
component object.The
valueRef
attribute binds theselectitems
tag to theengineOption
property ofCurrentOptionServer
.In the
CurrentOptionServer
, theengineOption
property has a type ofArrayList
:
UISelectItems
is a collection ofSelectItem
instances. You can see this by noting how theengineOption
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:The section UISelectItems Properties describes in more detail how to write a model object property for a
UISelectItems
componentThe selectitem Tag
The
cardemo
application contains a few examples ofselectitem
tags, but let's see how theengineOption
tag would look if you usedselectitem
instead ofselectitems
:<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 theSelectItem
instance. TheitemLabel
attribute represents theString
that appears in the dropdown list component on the page.You can also use a
valueRef
attribute instead of theitemValue
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.