1. Create implementations of each of the interface classes. Table 13-1 provides a description of the APIs.

   Table 13-1 ListOfValues Model API

   Method	Functionality
   autoCompleteValue()	Called when the search icon is clicked or the value is changed and the user presses the Enter key or either tabs out or clicks out from the input field, as long as autoSubmit is set to true on the component. This method decides whether to open the dialog or to auto-complete the value. The method returns a list of filtered objects.
   valueSelected(value)	Called when the value is selected from the Search and Select dialog and the OK button is clicked. This method gives the model a chance to update the model based on the selected value.
   isAutoCompleteEnabled()	Returns a boolean to decide whether or not the auto complete is enabled.
   getTableModel()	Returns the implementation of the TableModel class, on which the table in the search and select dialog will be based and created.
   getItems() and getRecentItems()	Return the items and recentItems lists to be displayed in the combobox dropdown. Valid only for the inputComboboxListOfValues component. Returns null for the inputListOfValues component.
   getItemDescriptors()	Return the list of columnDescriptors to be displayed in the dropdown list for an inputComboboxListOfValues component.
   getQueryModel() and getQueryDescriptor()	Return the queryModel based on which the query component inside the Search and Select dialog is created.
   performQuery()	Called when the search button in the query component is clicked.
   setCriterionValue(Object value)	Sets the value of the criterion that matches the LOV's display attribute in the advanced search panel. Default implementation does nothing. Object Value is the submittedValue of the component..

   For an example of a ListOfValues model, see the DemoLOVBean and DemoComboboxLOVBean classes located in the oracle.adfdemo.view.lov package, found in the Application Sources directory of the ADF Faces application.

2. For the inputListOfValues component, provide logic in a managed bean (it can be the same managed bean used to create your LOV model) that accesses the attribute used to populate the list. The inputComboboxListOfValues component uses the getItems() and getRecentItems() methods to return the list.
3. For the Search and Select popup dialog used in the InputListOfValues component, or if you want the InputComboboxListOfValues component to use the Search and Select popup dialog, implement the ListOfValuesModel.autoCompleteValue() and ListOfValuesModel.valueSelected() methods. These methods open the popup dialog and apply the selected values onto the component.

1. In the Components window, from the Text and Selection panel, drag an Input List Of Values and drop it onto the page.
2. In the Properties window, expand the Common section and set the following attributes:

   • model: Enter an EL expression that resolves to your ListOfValuesModel implementation, as created in How to Create the ListOfValues Data Model.

   • value: Enter an EL expression that resolves to the attribute values used to populate the list, as created in How to Create the ListOfValues Data Model.

3. Expand the Appearance section and set the following attribute values:

   • popupTitle: Specify the title of the Search and Select popup dialog.

   • searchDesc: Enter text to display as a mouseover tip for the component.

   • Placeholder: Specify the text that appears in the inputListOfValues component if the component is empty and does not have focus. When the component gets focus, or has a value, then the placeholder text is hidden.

     The placeholder text is used to inform the user what should be entered in the inputListOfValues component.

     Note:

     The placeholder value will only work on browsers that fully support HTML5.

   The rest of the attributes in this section can be populated in the same manner as with any other input component. See Using the inputText Component.

4. Expand the Behavior section and set the following attribute values:

   • autoSubmit: Set to true if you want the component to automatically submit the enclosing form when an appropriate action takes place (a click, text change, and so on). This will allow the auto-complete feature to work.

   • createPopupId: If you have implemented a popup dialog used to create a new object in the list, specify the ID of that popup component. Doing so will display a toolbar component above the table that contains a button component bound to the popup dialog you defined. If you have added a dialog to the popup, then it will intelligently decide when to refresh the table. If you have not added a dialog to the popup, then the table will be always refreshed.

   • launchPopupListener: Enter an EL expression that resolves to a launchPopupListener that you implement to provide additional functionality when the popup is launched.

   • returnPopupListener: Enter an EL expression that resolves to a returnPopupListener component that you implement to provide additional functionality when the value is returned.

   • Usage: Specify how the inputListOfValues component will be rendered in HTML 5 browser. The valid values are auto, text, and search. Default is auto.

     If the usage type is search, the inputListOfValues component will render as an HTML 5 search input type. Some HTML 5 browsers may add a Cancel icon that can be used to clear the search text.

   The rest of the attributes in this section can be populated in the same manner as with any other input component. See Using the inputText Component.

