webuijsf
Tag dropDown


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 webuijsf:dropDown tag can be configured to immediately submit the form when the user makes a selection. By default, the drop-down is used only for selecting items, and does not submit the form.

HTML Elements and Layout

The dropDown component renders an XHTML <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 tag

Use the items 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.

The first time the component is rendered, the option that corresponds to the value of the 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.

To optionally specify a label for the component, use the label attribute, or specify a label facet.

Configuring a Jump Menu

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

If the jump menu is to perform an action other than navigation, you should use the actionListener attribute to bind to a method to handle the action.

The 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

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.

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");
}

In addition, you should set the 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

The XHTML <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;
}

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:

Facets

The webuijsf:dropDown tag supports a label facet. Use this facet to specify a custom component for the label. This facet overrides the label attribute.

Client-side JavaScript Functions

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 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.
  • [optional] execute: Comma separated string containing a list of client IDs against which the 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:
  • id
  • dir
  • disabled
  • label
  • lang
  • multiple
  • onBlur
  • onChange
  • onClick
  • onDblClick
  • onFocus
  • onMouseDown
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onMouseMove
  • onKeyPress
  • onKeyUp
  • onSelect
  • options
  • size
  • submitForm
  • style
  • tabIndex
  • title
  • visible
submit(execute)
Used to asynchronously submit the component.
  • [optional] execute: Comma separated string containing a list of client IDs against which the 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.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client-side JavaScript Events

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>

The following events are supported.

<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client ID to process the event for
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include:
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client ID to process the event for
<Node>.event.submit.endTopic

Event topic published after asynchronously submitting the component. Supported properties include:

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

Examples

Example 1: Drop-Down Menu Using Backing Beans

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;
}

Example 2: Drop-Down Menu With Label Facet

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>

Example 3: Jump Drop-Down Menu

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>

Example 4: Jump Drop-Down Menu Used For Navigation

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" 
navigateToValue="true"
items="#{DropDownBean.pageOptions}"
id="airport"
label="Choose your page:"/>
The DropDownBean defines the menu items as shown below.
                             
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");
}

Example 5: Update Client-Side Drop-Down Menu Properties Using getProps and setProps Functions

This example shows how to toggle the disabled state of a drop-down menu client side using the getProps and setProps functions. When the user selects the Hide Menu option, the drop-down menu is either disabled or enabled.

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

Example 6: Asynchronously Update Drop-Down Menu Using Refresh Function

This example shows how to asynchronously update a drop-down menu using the refresh function. When the user selects the Refresh Menu option, the drop-down menu is asynchronously updated with new data.

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

Example 7: Asynchronously Update Drop-Down Menu Using Refresh Function

This example shows how to asynchronously update a drop-down menu using the refresh function. The execute property of the refresh function is used to define the client ID which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the drop-down menu label is updated client-side -- all without a page refresh.

<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 Classcom.sun.webui.jsf.component.DropDownTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.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.
toolTipfalsefalsejava.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.

submitFormfalsefalsejava.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.

htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
actionExpressionfalsefalsejava.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:

  • an outcome string, used to indicate which page to display next, as defined by a navigation rule in the application configuration resource file (faces-config.xml).
  • a JavaServer Faces EL expression that resolves to a backing bean method. The method must take no parameters and return an outcome string. The class that defines the method must implement the java.io.Serializable interface or javax.faces.component.StateHolder interface.

When you use the actionExpression attribute in the DropDown component, you must set the submitForm attribute to true.

actionListenerExpressionfalsefalsejava.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 void. The class that defines the method must implement the java.io.Serializable interface or javax.faces.component.StateHolder interface.

The actionListenerExpression method is only invoked when the submitForm attribute is true.

readOnlyfalsefalsejava.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
navigateToValuefalsefalsejava.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.

forgetValuefalsefalsejava.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.

onDblClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse double-click occurs over this component.

widthfalsefalsejava.lang.String The width property is a value for the CSS width property suitable for the select HTML element.
labelOnTopfalsefalsejava.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.

onKeyPressfalsefalsejava.lang.String

Scripting code that is executed when the user presses and releases a key while the component has the focus.

onFocusfalsefalsejava.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.

renderedfalsefalsejava.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.
idfalsetruejava.lang.StringNo Description
onKeyUpfalsefalsejava.lang.String

Scripting code that is executed when the user releases a key while the component has the focus.

onMouseUpfalsefalsejava.lang.String

Scripting code that is executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

CSS style class or classes to be applied to the outermost HTML element when this component is rendered.

itemsfalsefalsejava.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 ofcom.sun.webui.jsf.model.Option.

stylefalsefalsejava.lang.String

CSS style or styles that are applied to the outermost HTML element when the component is rendered.

onClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse click occurs over the component.

onBlurfalsefalsejava.lang.String

Scripting code that is executed when this element loses the focus.

onMouseDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses a mouse button while the mouse pointer is on the component.

converterfalsefalsejava.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:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
requiredfalsefalsejava.lang.String Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
disabledfalsefalsejava.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.

validatorExpressionfalsefalsejava.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:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

onMouseOutfalsefalsejava.lang.String

Scripting code that is executed when a mouse out movement occurs over this component.

separatorsfalsefalsejava.lang.String

Flag indicating that items corresponding to com.sun.webui.jsf.model.Option that are defined inside a com.sun.webui.jsf.model.OptionGroup should be surrounded by separators inside the list. The default value is true. If false, no separators are shown. To manually specify the location of separators, set this flag to false and place instances of com.sun.webui.jsf.model.Separator between the relevant com.sun.webui.jsf.model.Option instances when specifying the items attribute.

onMouseOverfalsefalsejava.lang.String

Scripting code that is executed when the user moves the mouse pointer into the boundary of this component.

onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

selectedfalsefalsejava.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.

immediatefalsefalsejava.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.
labelfalsefalsejava.lang.String

If set, a label is rendered adjacent to the component with the value of this attribute as the label text.

onChangefalsefalsejava.lang.String

Scripting code executed when the element value of this component is changed.

visiblefalsefalsejava.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.

onKeyDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses down on a key while the component has the focus.

labelLevelfalsefalsejava.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.

valueChangeListenerExpressionfalsefalsejava.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.
tabIndexfalsefalsejava.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.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.