Broadleaf Microservices

Search Walkthrough

In this walkthrough, we’ll be examining how we built the commerce app’s search and category pages. We will go through:

  1. Searching For Products.

    • Using the Commerce SDK to handle search requests

    • Handling type-ahead suggestion requests

Search Page

Prerequisite Information

Prior to loading content specific to searching for products we need to know, certain information prior, Specifically:

  1. Resolve the tenant and application

Search For Products.

To prepare for those requests, there are only two things required. First we need to resolve the Application, see Tenant & Application Walkthrough. Second we need to build the search parameters with the query, filters, and sort for the request.

Using searchProducts

METHOD

URL

SDK

Catalog Search

GET

/api/catalog-browse

searchProducts(searchParams, options)

Tip
Details can be found in the Catalog Search OpenAPI Documentation

How to query for products using the SDK

There is a single required parameter of the type SearchParams, which can contain important params such as query. The result will return a SearchResponse<Product> which has a property called content that contains the result of your query.

import { ClientOptions } from '@broadleaf/commerce-core';
import { BrowseClient } from '@broadleaf/commerce-browse';

async function searchFor(searchParams: SearchParams, options: ClientOptions) {
    const client = new BrowseClient(options);
    // EXAMPLE of SearchParams:
    // const searchParams = { query: "Green Ghost" };

    // BrowseClientCallOptions is OPTIONAL
    // BrowseClientCallOptions extends ClientCallOptions
    const priceContext: PriceContext = {
        locale: "en-US",
        currency: "USD"
    };

    const browserCallOptions: BrowseClientCallOptions = { priceContext }
    return client.searchProducts(searchParams, browserCallOptions);
}

This returns a SearchResponse<Product>, seen below. Note that the resulting Product results will be in content while the other information is for pagination, sorting, and filtering.

{
  "content": [
    {
      "id": "product1",
      "sku": "HS-GG-20",
      ...
    }
  ],
  "last": true,
  "pageable": {
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "pageSize": 50,
    "pageNumber": 0,
    "paged": true,
    "unpaged": false,
    "offset": 0
  },
  "sort": {
    "sorted": true,
    "unsorted": false,
    "empty": false
  },
  "facets": [ ... ],
  "totalElements": 5,
  "empty": false,
  "number": 0,
  "numberOfElements": 5,
  "size": 50,
  "correctedQuery": false,
  "totalPages": 1,
  "sorts": [
    {
      "sortOption": {
        "label": "Name",
        "name": "name",
        "displayOrder": 1
      },
      "active": true,
      "descending": false
    },
  ],
  "first": true
}

SearchParams

SearchParams contains optional properties to query products from a catalog

property

type

description

required

filters

Array<Filter>

The rule filters to apply.

optional

query

string

The query to search for.

optional

ruleFilters

string

The rule filters to apply.

optional

sort

string

Any sorting params to apply to the response.

Filtering

SearchParams contains the ability to apply filters that take an array of Filter objects. Below is an example of a price filter.

async function searchFor(searchParams: SearchParams, options: ClientOptions) {
    const client = new BrowseClient(options);

    const query = "Hot Sauce" ;

    const filters: Array<Filter> = [
        {
          name: 'price',
          ranges: [{ minValue: '0', maxValue: '15' }]
        }
    ];

    const searchParams = { query, filters };

    return await client.searchProducts(searchParams);
}

Filter DTO

Filter contains properties to filter product results products from a catalog search

property

type

description

required

name

string

The name of the filter.

required

values

Array<string>

The values associated to the filter.

optional

ranges

Array<FacetRange>

FacetRange DTO

A FacetRange contains optional properties to create a range filter

property

type

description

required

label

string

The label for the facet range.

optional

displayOrder

number

The values associated to the filter.

optional

minValue

string

The minimum value of the range.

optional

maxValue

string

The maximum value for the range.

Type-Ahead suggestions

Another key feature is the ability to get type-ahead suggestions from the SDK. These are used to provided autocomplete suggestions as well as specific products or categories that may match what the user is looking for and can save them form having to look through a search results page.

Using searchSuggestionsRequest

METHOD

URL

SDK

Catalog Search Suggest

GET

/search/catalog/suggest

searchSuggestionsRequest(searchSuggestionsRequest, options)

Tip
Details can be found in the Catalog Search Suggest OpenAPI Documentation

How to query for search suggestions using the SDK

There is a single required parameter of the type SearchSuggestionsRequest, that is described below, which will return the suggestions as a SearchSuggestionsResponse object.

import { ClientOptions } from '@broadleaf/commerce-core';
import { BrowseClient } from '@broadleaf/commerce-browse';

async function searchFor(searchSuggestionsRequest: SearchSuggestionsRequest, options: ClientOptions) {
    const client = new BrowseClient(options);
    // EXAMPLE of SearchSuggestionsRequest:
    // const searchSuggestionsRequest = { query: "Green Ghost" };
    return await client.searchSuggestions(searchSuggestionsRequest);
}

SearchSuggestionsResponse

This is the SearchSuggestionsResponse object that is returned by searchSuggestions.

{
  "suggestions": {
    "categories": [
      {
        "categoryNames": "Hot Sauces",
        "numResults": 1
      },
    ...
    ],
    "products": [ ... ]
  },
  "keyWords": [
    {
      "highlightedSuggestion": "<strong>Greeen</strong> Ghost",
      "suggestion": "Greeen Ghost"
    }
  ]
}

SearchSuggestionsRequest

SearchSuggestionsRequest contains properties to query suggestions from a catalog search

property

type

description

required

query

string

The query to use for suggestions.

required

name