5. If you want users to be able to create a new item, create a popup dialog with the ID given in Step 4. See Using Popup Dialogs, Menus, and Windows.
6. In the Components window, from the Operations panel, in the Behavior group, drag an Auto Suggest Behavior and drop it as a child to the inputListOfValues component.

   If you add auto suggest behavior, you must not set the immediate property to true. Setting immediate to true will cause validation to occur in the Apply Request Values phase and any validation errors may suppress the displaying of the suggestion list.

7. In the Properties window, for each of the auto-suggest attributes, enter the:

   • EL expression that resolves to the suggestItems method.

     The method should return List<javax.model.SelectItem> of the suggestItems. The method signature should be of the form List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext, oracle.adf.view.rich.model.AutoSuggestUIHints)

   • EL expression that resolves to the smartList method. The method should return List<javax.model.SelectItem> of the smart list items.

   • You can modify the behavior of af:autoSuggestBehavior to start to show the suggest items only when a user enters more than N characters. For example, if minimumChar="3", then the suggest list gets displayed only when you enter 3 or more characters.

   • Number of items to be displayed in the auto-suggest list. Enter -1 to display the complete list.

   If you are implementing this method in a managed bean, the JSF page entry should have the format shown in the following example

   <af:inputListOfValues value="#{bean.value}" id="inputId">
       ...
       <af:autoSuggestBehavior 
             suggestItems="#{bean.suggestItems}"
             smartList="#{bean.smartList}"
             minimumChar="3"
             maxSuggestedItems="7"/>
   </af:inputListOfValues>
   
   
   <af:inputListOfValues value="#{bean.value}" id="inputId">

   If the component is being used with a data model such as ADF Model, the suggestItem method should be provided by the default implementation.

8. If you are not using ADF Model, create the suggestItems method to process and display the list. The suggestItems method signature is shown in the following example.

   List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext,
       oracle.adf.view.rich.model.AutoSuggestUIHints) 

When you create an LOV dynamically using af:query, you cannot add AutoSuggestBehavior to the dynamically created LOV component. To achieve this, you need to first create the auto suggest behavior dynamically, configure it, and then add the dynamically created auto suggest behavior to the LOV component that is dynamically created. You can use the af:query component to create the behavior and to attach it to the dynamically created LOV component.

To create an auto suggest behavior, use the AutoSuggestBehaviorTag behaviorTag = new AutoSuggestBehaviorTag() in the af:query component.

To configure the properties of the dynamically created auto suggest behavior, use the AutoSuggestBehaviorConfig abstract class, which provides an instance that has all the configurations of AutoSuggestBehavior. The AttributeDescriptor API of af:query has a getAutoSuggestBehaviorConfig method that has the AutoSuggestBehavior properties. The query component invokes the AttributeDescriptor API to read the properties and set it on the AutoSuggestBehaviorTag instance that you created. To get the properties from AutoSuggestBehavior, use the following code:

AutoSuggestBehaviorConfig config = attribeDescriptorInstance.getAutoSuggestBehaviorConfig();
behaviorTag.setMinChars(config.getMinChars());
behaviorTag.setSuggestItems(config.getSuggestItems());

To add the dynamically created behavior to the LOV component, use the following code:

FacesBean bean = component.getFacesBean();
PropertyKey key = bean.getType().findKey("clientListeners");
ClientListenerSet cls = (ClientListenerSet) bean.getProperty(key);
if (cls == null)
  cls = new ClientListenerSet();
behaviorTag.updateClientListenerSet(component, cls);

By default, the search and select dialogs that the InputComboboxListOfValues and InputListOfValues components can be resized by end users when they render. You can disable the end user's ability to resize these dialogs by setting the value of the -tr-stretch-search-dialog selector key to false in your application's skin file, as shown in the following example. The default value of the -tr-stretch-search-dialog selector key is true. For more information about skinning, see the skinning chapter.

