public static interface SuggestOracle.Suggestion

Suggestion supplied by the SuggestOracle. Each suggestion has a display string and a replacement string. The display string is what is shown in the SuggestBox's list of suggestions. The interpretation of the display string depends upon the value of its oracle's SuggestOracle.isDisplayStringHTML(). The replacement string is the string that is entered into the SuggestBox's text box when the suggestion is selected from the list.

Replacement strings are useful when the display form of a suggestion differs from the input format for the data. For example, suppose that a company has a webpage with a form which requires the user to enter the e-mail address of an employee. Since users are likely to know the name of the employee, a SuggestBox is used to provide name suggestions as the user types. When the user types the letter f, a suggestion with the display string foo bar appears. When the user chooses this suggestion, the replacement string, [email protected], is entered into the SuggestBox's text box.

This is an example where the input data format for the suggestion is not as user-friendly as the display format. In the event that the display of a suggestion exactly matches the input data format, the Suggestion interface would be implemented in such a way that the display string and replacement string would be identical.

Associating Data Transfer Objects (DTOs) with Suggestion Objects

Some applications retrieve suggesstions from a server, and may want to send back a DTO with each suggestion. In the previous example, a DTO returned with the suggestion may provide additional contact information about the selected employee, and this information could be used to fill out other fields on the form. To send back a DTO with each suggestion, extend the Suggestion interface and define a getter method that has a return value of the DTO's type. Define a class that implements this subinterface and use it to encapsulate each suggestion.

To access a suggestion's DTO when the suggestion is selected, add a ChangeHandler to the SuggestBox (see SuggestBox's documentation for more information). In the SuggestionHandler.onSuggestionSelected(SuggestionEvent event) method, obtain the selected Suggestion object from the ChangeHandler object, and downcast the Suggestion object to the subinterface. Then, acces the DTO using the DTO getter method that was defined on the subinterface.