Search​Suggestion​Collection Search​Suggestion​Collection Search​Suggestion​Collection Search​Suggestion​Collection Class

Definition

Represents a collection of search suggestions to be displayed in the search pane in response to a suggestionsrequested event.

public : sealed class SearchSuggestionCollection : ISearchSuggestionCollectionpublic sealed class SearchSuggestionCollection : ISearchSuggestionCollectionPublic NotInheritable Class SearchSuggestionCollection Implements ISearchSuggestionCollection// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

The Search contract sample demonstrates how to respond to a suggestionsrequested event, including how to use the searchSuggestionCollection.

private void OnSearchPaneSuggestionsRequested(SearchPane sender, SearchPaneSuggestionsRequestedEventArgs e)
{
    var queryText = e.QueryText;
    if (string.IsNullOrEmpty(queryText))
    {
        MainPage.Current.NotifyUser("Use the search pane to submit a query", NotifyType.StatusMessage);
    }
    else
    {
        var request = e.Request;
        var linguisticDetails = e.LinguisticDetails;
        foreach (string alternative in linguisticDetails.QueryTextAlternatives)
        {
            foreach (string suggestion in suggestionList)
            {
                if (suggestion.StartsWith(alternative, StringComparison.CurrentCultureIgnoreCase))
                {
                    // Add suggestion to Search Pane
                    request.SearchSuggestionCollection.AppendQuerySuggestion(suggestion);

                    // Break since the Search Pane can show at most 5 suggestions
                    if (request.SearchSuggestionCollection.Size >= MainPage.SearchPaneMaxSuggestions)
                    {
                        break;
                    }
                }
            }

            // Break since the Search Pane can show at most 5 suggestions
            if (request.SearchSuggestionCollection.Size >= MainPage.SearchPaneMaxSuggestions)
            {
                break;
            }
        }

        if (request.SearchSuggestionCollection.Size > 0)
        {
            MainPage.Current.NotifyUser("Suggestions provided for query: " + queryText, NotifyType.StatusMessage);
        }
        else
        {
            MainPage.Current.NotifyUser("No suggestions provided for query: " + queryText, NotifyType.StatusMessage);
        }
    }
}
// Register the onsuggestionsrequested event in your apps global scope, for example default.js, so that it is registered as soon as your app is launched.
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onsuggestionsrequested = function (eventObject) {
    var queryText = eventObject.queryText, suggestionRequest = eventObject.request, linguisticDetails = eventObject.linguisticDetails;

    var queryAlternatives = linguisticDetails.queryTextAlternatives;
    var maxNumberOfSuggestions = 5;
    for (var i = 0, len = queryAlternatives.length, done = false; i < len && !done; i++) {
        // toLowerCase not necessary for East Asian languages. Preserves compatibility when non East Asian suggestions are mixed in with East Asian suggestions.
        var alternative = queryAlternatives[i].toLowerCase();
        for (var j = 0, suggestionLength = suggestionList.length; j < suggestionLength; j++) {
            if (suggestionList[j].substr(0, alternative.length).toLowerCase() === alternative) {
                suggestionRequest.searchSuggestionCollection.appendQuerySuggestion(suggestionList[j]);
                if (suggestionRequest.searchSuggestionCollection.size === maxNumberOfSuggestions) {
                    done = true;
                    break;
                }
            }
        }
    }

    // Construct list of alternatives so we can output them.
    var alternatives = "";
    for (var k = 0, alternativeCount = queryAlternatives.length; k < alternativeCount; k++) {
        alternatives += queryAlternatives[k];
    }
    if (suggestionRequest.searchSuggestionCollection.size > 0) {
        WinJS.log && WinJS.log("Suggestions provided for query: " + queryText + "\nUsing alternatives: " + alternatives, "sample", "status");
    } else {
        WinJS.log && WinJS.log("No suggestions provided for query: " + queryText + "\nUsing alternatives: " + alternatives, "sample", "status");
    }
};

Remarks

The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

An app retrieves this object through the searchPaneSuggestionsRequest.searchSuggestionCollection property while handling a suggestionsrequested event.

Properties

Size Size Size Size