af|inputComboboxListOfValues{
  -tr-stretch-search-dialog: false;
}
af|inputListOfValues{
  -tr-stretch-search-dialog: false;
}

1. In the Components window, from the Text and Selection panel, drag an Input Combobox List Of Values and drop it onto the page.
2. In the Properties window, expand the Common section and set the following attributes:

   • model: Enter an EL expression that resolves to your ListOfValuesModel implementation, as created in How to Create the ListOfValues Data Model.

   • value: Enter an EL expression that resolves to the attribute values used to populate the list, as created in How to Create the ListOfValues Data Model.

3. Expand the Appearance section and set the following attribute values:

   • popupTitle: Specify the title of the Search and Select popup dialog.

   • searchDesc: Enter text to display as a mouseover tip for the component.

   • Placeholder: Specify the text that appears in the inputComboboxListOfValues component if the component is empty and does not have focus. When the component gets focus, or has a value, then the placeholder text is hidden.

     The placeholder text is used to inform the user what should be entered in the inputComboboxListOfValues component.

     Note:

     The placeholder value will only work on browsers that fully support HTML5.

   The rest of the attributes in this section can be populated in the same manner as with any other input component. See Using the inputText Component.

4. Expand the Behavior section and set the following attribute values:

   • autoSubmit: Set to true if you want the component to automatically submit the enclosing form when an appropriate action takes place (a click, text change, and so on). This will allow the auto complete feature to work.

   • createPopupId: If you have implemented a popup dialog used to create a new object in the list, specify the ID of that popup component. Doing so will display a toolbar component above the table that contains a button component bound to the dialog you defined. If you have added a dialog to the popup, then it will intelligently decide when to refresh the table. If you have not added a dialog to the popup, then the table will always be refreshed.

   • launchPopupListener: Enter an EL expression that resolves to a launchPopupListener handler that you implement to provide additional functionality when the popup dialog is opened.

   • returnPopupListener: Enter an EL expression that resolves to a returnPopupListener handler that you implement to provide additional functionality when the value is returned.

   • Usage: Specify how the inputComboboxListOfValues component will be rendered in HTML 5 browser. The valid values are auto, text, and search. Default is auto.

     If the usage type is search, the inputComboboxListOfValues component will render as an HTML 5 search input type. Some HTML 5 browsers may add a Cancel icon that can be used to clear the search text.

   The rest of the attributes in this section can be populated in the same manner as with any other input component. See Using the inputText Component.

5. If you want to control when the contents of the dropdown are delivered, expand the Advanced section, and set the contentDelivery attribute to one of the following:

   • immediate: All undisclosed content is sent when the dropdown list is disclosed. The LaunchPopupEvent will not be queued.

   • lazy: The undisclosed content is sent only when the content is first disclosed. Once disclosed and the content is rendered, it remains in memory. The LaunchPopupEvent will be queued only the first time the dropdown displays.

   • lazyUncached: The undisclosed content is created every time it is disclosed. If the content is subsequently hidden, it is destroyed. The LaunchPopupEvent will be queued while displaying the dropdown panel. This is the default.

6. If you are using a launchPopupListener, you can use the getPopupType() method of the LaunchPopupEvent class to differentiate the source of the event. getPopupType() returns DROPDOWN_LIST if the event is a result of the launch of the LOV Search and Select dialog, and SEARCH_DIALOG if the event is the result of the user clicking the Search button in the dialog.
7. If you want users to be able to create a new item, create a popup dialog with the ID given in Step 5. See Using Popup Dialogs, Menus, and Windows.
8. In the Components window, from the Operations panel, in the Behavior group, drag an Auto Suggest Behavior and drop it as child to the inputComboboxListOfValues component.

   If you add auto suggest behavior, you must not set the immediate property to true. Setting immediate to true will cause validation to occur in the Apply Request Values phase and any validation errors may suppress the displaying of the suggestion list.

