SelectOneMenu 2.x - roberts-sandbox/test-wiki-page-title GitHub Wiki

TOCSTART

TOCEND

The SelectOneMenu component is an extended version of the standard JSF SelectOneMenu component, which adds such features as auto-suggestion for convenient support of large lists, embedding components to select items and multi-column drop-down lists.

Online Demo

• Supporting all features of the standard SelectOneMenu component
• Specifying List of Items
• Representing value by individual column
• Auto-Suggestion difference
• Difference between SelectOneMenu and DropDownField

This documentation page is under construction

OpenFaces <o:selectOneMenu> API-compatible with its standard analog <h:selectOneMenu>. You can migrate to the OpenFaces version quite easily. For example you have the following code:

<h:selectOneMenu value="#{SelectOneMenuBean.selectedCity}" converter="#{SelectOneMenuBean.cityConverter}">
  <f:selectItems value="#{SelectOneMenuBean.cityItems}"/>
</h:selectOneMenu>

You just need to replace <h:selectOneMenu> to <o:selectOneMenu>

<o:selectOneMenu value="#{SelectOneMenuBean.selectedCity}" converter="#{SelectOneMenuBean.cityConverter}">
  <f:selectItems value="#{SelectOneMenuBean.cityItems}"/>
</o:selectOneMenu>

After this you will be able to use all OpenFaces SelectOneMenu features. We still have one incompatibility between standard and OpenFaces realisation of this component - <f:selectItem> doesn't support the itemDisabled standard attribute, so you can't disable item for selection.
In the same way as in a standard <h:seleconeMenu> the value displayed in selected item doesn't always equal the value that will be submitted to server because it's just presentation value. In our component we actually make full html copy of SelectItem in suggestion list. So that means that all embedded components and styles from <f:selectItem> will be copied to selected item field after selection.

To add the SelectOneMenu component to a page, use the <o:selectOneMenu> tag. There are three ways to specify items that will be displayed in the drop-down list. Regardless of the way you choose, each item is assigned a value which is an arbitrary Object that becomes a selected value of the SelectOneMenu component once an appropriate item is selected. You can specify SelectOneMenu list items in the following ways:

• Create a fixed list of values right on the JSF page. To do so, you should use the <f:selectItem> tag to specify each separate item. The value attribute of the <f:selectItem> tag can either be a String literal, which specifies a string value for this item, or a value binding expression, which refers to an Object that will be the value for this item. The example below shows the SelectOneMenu component containing three items in the list.

  	    <f:selectItem value="Martin Luther King, Jr."/>
              <f:selectItem value="Inauguration Day"/>
              <f:selectItem value="Presidents Day"/>
  

It is also possible to add child components to the <f:selectItem> tag. The following example demonstrates this feature displaying not just name of the holiday, but also some icon which represent this holiday.

            <f:selectItem value="New Year's Day">
                <h:graphicImage url="../images/selectonemenu/newyear.png"/>
                <h:outputText value="New Year's Day" />
            </f:selectItem>
            <f:selectItem value="Martin Luther King, Jr.">
                <h:graphicImage url="../images/selectonemenu/luterday.png"/>
                <h:outputText value="Martin Luther King, Jr." style="padding-left: 5px;"/>
            </f:selectItem>
            <f:selectItem value="Inauguration Day">
                <h:graphicImage url="../images/selectonemenu/inaguration.png"/>
                <h:outputText value="Inauguration Day" style="padding-left: 5px;"/>
            </f:selectItem>

When we embed some component into <f:selectItem> tag, the value attribute doesn't display anymore, so to display some text information we need to use <h:outputText> tag. But we still need to specify value attribute in <f:selectItem> tag, this value will be used for suggestions and also it will be submitted to server if the item is selected.

