Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Catalog browsing

Catalog browsing

Catalog browsing lets customers locate products by browsing the catalog hierarchy. Catalog browsing uses filters, sorters and pagination to make it easier for users to find products of interest. For more information on filters, see Filtered navigation.

Key classes and files

In Storefront:

  • BrowsingControllerImpl - Spring MVC controller for catalog browsing.
  • CatalogViewResultBean - Bean containing a browsing result, pagination history, and view history for display by a Velocity template.

In Store Assets:

  • categoryTemplate.vm - Default Velocity template for displaying a category-browsing page.

In Core:

  • BrowsingService - Service for browsing a catalog and its products.
  • BrowsingRequest - Browsing request representation.
  • BrowsingResult - Browsing result representation containing the products to display.
  • CategoryService - Service for category tasks.
  • ProductLoadTuner - Beans that define how much of a Product's data should be loaded during product retrieval.

How it works

  1. BrowsingControllerImpl's handleRequestInternal() method is invoked when a user browses a category by clicking a category link.
  2. BrowsingControllerImpl converts the category code to a category UID using CategoryService.
  3. BrowsingControllerImpl creates and populates a BrowsingRequest object with data from the HTTP request and the category UID.
  4. BrowsingControllerImpl calls the BrowsingService with the following input:
    1. The BrowsingRequest.
    2. The user's ShoppingCart, which is used to apply promotion rules.
    3. The ProductLoadTuner, which determines how much of a product's data is loaded.
  5. BrowsingService creates and populates a BrowsingResult.
  6. BrowsingService returns the BrowsingResult to BrowsingControllerImpl.
  7. BrowsingControllerImpl creates a CatalogViewResultBean populated with the BrowsingResult, and returns to the Spring MVC framework.
  8. categoryTemplate.vm renders the CatalogViewResultBean into HTML viewed by the user.

By default, the data included in each object in the result set is determined by the productLoadTunerForBrowsingAndSearch. For more information, see Load tuners.


  • You can configure BrowsingControllerImpl and the product load tuner in the Storefront's url-mapping.xml file.


  • If a CatalogViewResultHistory is passed to BrowsingService, BrowsingService will check whether the result in the history can be reused. A result in the history is considered reuseable if the new browsing request is more restricted than the former browsing request. For example, a browisng request of a category with a price filter " $200 - $400" is more restricted than a browisng request of the same category without the price filter.