9. In the Properties window, for each of the auto-suggest attributes, enter the:

   • EL expression that resolves to the suggestItems method.

     The method should return List<javax.model.SelectItem> of the suggestItems. The method signature should be of the form List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext, oracle.adf.view.rich.model.AutoSuggestUIHints)

   • EL expression that resolves to the smartList method. The method should return List<javax.model.SelectItem> of the smart list items.

   • Number of items to be displayed in the auto-suggest list. Enter -1 to display the complete list.

   If you are implementing this method in a managed bean, the JSF page entry should have the format shown in the following example.

   <af:inputComboboxListOfValues value="#{bean.value}" id="inputId">
       ...
       <af:autoSuggestBehavior 
             suggestItems="#{bean.suggestItems}"
             smartList="#{bean.smartList}"
             maxSuggestedItems="7"/>
   </af:inputComboboxListOfValues>
   

   If the component is being used with a data model such as ADF Model, the suggestItem method should be provided by the default implementation.

10. If you are not using the component with ADF Model, create the suggestItems method to process and display the list:

    List<javax.model.SelectItem> suggestItems(javax.faces.context.FacesContext,
        oracle.adf.view.rich.model.AutoSuggestUIHints) 
    

You can customize the filtering and display of suggestions by including attributes in inputSearch source code. Table 13-2 provides the list of attributes that you can use in the inputSearch component.

The af:searchSection component is basically used to specify the REST endpoint URL. The af:searchSection supports other attributes that you can use to customize the search section, such as search type, search id and so on. The following example shows the code sample of af:searchSection:

<af:inputSearch label="Label" valueAttribute="id">
	<af:searchSection type="default" 
		dataUrl="/rest/employees" />
</af:inputSearch>

Table 13-3 lists the attributes that you can use in the af:searchSection.

You can customize the display of suggestions on the client by using the client template feature supported by the inputSearch component. The rendering of the component and submission of value happens through the JSF lifecycle. The template system supported by the component is called Mustache, a web template system that may be embedded into HTML and relies on a template engine to expand the template at runtime. See Mustache Manual. You can include the value from the REST response as Mustache tags within the af:sanitized tag of jspx page. You can use the contentStamp and contentHeader facets in the .jspx page source code to provide the template. Mustache tags are evaluated for each suggestion object and the expanded template is rendered as a suggestion item in the suggestions panel.

Basically, the property names in the JavaScript suggestion object are to be referenced as mustache tags in the template. The component would evaluate the template replacing the mustache tags with the values in the suggestion object. Depending on the contentMode attribute, the component evaluates the mustache expressions and dumps it as is in the HTML either inside a <li> tag or a <tr> tag to display the suggestion items.

The following example shows the sample code for tabular display without any header, followed by the sample template as shown in Figure 13-12.

<af:inputSearch contentMode="table" ... >
	...
	<f:facet name="contentStamp">
     <af:sanitized >
        <td>{{fName}} {{lName}}</td>
        <td>{{jobTitle}}</td>
        <td>{{email}}</td> 
        <td><span style="font-style: italic;">{{tags}}</span></td>
     </af:sanitized>
	</f:facet>
</af:inputSearch>

Figure 13-12 Sample Tabular Display

Description of "Figure 13-12 Sample Tabular Display"

The following example shows the sample code for tabular display with contentHeader, followed by the sample template as shown in Figure 13-13.

<af:inputSearch contentMode="table" ... >
  ...
	<f:facet name="contentHeader">
     <af:sanitized >
       <th>Name</th> 
       <th>Title</th> 
       <th>Contact Email</th> 
       <th><span style="font-style: italic;">Specializations</span></th>
    </af:sanitized>
  </f:facet>
  <f:facet name="contentStamp">
    <af:sanitized >
       <td>{{fName}} {{lName}}</td> 
       <td>{{jobTitle}}</td> 
       <td>{{email}}</td> 
       <td><span style="font-style: italic;">{{tags}}</span></td>
    </af:sanitized>
  </f:facet>
</af:inputSearch>

Figure 13-13 Sample Tabular Display with Header Row

Description of "Figure 13-13 Sample Tabular Display with Header Row"

The following example shows the sample code for list display, followed by the sample template as shown in Figure 13-14.