• Retrieve the list of items from a backing bean. To do so, you should use the <f:selectItems/> tag, see JavaServer Faces specification for more information. The value attribute of the <f:selectItems/> tag should be bound to the collection or array of item value objects:

  <f:selectItems value="#{SelectOneMenuBackingBean.availableItems}"/>
  

  And here's how the SelectItems property is defined in the SelectOneMenuBackingBean class:

      <div class="code panel" style="border-width: 1px;">
          <div class="codeContent panelContent">
  

      public List getAvailableItems() {
        List itemValues = Arrays.asList(new String[]{"1 star", "2 stars", "3 stars"});
        return itemValues;
      }
  

          </div>
      </div>
      <p>Another more specific way to specify list of value is using of javax.faces.model.SelectItem:</p>
  
      <div class="code panel" style="border-width: 1px;">
          <div class="codeContent panelContent">
  

  public List<SelectItem> getSelectItemsList() {
    List<SelectItem> selectItemsList = new ArrayList<SelectItem>();
    selectItemsList.add(new SelectItem(2, "Two Stars Hotel"));
    selectItemsList.add(new SelectItem(3, "Three Stars Hotel"));
    selectItemsList.add(new SelectItem(4, "Four Stars Hotel"));
    selectItemsList.add(new SelectItem(5, "Five Stars Hotel"));
    return selectItemsList;
  }
  ...
  <o:selectOneMenu value="#{SelectOneMenuBackingBean.selectedHotelStars}">
    <f:selectItems var="any" value="#{SelectOneMenuBackingBean.selectItemsList}"/>
  </o:selectOneMenu>
  

          </div>
      </div>
      <p>In the example above we will have <cite>SelectOneMenu</cite> with string values in the list, but when we
          select some value it will submit integer value to the server. See JavaServer Faces specification for
          more information about javax.faces.model.SelectItem.</p></li>
  <li>Combine the two aforementioned approaches by specifying the <u>&lt;/f:selectItem&gt;</u> and <u>&lt;f:selectItems&gt;</u>
      tags in any order you need, like in following example:
      <div class="code panel" style="border-width: 1px;">
          <div class="codeContent panelContent">
  

   <f:selectItem value="Any value">
   <f:selectItems value="#{SelectOneMenuBackingBean.availableItems}"/>
  

          </div>
      </div>
      <p>Like any JSF UIInput component, the SelectOneMenu component supports the standard <b>validator</b>, <b>required</b>,
          <b>converter</b>, <b>immediate</b> and <b>disabled</b> attributes. For more information about them, see
          JavaServer Faces specification (section "EditableValueHolder").</p></li>
  

As it was described above, after selecting any item in a list all it's content copied to selected item field. It can cause some problems, when you are using multi column displaying and do not want to copy all columns to selected item field. To solve this issue you can use itemPresentationColumn attribute. You need to specify number of column(default value -1) which will represent your selection in selected item field:

<o:selectOneMenu value="#{SelectOneMenuBackingBean.selectedBGColor}"
var="color">
<f:selectItems value="#{SelectOneMenuBackingBean.colors}"/>
<o:column width="12px">
 <h:outputText styleClass="colorRect" style="background: #{color.name};"/>
 </o:column>
<o:column>
 <h:outputText value="#{color.name}"/>
</o:column>
</o:selectOneMenu>

In this example we use itemPresentationColumn attribute to specify that we want to display only color name value in selected value field. Below you can see results of using tag with itemPresentationColumn attribute and without it

When you are using client side auto suggestion of SelectOneMenu, it's important to remember that filtering will not be applied on outputted values, but it will be applied on the values which actually set to the value attribute of f:selectItem. If you are using non-string value for selectItem, filtering will be applied on toString() method of object or on the getAsString() method of jsf converter if you specified it.

You can fully remove suggestions from component, by setting suggestioMode attribute to none. It also fully remove input field which show on element double click.

Although the SelectOneMenu looks very much like the DropDownField component, they have one key difference besides some API differences described above. The DropDownField component (as well as its cousin SuggestionField) is essentially an input component, like other standard input components such as <h:inputText>. In other words, despite it contains the drop-down list to choose items from, the purpose of the DropDownField component is just the entry of text, and the component's drop-down list as well as the autocompletion functionality just assists the text entry. This particularly means that if for example the drop-down list contains two items with the same name (say London, UK and London, OH), it won't be possible to distinguish between them - the DropDownField will just contain the "London" text when clicking on any of these items and it will be the same as if the user entered this text without even opening the drop-down list.
In contrast, the SelectOneMenu component is a select component, which means that although it allows typing item name in its embedded input field, its purpose is to select from a predefined list of items. So typing "London" (or a partial text) will open a drop-down list for selecting the desired option, and the selected item will be saved in the component and will properly reflect the original item object that corresponds to the selected item.

Features from drop down field which need to be described here.
-Key Features
-Specifying List of Items
-Restricting Input to List Items
-Entering Non-String Values
+Specifying Child Components
+Creating Multi-Column Drop-Down List
+/-Auto-Suggestion
+Partial Loading of Drop-Down List
-Auto-Completion
+Keyboard Navigation
+Auto-Closing Drop-Down List
+Customizing Appearance
+Customizing Styles
+Client-Side Events
+Server-Side Event Listeners
+Client-Side API