The number of suggestions in the collection.

public : unsigned short Size { get; }public uint Size { get; }Public ReadOnly Property Size As uint// You can use this property in JavaScript.
Value
unsigned short uint uint uint

The number of suggestions.

Remarks

The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

See Also

Methods

AppendQuerySuggestion(String) AppendQuerySuggestion(String) AppendQuerySuggestion(String) AppendQuerySuggestion(String)

Appends a query suggestion to the list of search suggestions for the search pane.

public : void AppendQuerySuggestion(PlatForm::String text)public void AppendQuerySuggestion(String text)Public Function AppendQuerySuggestion(text As String) As void// You can use this method in JavaScript.
Parameters
text
PlatForm::String String String String

The text of the query suggestion.

Remarks

A query suggestion is a suggestion that the user can select as his or her query.

The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

See Also

AppendQuerySuggestions(IIterable<String>) AppendQuerySuggestions(IIterable<String>) AppendQuerySuggestions(IIterable<String>) AppendQuerySuggestions(IIterable<String>)

Appends a list of query suggestions to the list of search suggestions for the search pane.

public : void AppendQuerySuggestions(IIterable<PlatForm::String> suggestions)public void AppendQuerySuggestions(IEnumerable<String> suggestions)Public Function AppendQuerySuggestions(suggestions As IEnumerable<String>) As void// You can use this method in JavaScript.
Parameters
suggestions
IIterable<PlatForm::String> IEnumerable<String> IEnumerable<String> IEnumerable<String>

The list of query suggestions.

Remarks

A query suggestion is a suggestion that the user can select as his or her query.

The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

See Also

AppendResultSuggestion(String, String, String, IRandomAccessStreamReference, String) AppendResultSuggestion(String, String, String, IRandomAccessStreamReference, String) AppendResultSuggestion(String, String, String, IRandomAccessStreamReference, String) AppendResultSuggestion(String, String, String, IRandomAccessStreamReference, String)

Appends a suggested search result to the list of suggestions to display in the search pane.

public : void AppendResultSuggestion(PlatForm::String text, PlatForm::String detailText, PlatForm::String tag, IRandomAccessStreamReference image, PlatForm::String imageAlternateText)public void AppendResultSuggestion(String text, String detailText, String tag, IRandomAccessStreamReference image, String imageAlternateText)Public Function AppendResultSuggestion(text As String, detailText As String, tag As String, image As IRandomAccessStreamReference, imageAlternateText As String) As void// You can use this method in JavaScript.
Parameters
text
PlatForm::String String String String

The text of the suggested result.

detailText
PlatForm::String String String String

The detail text for the suggested result.

tag
PlatForm::String String String String

The unique tag that identifies this suggested result.

If this suggested result is selected by the user, a resultsuggestionchosen event is fired. When the app handles this event, it can get the tag of the chosen result suggestion from the searchPaneResultSuggestionChosenEventArgs.tag property.

image
IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference IRandomAccessStreamReference

The image to accompany the results suggestion. The image should be 40 x 40. Windows will scale or crop smaller or larger images.

imageAlternateText
PlatForm::String String String String

The alternate text for the image.

Remarks

You should use result suggestions instead of query suggestions only to display high-confidence results that take the user directly to the item instead of to a view that shows search results.

Suggested results include an image and optional detail text to display with the suggestion in the search pane. The image signals to the user that they are seeing results and not query suggestions. If an image for the result doesn't exist, you can use a generic image or icon that represents the result or result type.

You must listen for and handle the resultsuggestionchosen event if you want to provide result suggestions.

The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

See Also

AppendSearchSeparator(String) AppendSearchSeparator(String) AppendSearchSeparator(String) AppendSearchSeparator(String)

Appends a text label that is used to separate groups of suggestions in the search pane.

public : void AppendSearchSeparator(PlatForm::String label)public void AppendSearchSeparator(String label)Public Function AppendSearchSeparator(label As String) As void// You can use this method in JavaScript.
Parameters
label
PlatForm::String String String String

The text to use as a separator. This text should be descriptive of any suggestions that are appended after it.

Remarks

The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and decreases the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

See Also

See Also