<af:inputSearch ... >
	...
	<f:facet name="contentStamp">
     <af:sanitized >
        <span style="font-size:1.2em">{{fName}} {{lName}}</span> &nbsp; 
        <span style="font-size:0.9em; padding-left: 8px">{{jobTitle}}</span>
        <br/>
        <b>Tags: </b><span style="font-style: italic;">{{tags}}</span>
     </af:sanitized>
	</f:facet>
</af:inputSearch>

Figure 13-14 Sample List Display

Description of "Figure 13-14 Sample List Display"

The following example shows the sample code for advanced list template, followed by the sample template as shown in Figure 13-15.

<af:inputSearch ... >
  ...
  <f:facet name="contentStamp">
    <af:sanitized>
        <div style="height: 68px; line-height: 18px; white-space: nowrap">
        <div style="padding: 0px; margin: 0px; width: 64px; display: inline-block;">
        <img src="../../images/people/{{profileKey}}" height="56" width="56" 
        style="vertical-align: bottom; border: 2px solid #B8AE07; padding: 2px; border-radius: 10px;"/>
        </div>
        <div style="padding-left: 10px; display: inline-block;">
        <div style="color: #4646D0;font-size: medium;">{{fName}} {{lName}}</div>
        <div>{{jobTitle}}</div>
        <div style="font-size: smaller;font-style: italic;">{{email}}</div>
        </div>
      </div>
    </af:sanitized>
  </f:facet>
</af:inputSearch>

Figure 13-15 Sample Advanced List Display

Description of "Figure 13-15 Sample Advanced List Display"

The inputSearch component includes a facet toolbar that renders a section in the suggestions panel, which you can use to place custom controls such as tool bar items of your choice. Figure 13-16 displays the suggestion panel.

Figure 13-16 Suggestions Panel Displaying the Toolbar Facet

The following example shows the sample code for including the toolbar facet.

 <af:searchSection type="default" dataUrl="#{inputSearchDemo.dataUrl}" partialTriggers="ctb3" />
           <f:facet name="toolbar">
             <af:toolbar id="pgl14">
               <af:group id="g1">
                 <af:commandToolbarButton shortDesc="Create" icon="/images/new_ena.png" id="ctb1">
                   <af:showPopupBehavior popupId="createpopup"/>
                 </af:commandToolbarButton>
                 <af:commandToolbarButton icon="/images/update_ena.png" shortDesc="Update the searchSection URL on client" id="ctb2">
                   <af:clientListener type="action" method="updateSuggestionCount" />
                 </af:commandToolbarButton>
                 <af:commandToolbarButton icon="/images/uplevel.gif" actionListener="#{inputSearchDemo.updateDataUrl}"
                     shortDesc="Update the searchSection URL on server" id="ctb3"/>
               </af:group>
               <af:group id="g2">
                 <af:commandToolbarButton shortDesc="E-mail" icon="/images/email.gif" id="ctb4"/>
                 <af:commandToolbarButton shortDesc="Snapshot" icon="/images/snapshot.gif" id="ctb5"/>
               </af:group>
             </af:toolbar>
           </f:facet>

The suggestionSection component creates and manages the most recently used (MRU) suggestion lists based on the frequency and recentness of the suggestions used. The preferred list of suggestion items is stored in the browser’s storage object. The suggestionSection component manages a list of preferred suggestions and gets displayed based on the various factors on the client:

• The parent inputSearch component retrieves the list managed by the suggestionSection and displays the list in the UI.

• The inputSearch component might not display the preferred suggestion list managed by af:suggestionSection, if the master list is small.

• The length of the master list is determined the first time the suggestion popup is launched. Therefore, if you launch the suggestion popup without much suggestions the first time, the inputSearch will still display the preferred suggestion list even if the length of the suggestion list is small.

• The list managed by the suggestionSection component is a subset of the suggestions retrieved via the REST service.

The following example shows the suggestionSection tag within theinputSearch component:

<af:inputSearch label="Label" valueAttribute="id" ...>
   <af:searchSection type="default" dataUrl="/rest/employees" />
   <af:suggestionsSection />
</af:inputSearch>

