Navigating between pages (CSR)

This is for:

Developer

In this article

Manage page URL via the context.view object
Syncing parameters with the URL
Updating language on page change

When building your commerce interfaces, it’s crucial to manage the state of the current URL using Headless. As users navigate to different pages, ensure that the URL is set and updated correctly to reflect the current view.

Additionally, you may want to manage URL parameters to sync them with the state of the interface. For example, when a user filters products on a search page or product listing page (PLP), you might want to update the URL to reflect the applied filters. This way, reloading the page or sharing the URL with others will display the same filtered results.

Manage page URL via the `context.view` object

Use Headless to send the URL information with every Commerce API request. This ensures that actions which affect the view, such as navigating to a new page, emit the correct analytics events.

It’s also important for product listing pages (PLPs) because you must specify the URL that corresponds to the PLP you want to target.

Setting URL on engine initialization

When initializing the commerce engine, you can set the URL by using the context.view object.

import { buildCommerceEngine } from '@coveo/headless/commerce';
import { loadCartItemsFromLocalStorage } from '../utils/cart-utils';

export const getEngine = () => {
  if (_engine !== null) {
    return _engine;
  }

  _engine = buildCommerceEngine({
    configuration: {
      organizationId: '<ORGANIZATION_ID>',
      accessToken: '<ACCESS_TOKEN>',
      analytics: {
        trackingId: '<TRACKING_ID>'
      },
      context: {
        currency: '<CURRENCY>',
        country: '<COUNTRY>',
        language: '<LANGUAGE>',
        view: { 
          url: '<URL>'
        },
      }
      cart: {
        items: loadCartItemsFromLocalStorage() ?? [],
      },
    },
  });

  return _engine;
};

Set the view URL to the current page URL.

Modifying the URL on page change

When the user navigates to a new page, update the view URL using the Context controller.

import { engine } from './Engine';
import { buildContext } from '@coveo/headless/commerce';

const context = buildContext(engine); 

onPageChange(newUrl: string) { 
  context.setView({ url: newUrl });
}

	Initialize the `Context` controller by passing in the previously initialized engine.
	Call the `setView` method on the `Context` controller to change the url when the user navigates to a different page.

For more details on how to set the URL in a sample project, see the sample in the Headless repository

For URL-based audiences defined in the Coveo Merchandising Hub (CMH) to function correctly with query parameters, you can pass the complete URL including query or hash parameters when calling setView().

import { engine } from './Engine';
import { buildContext } from '@coveo/headless/commerce';

const context = buildContext(engine);

onPageChange(newUrl: string) {
  const currentUrl = new URL(newUrl, window.location.origin);
  currentUrl.search = window.location.search;
  context.setView({ url: currentUrl.href }); 
}

Include query parameters to ensure that the Commerce API receives the complete URL for audience targeting.

Syncing parameters with the URL

Additionally, you might need to sync search parameters with the URL. This ensures that filters, sorting, and other side effects, such as the current pagination, are reflected in the URL. As a result, users can reload the page or share it with others to see the same filtered results.

Headless for Commerce provides two sub-controllers to manage URL parameters:

urlManager: Automatically serializes parameters (such as query, sort criteria, and facet values) into a URL-ready string. This controller handles serialization and deserialization internally, making it easy to use and requiring minimal configuration.

Example

Your search page is configured with the query set to "hello" and results sorted by descending date. The urlManager serializes this state into the following string: q=hello&sortCriteria=date%20descending.
parameterManager: Provides search parameters as an object rather than a string, offering full control over URL serialization and deserialization. This controller is useful when you must handle URL parameters in a specific way, but it requires a more complex setup.

Note

This article explains how to use the urlManager sub-controller to manage URL parameters on a product listing page (PLP). Similar logic applies when using the parameterManager sub-controller.

The primary difference is that, with the parameterManager sub-controller, you must manually serialize and deserialize parameters. For details, see the generic Headless example.

When using the commerce engine, replace the buildSearchParameterManager with the corresponding parameterManager sub-controller from either the Search controller or the ProductListing controller.

Using the `urlManager` sub-controller

import {
  buildProductListing,
  Cart,
  CommerceEngine,
  Context,
} from '@coveo/headless/commerce';
import { useEffect, useCallback } from 'react';
import SearchAndListingInterface from '../components/use-cases/search-and-listing-interface/search-and-listing-interface.js';

interface IProductListingPageProps {
  engine: CommerceEngine;
  contextController: Context;
  url: string;
}

export default function ProductListingPage(props: IProductListingPageProps) {
  const {engine, contextController, url} = props;

  const productListingController = buildProductListing(engine);

  const bindUrlManager = useCallback(() => { 
    const fragment = () => window.location.hash.slice(1); 
    const urlManager = productListingController.urlManager({ 
      initialState: {fragment: fragment()},
    });

    const onHashChange = () => {
      urlManager.synchronize(fragment());
    };

    window.addEventListener('hashchange', onHashChange); 
    const unsubscribeManager = urlManager.subscribe(() => { 
      const hash = `#${urlManager.state.fragment}`;

      if (!productListingController.state.responseId) {
        window.history.replaceState(null, document.title, hash);
        return;
      }

      window.history.pushState(null, document.title, hash);
    });

    return () => {
      window.removeEventListener('hashchange', onHashChange);
      unsubscribeManager();
    };
  }, [productListingController]);

  useEffect(() => {
    contextController.setView({url}); 
    const unsubscribe = bindUrlManager(); 

    if (
      !productListingController.state.isLoading &&
      !productListingController.state.responseId
    ) {
      productListingController.executeFirstRequest();
    } else if (!productListingController.state.isLoading) {
      productListingController.refresh();
    }

    return unsubscribe;
  }, [contextController, url, productListingController, bindUrlManager]);

  return (
    <div className="ProductListingPage">
      <SearchAndListingInterface searchOrListingController={productListingController}/>
    </div>
  );
}

Define a function that synchronizes the URL fragment with the urlManager state. Use React’s useCallback hook to memoize the function between renders.

Create a function that extracts the hash fragment from the URL using the window object.

Initialize the urlManager sub-controller with the initial state of the fragment.

Depending on the product discovery solution you’re implementing, choose the appropriate urlManager sub-controller: Search or ProductListing.

Add an event listener to the hashchange event to update the state of the fragment on the urlManager sub-controller.

Similarly, subscribe to the urlManager sub-controller to update the URL fragment in the browser using the History API. Now, the state of the fragment in Headless will be synced with the URL fragment in the browser.

As discussed previously, when a user navigates to a new page, update the URL by calling the setView method on the Context controller.

Calling setView resets the state of facets, sorting, and pagination. This behavior is necessary because the user may have navigated to a different page where these settings are no longer applicable. However, if the user hasn’t navigated to a new page, such as when loading a page for the first time or reloading the same page, it’s important to restore the parameters encoded in the URL fragment. Thus, setView should be called before calling bindUrlManager().

If you use URL-based audiences, make sure that the url parameter you pass to setView includes the query or hash parameters, as shown in the Modifying the URL on page change section.

Call the bindUrlManager function to synchronize the URL fragment with the urlManager state.

Note

In the example above, setView is called before bindUrlManager to ensure the user’s intended state isn’t lost when the page is loaded or reloaded. Similar logic applies when you’re using other methods to update the Context controller.

Updating language on page change

If you’re supporting multiple languages, you must first set the language when initializing the engine.

Then, when the user changes the language, update the state of the language using the setLanguage method on the Context controller.