| |||||||
FRAMES NO FRAMES |
Use the webuijsf:dropDown
tag to display a drop-down
menu that enables users to select one or more items from a list. The
drop-down menu occupies one line of the page, and displays one list item.
The rest of the list items are displayed when the user opens the menu.
The The dropDown component renders an XHTML Use the The first time the component is rendered, the option that
corresponds to the value of the To optionally specify a label for the component, use the A drop-down menu can be configured as a jump menu. Jump menus
immediately perform an action, such as opening a window or navigating
to another page, when the user selects an item. This action is
accomplished by submitting the form immediately when the user changes
the selection. By default, the dropDown menu is not a jump menu. The
submission of the form does not occur until the user activates another
component such as a button in order to submit the form. To configure the If the jump menu is to perform an action other than navigation, you
should use the The You can display a non-selectable title as the first item in a
drop-down menu. The title might be used to provide a brief instruction for
the user, such as "Select a page". To create a title in a drop-down menu, when you define your drop
down menu items in an Option[], you must specify the first Option as
type OptionTitle along with the string to display. The title is
rendered as the specified string with dashes before and after the text,
to differentiate the title from the selectable options. For example, in this sample backing bean Option, the OptionTitle
option is bolded. In addition, you should set the The XHTML The drop-down menu that is rendered with this property will appear
as follows: The important points to note in the sample backing bean are: The OptionGroup A separator (a series of dashes) is rendered above the optgroup
label. By default, the separator is rendered above each optgroup in a
drop-down menu. The separators can be removed by setting the The The The webuijsf:dropDown tag supports a When the component is rendered, a DOM object corresponding to the
component is created. To manipulate the component on the client side,
you may invoke functions on the DOM object. With reference to the DOM
ID, to disable the component, invoke webuijsf:dropDown
tag can be configured to
immediately submit the form when the user makes a selection. By
default, the drop-down HTML Elements and Layout
<select>
element with an optional <label>
element. The <option>
elements within the <select>
element are derived
from the webuijsf:dropDown
tag's items
attribute.Configuring the
webuijsf:dropdown
tagitems
attribute to specify the options to be
displayed in the drop-down menu. The value must be a JavaServer Faces
EL expression that identifies an array, a java.util.Collection
or a java.util.Map
of com.sun.webui.jsf.model.Option
.selected
model object
property is marked as selected, using the equals
method
on the model object. On subsequent displays of the page, the previously
selected option is redisplayed as the selection. If you want the menu
to always show the default selection, set the forgetValue
attribute to true. label
attribute, or specify a label
facet.
Configuring a Jump Menu
webuijsf:dropDown
tag to render a
jump menu, set the submitForm
attribute to true. If the
jump menu is to be used to navigate to another location, you should
also use the navigateToValue
attribute and include
outcome strings in the drop-down menu's list of options. In addition,
you should set the forgetValue
attribute to true to cause
the dropDown's selected value to be reset when the page is redisplayed.
This enables the dropDown to always display the same option initially. actionListener
attribute to bind to a
method to handle the action.immediate
attribute is useful in a jump menu when
you do not want to submit any data entered into the form when a
selection is made in the jump menu.Using a Title in the Drop-Down Menu
public BackingFileDropDown() {
pageOptions = new Option[4];
pageOptions[0] =
new OptionTitle("Select a Page");
pageOptions[1] = new
Option("indexPage", "Main Page");
pageOptions[2] = new Option("printerPage", "Printer
Status");
pageOptions[3] = new Option("faxPage", "Fax
Machines");
}
webuijsf:dropDown
tag's forgetValue
attribute to true, to ensure that the
title is always displayed in the drop-down menu when the page is
rendered.Grouping Options in the Drop-Down Menu
<select>
element can contain an <optgroup>
element to define a group of related items in a drop-down menu. The <optgroup>
has a label, and the options within the group are indented in the
displayed menu. You can configure the list of items created with the webuijsf:dropDown
tag to be rendered with <optgroup>
elements by
setting up your backing bean appropriately. A backing bean object that
populates the drop-down menu with grouped options might look as follows.public BackingFileDropDown2() {
actionOptions = new Option[5];
actionOptions[0] = new OptionTitle("More Actions");
actionOptions[1] = new Option("Action1", "Action 1");
actionOptions[2] = new Option("Action2", "Action 2");
actionOptions[2].setDisabled(true);
actionOptions[3] = new Option("Action3", "Action 3");
OptionGroup group = new OptionGroup();
group.setLabel("ActionGroup");
Option[] groupedOptions = new Option[3];
groupedOptions[0] = new Option("Action4", "Action
4");
groupedOptions[1] = new Option("Action5", "Action
5");
groupedOptions[2] = new Option("Action6", "Action
6");
groupedOptions[2].setDisabled(true);
group.setOptions(groupedOptions);
actionOptions[4] = group;
}
group
has a setLabel
method that sets the label of the <optgroup>
to
"ActionGroup".webuijsf:dropDown
tag's separators
attribute to false. group
is defined as the last item in the actionOptions
Option instance. The setOptions
method sets the options
of the group
to the groupedOptions
object
values.setDisabled
method can be used to disable any
of the options in the drop-down menu.Facets
label
facet. Use
this facet to specify a custom component for the label. This facet
overrides the label
attribute.Client-side JavaScript Functions
document.getElementById(id).setProps({visible:
false})
.
getProps()
Used to get widget
properties. Please see
setProps()
function for a list of
supported properties.
getSelectElement()
Used to access the HTML
<select>
element that is rendered by the component.
getSelectedLabel()
Used to get the label of the first selected
option on the dropDown. If no option is selected, this function returns
null.
getSelectedValue()
Used to get the value of the
first selected option on the dropDown. If no option is selected,
this function returns null.
refresh(execute)
Used to asynchronously refresh the component.
execute
portion of
the request processing lifecycle must be run. If omitted, no other
components are executed.
setProps(props)
Used to change any of the following supported
properties:
submit(execute)
Used to asynchronously submit the component.
execute
portion of
the request processing lifecycle must be run. If omitted, the component
on which the function has been invoked, is submitted.
subscribe(topic, obj, func)
Use this function to subscribe
to an event topic.
When the component is manipulated client-side, some functions might
publish event topics for custom Ajax implementations to listen for.
For example, you can listen for
the refresh event topic by using:
<webuijsf:script>
var processEvents =
{
update: function(props) {
//
Do something...
}
}
// Subscribe to refresh event.
var domNode = document.getElementById("form1:test1");
domNode.subscribe(domNode.event.refresh.endTopic,
processEvents, "update");
</webuijsf:script>
<Node>.event.refresh.beginTopic | Event topic published before asynchronously refreshing the
component. Supported properties include:
|
<Node>.event.refresh.endTopic | Event topic published after asynchronously refreshing the
component. Supported properties include:
|
<Node>.event.submit.beginTopic | Event topic published before asynchronously submitting the
component. Supported properties include:
|
<Node>.event.submit.endTopic |
Event topic published after asynchronously submitting the component. Supported properties include:
|
This example uses several backing beans. The options to display in
the drop-down menu are provided in the items
attribute,
which is set to an EL expression that resolves to an airports
array in the dataBean
. The tag generates a drop-down menu
with a label, which is specified with the label
attribute, and the label text is obtained from the chooseDepartureAirport
property of a msgs
bean. The tooltip text is provided in
a similar way. The selected
attribute specifies the
option to show as selected in the menu, with the value stored in the leaveAirport
property of the flightSearch
backing bean.
<webuijsf:dropDown selected="#{flightSearch.leaveAirport}"
items="#{dataBean.airports}"
id="leaveAirport"
tooltip="#{msgs.chooseAirport}"
label="#{msgs.chooseDepartureAirport}" />
The dataBean
backing bean would include the following
definition for the "airports" items:
private Option[] airports = null;
// Creates a new instance of backing bean //
public DataBean() {
airports = new Option[11];
airports[0] = new Option("SFO", "San Francisco");
airports[1] = new Option("OAK", "Oakland");
airports[2] = new Option("SAN", "San Diego");
airports[3] = new Option("BOS", "Boston");
airports[4] = new Option("ARN", "Stockholm");
airports[5] = new Option("MNL", "Manila");
airports[6] = new Option("CDG", "Paris");
airports[7] = new Option("PDX", "Portland");
airports[8] = new Option("LAX", "Los Angeles");
airports[9] = new Option("NRT", "Tokyo");
airports[10] = new Option("TBD", "Future Airport");
airports[10].setDisabled(true);
}
public Option[] getAirports() {
return airports;
}
This example is the same as Example 1 except that it uses the label
facet, which contains a webuijsf:label
tag.
<webuijsf:dropDown selected="#{flightSearch.leaveAirport}"
items="#{dataBean.airports}"
id="leaveAirport"
tooltip="#{msgs.chooseAirport}" >
<f:facet name="label">
<webuijsf:label text="#{msgs.chooseDepartureAirport}" for="menuform1:leaveAirport"/>
</f:facet>
</webuijsf:dropDown>
This example shows a drop-down menu that submits the form as soon as the user makes a selection. The action of this dropDown component does not move to another page (no action or navigation rule has been configured). When the form is submitted, the selected value is updated. After submitting the form, the value of the DropDown is displayed by the staticText component.
<webuijsf:dropDown items="#{dataBean.airports}"
submitForm="true"
required="true"
id="airport"
selected="#{dataBean.airport}">
<f:facet name="label">
<webuijsf:label text="Set airport:" for="menuform1:airport"/>
</f:facet>
</webuijsf:dropDown>
<p>
<webuijsf:label text="Current airport: ">
<webuijsf:staticText text="#{dataBean.airport}" id="blah" />
</webuijsf:label>
This example shows a drop-down menu that allows the user to jump to
the page indicated by the selected item. The component is configured
with navigateToValue="true", so the action value returned by the
component is the value of the selected item. The selected value should
be an outcome string that is declared in a navigation rule in the faces-config.xml
file.
<webuijsf:dropDown submitForm="true"The DropDownBean defines the menu items as shown below.
navigateToValue="true"
items="#{DropDownBean.pageOptions}"
id="airport"
label="Choose your page:"/>
public BackingFileDropDown3() {
pageOptions = new Option[4];
pageOptions[0] = new OptionTitle("Select a Page" );
pageOptions[1] = new Option("indexPage", "Test App Index" );
pageOptions[2] = new Option("hyperlinkPage", "HyperLink Test Page");
pageOptions[3] = new Option("tablePage", "Table Test Page");
}
<webuijsf:radioButton id="rb1" name="rb1" label="Hide
Menu" onClick="hideMenu()"/>
<webuijsf:dropDown
id="menu1"
items="#{dataBean.airports}"
label="#{msgs.chooseDepartureAirport}"
selected="#{flightSearch.leaveAirport}"
tooltip="#{msgs.chooseAirport}"
/>
<webuijsf:script>
function toggleDisabled() {
var domNode =
document.getElementById("form1:
menu1"); // Get menu
return
domNode.setProps({disabled: !domNode.getProps().disabled}); // Toggle
disabled state
}
</webuijsf:script>
<webuijsf:radioButton id="rb1" name="rb1" label="Refresh Menu"
onClick="refreshMenu()"/>
<webuijsf:dropDown
id="menu1"
items="#{dataBean.airports}"
label="#{msgs.chooseDepartureAirport}"
selected="#{flightSearch.leaveAirport}"
tooltip="#{msgs.chooseAirport}"
/>
<webuijsf:script>
function refreshMenu() {
var domNode =
document.getElementById("form1:menu1"); // Get menu
return domNode.refresh(); //
Asynchronously refresh menu
}
</webuijsf:script>
Note that the refresh function can optionally take a list of
elements
to execute. Thus, a comma-separated list of ids can be provided to
update components server-side: refresh("form1:id1,form2:id2,..."). When
no parameter is given, the refresh function acts as a reset.
That is, the component will be redrawn using values set
server-side, but not updated.
<webuijsf:dropDown
id="menu1"
items="#{dataBean.airports}"
label="
#{MyBean.label}
"
selected="#{flightSearch.leaveAirport}"
tooltip="#{msgs.chooseAirport}"
/>
<webuijsf:textField id="field1"
text="#{MyBean.label}"
label="Change Menu Label"
onKeyPress="setTimeout('refreshMenu();', 0);"/>
// Field used to
asynchronously update label.
<webuijsf:script>
function
refreshMenu
() {
var domNode =
document.getElementById("form1:menu1"); // Get menu
return
domNode.refresh("form1:field1"); // Asynchronously refresh while
submitting field value
}
</webuijsf:script>
Note that the refresh function can optionally take a list of
elements to execute. Thus, a comma-separated list of IDs can be provided to
update components server-side: refresh("form1:id1,form2:id2,...")Tag Information | |
Tag Class | com.sun.webui.jsf.component.DropDownTag |
TagExtraInfo Class | None |
Body Content | JSP |
Display Name | None |
Attributes | ||||
Name | Required | Request-time | Type | Description |
binding | false | false | java.lang.String | A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children. |
toolTip | false | false | java.lang.String | Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element. |
submitForm | false | false | java.lang.String | When the submitForm attribute is set to true, the form is immediately submitted when the user changes the selection in the drop down list. |
htmlTemplate | false | false | java.lang.String | Alternative HTML template to be used by this component. |
actionExpression | false | false | java.lang.String | Used to specify the action to take when this component is activated by the user. The value of the actionExpression attribute must be one of the following:
When you use the actionExpression attribute in the DropDown component, you must set the submitForm attribute to true. |
actionListenerExpression | false | false | java.lang.String | Used to specify a method to handle an action event that is
triggered when this component is activated by the user. The
value must be a JavaServer Faces EL expression that resolves
to a method in a backing bean. The method must take a single parameter
that is an ActionEvent, and its return type must be The actionListenerExpression method is only invoked when the submitForm attribute is true. |
readOnly | false | false | java.lang.String | If this attribute is set to true, the value of the component is rendered as text, preceded by the label if one was defined. Deprecated: The attribute is deprecated starting from version 4.1 |
navigateToValue | false | false | java.lang.String | When this attribute is set to true, the value of the menu selection is used as the action, to determine which page is displayed next according to the registered navigation rules. Use this attribute instead of the action attribute when the drop down is used for navigation. When you set navigateToValue to true, you must also set submitForm to true. |
forgetValue | false | false | java.lang.String | If this flag is set to true, then the component is always rendered with no initial selection. By default, the component displays the selection that was made in the last submit of the page. This value should be set to true when the drop down is used for navigation. |
onDblClick | false | false | java.lang.String | Scripting code that is executed when a mouse double-click occurs over this component. |
labelOnTop | false | false | java.lang.String | If true, the label is rendered above the component. If false, the label is rendered next to the component. The default is false. |
onKeyPress | false | false | java.lang.String | Scripting code that is executed when the user presses and releases a key while the component has the focus. |
onFocus | false | false | java.lang.String | Scripting code that is executed when this component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse. |
rendered | false | false | java.lang.String | Indicates whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission. |
id | false | true | java.lang.String | No Description |
onKeyUp | false | false | java.lang.String | Scripting code that is executed when the user releases a key while the component has the focus. |
onMouseUp | false | false | java.lang.String | Scripting code that is executed when the user releases a mouse button while the mouse pointer is on the component. |
styleClass | false | false | java.lang.String | CSS style class or classes to be applied to the outermost HTML element when this component is rendered. |
items | false | false | java.lang.String | Specifies the options that the web application user can choose
from. The value must be one of an array, Map or Collection
whose members are all subclasses of |
style | false | false | java.lang.String | CSS style or styles that are applied to the outermost HTML element when the component is rendered. |
onClick | false | false | java.lang.String | Scripting code that is executed when a mouse click occurs over the component. |
onBlur | false | false | java.lang.String | Scripting code that is executed when this element loses the focus. |
onMouseDown | false | false | java.lang.String | Scripting code that is executed when the user presses a mouse button while the mouse pointer is on the component. |
converter | false | false | java.lang.String | Specifies a method to translate native
property values to String and back for this component. The converter
attribute value must be one of the following:
|
required | false | false | java.lang.String | Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error. |
disabled | false | false | java.lang.String | Flag indicating that the user is not permitted to activate this component, and that the component's value will not be submitted with the form. |
validatorExpression | false | false | java.lang.String | Used to specify a method in a backing bean to validate input
to the component. The value must be a JavaServer Faces
EL expression that resolves to a public method with
return type void. The method must take three parameters:
The backing bean where the method is defined must implement
The method is invoked during the Process Validations Phase. |
onMouseOut | false | false | java.lang.String | Scripting code that is executed when a mouse out movement occurs over this component. |
separators | false | false | java.lang.String | Flag indicating that items corresponding to
|
onMouseOver | false | false | java.lang.String | Scripting code that is executed when the user moves the mouse pointer into the boundary of this component. |
onMouseMove | false | false | java.lang.String | Scripting code executed when the user moves the mouse pointer while over the component. |
selected | false | false | java.lang.String | The object that represents the selections made from the available options. If multiple selections are allowed, this must be bound to an Object array, or an array of primitives. |
immediate | false | false | java.lang.String | Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase. |
label | false | false | java.lang.String | If set, a label is rendered adjacent to the component with the value of this attribute as the label text. |
onChange | false | false | java.lang.String | Scripting code executed when the element value of this component is changed. |
visible | false | false | java.lang.String | Indicates whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present. |
onKeyDown | false | false | java.lang.String | Scripting code that is executed when the user presses down on a key while the component has the focus. |
labelLevel | false | false | java.lang.String | Sets the style level for the generated label, provided the label attribute has been set. Valid values are 1 (largest), 2 and 3 (smallest). The default value is 2. |
valueChangeListenerExpression | false | false | java.lang.String | Specifies a method to handle a value-change event that is triggered
when the user enters data in the input component. The
attribute value must be a JavaServer Faces EL expression that
resolves to a backing bean method. The method must take a single
parameter of type javax.faces.event.ValueChangeEvent ,
and its return type must be void. The backing bean where the
method is defined must implement java.io.Serializable
or javax.faces.component.StateHolder .
|
tabIndex | false | false | java.lang.String | Describes the position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767. |
Variables | No Variables Defined. |
| |||||||
FRAMES NO FRAMES |