By default, af:suggestionsSection based list is shared across inputSearch components which are based on same REST URL. You can use the following attributes in the suggestionSection to customize the sharing and display of suggestion list.

• cacheKeyGenerator Use this attribute to keep the suggestion list as private per component or to remove the cache search parameter from the URL to be used as localStorage key. Setting this attribute manages a list of suggestions completely on the client.

  <af:inputSearch ...>
  ...
    <af:suggestionsSection cacheKeyGenerator="ignoreCacheAttr"/"privateList" />
  </af:inputSearch>

• displayCount Use this attribute to customize the number of items that are to be displayed in the preferred list.

  <af:inputSearch ...>
  ...
  	<af:suggestionsSection displayCount="15" />
  </af:inputSearch>

• dontCache Use this attribute to not to store the specified fields in the browser’s localStorage for the REST data.

  <af:inputSearch ...>
  ...
  	<af:suggestionsSection dontCache="lName jobTitle" />
  </af:inputSearch>

  In this code sample, the lName and jobTitle attributes from the suggestion items retrieved from the REST call will not be stored in the localStorage.

See What You May Need to Know About suggestionSection Attributes for other attributes that you can use with suggestionSection tag.

You can further customize the suggestion list by including a header facet. The suggestionSection supports only header facet that allows the child components within af:sanitized. The following example shows the sample code for the header facet that includes Recent Items as header in the suggestion list.

<af:inputSearch id="iSearch4"
          label="Select a person from the list (Filter by name and job title): "
          valueAttribute="id"
          displayAttributes="fName lName"
          filterAttributes="fName lName jobTitle"
          selectionConverter="#{inputSearchDemo.selectionConverter}">
  <af:searchSection type="default" dataUrl="/rest/employees?cache=etag&amp;limit=5000" />
  <af:suggestionsSection>
    <f:facet name="header">
      <af:sanitized>
        <b>Recent Items</b> <!-- The "Recent Items" text in the screenshot below is because of this line -->
      </af:sanitized>
    </f:facet>
  </af:suggestionsSection>
</af:inputSearch>

Figure 13-17 shows the output for the above code.

Figure 13-17 Output of the header Facet in suggestionSection

Description of "Figure 13-17 Output of the header Facet in suggestionSection"

Table 13-4 lists the attributes that you can use in the af:suggestionSection.

 function privateList(normalizedUrl)
{ // "this" refers to parent inputSearch component return this.getClientId(); }

When you use filterAttributes in the inputSearch component the REST response data is filtered and the values are displayed in the suggestions popup. The inputSearch component further supports dependency-based filtering on clientside. To further filter the suggestion list on the clientside, you can use the filter attribute that holds the name of the JavaScript callback that would perform Array.filter operation on the collection returned from the REST response. The component instance will be set as context during JavaScript callback invocation.

The row object passed to the callback will have the structure below:

• data: The raw row data

• index: The index for the row

• key: The key value for the row

The following example shows the sample code snippet for dependency based filtering that lists the Employee suggestion list based on the Department value, followed by the sample template as shown in Figure 13-18.

<af:inputSearch label="Employee" filter="filterEmpForDept" ...>
  <af:searchSection type="default" dataUrl="/rest/employees" />
</af:inputSearch>

Sample JS:

var filterValue;
var filterKey = "deptName";
function filterEmpForDept(rowObj, collectionIndex)
{
  // var component = this;
  if (collectionIndex == 0)
  {
    // get the filterValue once for the zeroth row
    // and use the same for subsequent row filtering
    var parentComp = AdfPage.PAGE.findComponent
    ('parent component id whose value will determine the suggestions to be displayed in inputSearch')
    var parentCompValue = parentComp.getValue();
    filterValue = parentCompValue ? parentComp.getSelectItems()[parentComp.getValue()].getLabel() : null;
  }

  if (filterValue &amp;&amp; rowObj.data[filterKey] == filterValue)
    return true;
  return false;
}

Figure 13-18 shows different Employee suggestion list based on the Department value.

Figure 13-18 Dependency-Based Filtering in inputSearch Component

Description of "Figure 13-18 Dependency-Based Filtering in inputSearch Component"