Smart Collections (Categories & Brands)

Enhance your Catalyst storefront category and brand pages by integrating Fast Simon’s Smart Collection capabilities. This guide explains how to leverage the Fast Simon API in your Catalyst project to power dynamic, faceted category and brand pages.

This guide covers the category page implementation, but the implementation for the brand pages is identical. Follow the same steps for brand pages to integrate Fast Simon’s Smart Collections.

Step 1: Implement Smart Collection Data Fetching

• In your Catalyst project, navigate to the file:
  core/app/[locale]/(default)/(faceted)/fetch-faceted-search.ts
  
• Import the necessary types:

import {
  SortBy as FastSimonSortBy,
  SearchParams,
  ServerNarrow,
  SmartCollectionsParams,
} from '@fast-simon/types';

• Add the following code at the bottom:

interface FastSimonProductSearchParams {
  page?: string | null;
  categoryId?: string | number;
  narrow?: ServerNarrow[] | null;
  sort?: FastSimonSortBy | null | '';
  term?: string | null;
  facetsOnly?: boolean;
}

const getFastSimonProductSearchResults = cache(
  async ({
    page = '1',
    narrow,
    sort = '',
    categoryId,
    term,
    facetsOnly,
  }: FastSimonProductSearchParams) => {
    const fastSimon = await getFastSimon();

    const params: SmartCollectionsParams | SearchParams = {
      page: Number(page || '1'),
      narrow: narrow || undefined,
      sortBy: sort || undefined,
      facetsRequired: facetsOnly,
      productsPerPage: 12,
      categoryID: String(categoryId || ''),
      query: String(term || ''),
    };

    const cacheOptions = {
        cache: 'force-cache',
        next: {revalidate: 3600}
    }

    return categoryId
      ? await fastSimon.getSmartCollection(params, cacheOptions)
      : await fastSimon.getSearchResults(params, cacheOptions);
  },
);

export const fetchFastSimonFacetedSearch = cache(async (params: FastSimonProductSearchParams) => {
  const fastSimonResults = await getFastSimonProductSearchResults({ ...params, facetsOnly: false }); // cached

  if (params.facetsOnly && !fastSimonResults.facets_completed) {
    const facetsOnlyResponse = await getFastSimonProductSearchResults(params);
    fastSimonResults.facets = facetsOnlyResponse.facets;
  }

  return FastSimonDataTransformer.parseFastSimonProductsResponseData(fastSimonResults);
});

Explanation:

• Interface Definition: FastSimonProductSearchParams defines the parameters used for product search.
• Data Fetching Function: The getFastSimonProductSearchResults function initializes the Fast Simon client and retrieves either a smart collection (if a categoryId is provided) or search results.
• Facets Handling: The fetchFastSimonFacetedSearch function checks if facets are complete; if not, it re-fetches the facet data and then transforms the Fast Simon response using FastSimonDataTransformer.
• Cache Options: All fetching methods in our SDK support passing cacheOptions, which gives you full control over the API call caching. For example, in the code above, we pass:

  const cacheOptions = {
      cache: 'force-cache',
      next: { revalidate: 3600 }
  };
  This aligns with the Next.js reference for caching (see: Next.js API Reference for fetch). You can adjust these options as needed to manage caching and revalidation across all SDK data fetching methods.

---

Step 2: Integrate Smart Collections into Category Pages

Next, update your category page component to use Fast Simon’s refined search data. In your Catalyst project, navigate to:
core/app/[locale]/(default)/(faceted)/category/[slug]/page.tsx
and add the following code:

const getFastSimonRefinedSearch = cache(async (props: Props) => {
  const allParams = await props.params;
  const { slug } = allParams;

  const categoryId = Number(slug);
  const searchParams = await props.searchParams;

  return await fetchFastSimonFacetedSearch({
    page: searchParams.page && typeof searchParams.page === 'string' ? searchParams.page : '1',
    narrow: FastSimonDataTransformer.parseFiltersParams(searchParams),
    sort: FastSimonDataTransformer.getFastSimonSortParam(searchParams.sort),
    categoryId,
    facetsOnly: props.facetsOnly || false,
  });
});

Then, replace the data fetching calls in your page component:

• Update the Search and Pagination Functions:
  Locate the functions getSearch and getPaginationInfo and replace calls to the previous refined search function with getFastSimonRefinedSearch:

const getSearch = cache(async (props: Props) => {
  const search = await getFastSimonRefinedSearch(props);
  return search;
});

async function getPaginationInfo(props: Props): Promise<CursorPaginationInfo> {
  const search = await getFastSimonRefinedSearch(props);
  return {
    ...search.products.pageInfo,
    ...pageInfoTransformer(search.products.pageInfo)
  };
}

• Update the Filters Function:
  Replace the getFilters function with:

async function getFilters(props: Props): Promise<Filter[]> {
  const refinedSearch = await getFastSimonRefinedSearch({ ...props, facetsOnly: true });
  return refinedSearch.facets.items;
}

Explanation:

• Dynamic Data Fetching: The getFastSimonRefinedSearch function fetches the refined search data by parsing the route parameters (slug, page, filters, sort) and passing them to the faceted search function.
• Component Integration: By updating the search, pagination, and filters functions, your category pages now render data provided by Fast Simon’s Smart Collection API.

---

Step 3: Allow Fast Simon Image URLs

• Go to the file:
  core/next.config.ts
  
• In the nextConfig object, add the following:

// rest ...
images:{
  remotePatterns: [
    {
      protocol: 'https',
      hostname: 'acp-magento.appspot.com',
      pathname: '/**',
    },
    {
      protocol: 'https',
      hostname: 'assets.instantsearchplus.com',
      pathname: '/**',
    },
  ],
},
// ...rest

---

Pagination Integration for Catalyst

This guide details how to update your Catalyst storefront's pagination to use page numbers instead of cursors. It also covers necessary changes to the getPaginationInfo functions in both collection and search pages.

---

1. Update the CursorPaginationInfo Interface

In the file: core/vibes/soul/primitives/cursor-pagination/index.tsx

Update the CursorPaginationInfo interface as follows:

export interface CursorPaginationInfo {
  startCursorParamName?: string;
  startCursor?: string | null;
  endCursorParamName?: string;
  endCursor?: string | null;
  hasNextPage?: boolean | null;
  hasPreviousPage?: boolean | null;
}

---

2. Update the CursorPaginationResolved Component

Within the same file, update the pagination component logic:

a. Extract Pagination Data

Replace the original code that reads cursor values with code that extracts page numbers and pagination booleans:

const { hasNextPage, hasPreviousPage } = useStreamable(info);
const searchParams = useSearchParams();
const serialize = createSerializer({
  page: parseAsString,
});
const page = Number(searchParams.get('page') || '1');

b. Update the Previous Page Link

Replace the old cursor-based link:

{startCursor != null ? (
  <PaginationLink
    aria-label={previousLabel}
    href={serialize(searchParams, {
      [startCursorParamName]: startCursor,
      [endCursorParamName]: null,
    })}
    scroll={scroll}
  >

With the new implementation using page numbers:

{hasPreviousPage ? (
  <PaginationLink
    aria-label={previousLabel}
    href={serialize(searchParams, {
      page: String(page - 1),
    })}
    scroll={scroll}
  >

c. Update the Next Page Link

Similarly, replace the old cursor-based link for next:

{endCursor != null ? (
  <PaginationLink
    aria-label={nextLabel}
    href={serialize(searchParams, {
      [endCursorParamName]: endCursor,
      [startCursorParamName]: null,
    })}
    scroll={scroll}
  >

With the new implementation:

{hasNextPage ? (
  <PaginationLink
    aria-label={nextLabel}
    href={serialize(searchParams, {
      page: String(page + 1),
    })}
    scroll={scroll}
  >

---

3. Update the PaginationLink Component

Locate the PaginationLink component code in the same file and add prefetch to improve navigation performance. Update the <Link> element as follows:

<Link
  aria-label={ariaLabel}
  className={clsx(
    'flex h-12 w-12 items-center justify-center rounded-full border border-contrast-100 text-foreground ring-primary transition-colors duration-300 hover:border-contrast-200 hover:bg-contrast-100 focus-visible:outline-0 focus-visible:ring-2',
  )}
  href={href}
  scroll={scroll}
  prefetch="viewport"
  prefetchKind="full"
>
  {/* Link content */}
</Link>

Where to Add These Updates

• CursorPagination Component: All changes related to the pagination UI should be added in the core/vibes/soul/primitives/cursor-pagination/index.tsx file.

---

By following these steps, you'll have a unified pagination solution that leverages page numbers, improves navigation with prefetching, and integrates smoothly with Fast Simon's refined search responses in your Catalyst storefront.

---

Key Concepts

Fast Simon Smart Collection Data

• Smart Collections vs. Search Results: The implementation dynamically determines whether to fetch a smart collection (when a category ID is present) or general search results.
• Facets Handling: If facets are not complete in the initial API response, the code re-fetches the facets using the facetsOnly parameter.
• Data Transformation: The raw Fast Simon response is processed using FastSimonDataTransformer.parseFastSimonProductsResponseData to align with your storefront’s expected data structure.

Integration Benefits

• Improved Discovery: Leverage faceted search to provide customers with dynamic filtering options.
• Seamless Experience: Integrate smart collections into your Catalyst storefront without overhauling your existing components.
• Optimized Performance: Utilize caching strategies provided by Catalyst’s cache utility for efficient data fetching.

---

Additional Notes

• For more detailed examples on rendering facets and paginated results, refer to the Filters and Pagination components in the sample site.
• Ensure that your components are designed to handle the transformed data structure from Fast Simon.
• Customizations to the data transformation logic (via FastSimonDataTransformer) may be necessary depending on your storefront’s specific requirements.

By following these steps, you can harness the power of Fast Simon’s Smart Collection capabilities in your BigCommerce Catalyst storefront, creating a more dynamic and personalized shopping experience.