SearchPaneSuggestionsRequest SearchPaneSuggestionsRequest SearchPaneSuggestionsRequest SearchPaneSuggestionsRequest Class

Definition

Stores suggestions and information about the request for suggestions.

public : sealed class SearchPaneSuggestionsRequest : ISearchPaneSuggestionsRequestpublic sealed class SearchPaneSuggestionsRequest : ISearchPaneSuggestionsRequestPublic NotInheritable Class SearchPaneSuggestionsRequest Implements ISearchPaneSuggestionsRequest// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows Desktop Extension SDK (introduced v10.0.10240.0) Xbox One Extensions for the UWP (introduced v10.0.10586.0)
API contract
Windows.ApplicationModel.Search.SearchContract (introduced v1)

Examples

The Search contract sample demonstrates how to respond to a suggestionsrequested event, including how to access the searchPaneSuggestionsRequest.

private async 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 if (string.IsNullOrEmpty(UrlTextBox.Text))
    {
        MainPage.Current.NotifyUser("Please enter the web service URL", NotifyType.StatusMessage);
    }
    else
    {
        // The deferral object is used to supply suggestions asynchronously for example when fetching suggestions from a web service.
        var request = e.Request;
        var deferral = request.GetDeferral();

        try
        {
            // Use the web service Url entered in the UrlTextBox that supports XML Search Suggestions in order to see suggestions come from the web service.
            // See http://msdn.microsoft.com/en-us/library/cc848863(v=vs.85).aspx for details on XML Search Suggestions format.
            // Replace "{searchTerms}" of the Url with the query string.
            Task task = GetSuggestionsAsync(Regex.Replace(UrlTextBox.Text, "{searchTerms}", Uri.EscapeDataString(queryText)), request.SearchSuggestionCollection);
            await task;
            if (task.Status == TaskStatus.RanToCompletion)
            {
                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);
                }
            }
        }
        catch (TaskCanceledException)
        {
            // Previous suggestion request was canceled.
        }
        catch (FormatException)
        {
            MainPage.Current.NotifyUser("Suggestions could not be retrieved, please verify that the URL points to a valid service (for example http://contoso.com?q={searchTerms})", NotifyType.ErrorMessage);
        }
        catch (Exception)
        {
            MainPage.Current.NotifyUser("Suggestions could not be displayed, please verify that the service provides valid XML Search Suggestions.", NotifyType.ErrorMessage);
        }
        finally
        {
            deferral.Complete();
        }
    }
}
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onsuggestionsrequested = function (eventObject) {
    var queryText = eventObject.queryText, language = eventObject.language, suggestionRequest = eventObject.request;

    // The deferral object is used to supply suggestions asynchronously for example when fetching suggestions from a web service.
    // Indicate that we'll do this asynchronously:
    var deferral = suggestionRequest.getDeferral();

    // Use the web service Uri entered in the urlInput that supports this standard in order to see suggestions come from the web service.
    // See http://msdn.microsoft.com/en-us/library/cc848863(v=vs.85).aspx for details on XML Search Suggestions format.
    // And replace "{searchTerms}" with the query string, which should be encoded into the URI.
    var suggestionUri = document.getElementById("urlInput").innerText.replace("{searchTerms}", encodeURIComponent(queryText));

    // Cancel the previous suggestion request if it is not finished.
    if (xhrRequest && xhrRequest.cancel) {
        xhrRequest.cancel();
    }

    // Create request to obtain suggestions from service and supply them to the Search Pane.
    xhrRequest = WinJS.xhr({ url: suggestionUri });
    xhrRequest.done(
        function (request) {
            if (request.responseXML) {
                generateSuggestions(request.responseXML, suggestionRequest.searchSuggestionCollection, queryText);
            }

            deferral.complete(); // Indicate we're done supplying suggestions.
        },
        function (error) {
            WinJS.log && WinJS.log("Error retrieving suggestions for query: " + queryText, "sample", "status");

            // Call complete on the deferral when there is an error.
            deferral.complete();
        });
};

Remarks

If your app provides its own suggestions to display in the search pane, use the searchPaneSuggestionsRequest.searchSuggestionCollection property to add your app's suggestions to the collection of suggestions to display.

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.

Properties

IsCanceled IsCanceled IsCanceled IsCanceled

Indicates whether the request for suggestions to display is canceled.

public : PlatForm::Boolean IsCanceled { get; }public bool IsCanceled { get; }Public ReadOnly Property IsCanceled As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

True if the request was canceled, otherwise false. The default value is false.

Remarks

A request for search pane suggestions is valid if it is still tied to the most recent suggestionsrequested event; that is, if the user has not changed the search query.

See Also

SearchSuggestionCollection SearchSuggestionCollection SearchSuggestionCollection SearchSuggestionCollection

The suggestions to display in the search pane for the current query. Apps provide suggestions to display by appending them to this searchSuggestionCollection object.

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

The suggestions to display. Apps provide suggestions by appending them to this searchSuggestionCollection object.

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.

Use the SearchSuggestionCollection object to append app-provided suggestions and search separators to display in the search pane.

When the request for suggestions is completed, either by returning from the suggestionsrequested event handler or by calling searchPaneSuggestionsRequestDeferral.complete, the search pane displays the suggestions in the searchSuggestionCollection.

See Also

Methods

GetDeferral() GetDeferral() GetDeferral() GetDeferral()

Retrieves an object that lets an app respond to a request for suggestions asynchronously.

public : SearchPaneSuggestionsRequestDeferral GetDeferral()public SearchPaneSuggestionsRequestDeferral GetDeferral()Public Function GetDeferral() As SearchPaneSuggestionsRequestDeferral// You can use this method in JavaScript.
Returns

An object that lets an app signal when it has fulfilled the request for search suggestions.

Remarks

Your app should respond asynchronously to a request for search suggestions if fulfilling the request will take a significant amount of time, such as fetching suggestions from a web service.

Use the searchPaneSuggestionsRequestDeferral.complete method to signal when your app has fulfilled the request.

See Also

See Also