SDK Query Hooks

SDK Query Hooks are React Hooks that allow a developer to connect through the Sitecore Search API. Additionally, each type of widget will have a corresponding hook. For example, a SearchResults type widget will have a useSearchResults hook. Using the hook, we can get valuable information about the widget behavior:

• WidgetRef: Node widget reference. The user has to explicitly reference which node has to be monitored by the SDK. Once the referenced node appears in the browser's viewport the SDK will automatically trigger the widget appear event.
• Actions:. Available operations that the widget can execute. For example, apply a filter or change the number of results that we would like to show.
• State: Get the parameters applied to a request.
• Results: Get the results from the API and the request status

On the other hand, the hook will also allow us to set the query parameters to configure our widget behavior.

Anatomy

const {
    widgetRef,
    actions: {
        // Here we destructure the actions that we would like to use.
    },
    state: {
        // Here we destructure the state variables that we would like to obtain.
    },
    queryResult: {
        isLoading, // The query has no data and is currently fetching
        isError, // The query encountered an error
        isSuccess, // The query was successful and data is available
        isFetching, // In any state, if the query is fetching at any time (including background refetching) isFetching will be true.
        data: {
            // Here we destructure the API response properties.
        } = {},
    },
} = [useSearchResults|useRecommendation|usePreviewSearch]({
      query: (query) => query.getRequest().setOffset(10),
      state: {
            keyphrase: 'red',
      }
});

return (
    <div ref={widgetRef}>
        // Logic here.
    </div>
);
Copy

Interface

Note that in all cases we have an object with 2 parameters, one named query which is a function that executes once the component (template) loads and state used to initialize some properties on the request.

useSearchResults({
        query: (query) => {query.getRequest().setContextBrowserDevice('mobile');}, // Changing context at initialization, in this case, changing the device.
        state: {
            itemsPerPage: 10, // Changing the default amount of items to show
            keyphrase: 'Initial query term', // Changing the initial query term.
        }
  });
Copy

The example above works for Search Results, please note that each widget will have different properties to initialize.

Actions

Actions are operations that a widget can execute. Different widget types will have different actions. The following is a list of actions grouped by Widget type: