TURBO for Developers

Home > widget-integration > FilterService

FilterService class

Core business logic service for filter widget operations.

Orchestrates filter API calls, state management, URL handling, pagination, and filter option processing. Coordinates between FilterAPI, FilterStore, and various helper services to provide complete filter functionality.

Signature:

export declare class FilterService

Remarks

This service handles: - Filter API requests with additional parameters - Pagination state and URL synchronization - Collection path parsing and storage - Filter tree data enrichment - SEO meta tag management - Request ID tracking for analytics

Technical Support teams can extend this service to customize filter behavior, API request parameters, pagination logic, or add shop-specific business rules.

Example 1

Extend to add custom API parameters:

window.boostWidgetIntegration.extend('FilterService', (FilterService) => {
  return class CustomFilterService extends FilterService {
    async fetchFilters(addition = {}) {
      // Add shop-specific parameters
      const customAddition = {
        ...addition,
        shopId: this.getShopId(),
        customSegment: this.getCustomerSegment()
      };
      return super.fetchFilters(customAddition);
    }
  };
});

Example 2

Override pagination behavior:

window.boostWidgetIntegration.extend('FilterService', (FilterService) => {
  return class extends FilterService {
    async processPagination(newPage, behavior = 'replace') {
      // Add custom analytics before pagination
      this.trackPaginationEvent(newPage, behavior);
      return super.processPagination(newPage, behavior);
    }
  };
});

Constructors

Constructor	Modifiers	Description
(constructor)(appService, filterAPI, filterStore, filterHelper, storageHelper, urlHelper, filterTranslation, domHelper)		Creates a new FilterService instance.

Methods

Method	Modifiers	Description
clearAllParamHistory(options)		Clears all filter parameters from URL history. Removes all filter-related query parameters from the URL without affecting other parameters. Supports URL shortening and optional history push prevention.
fetchFilters(addition)		Fetches filter results from the API with optional additional parameters. Main method for requesting filtered product data. Handles API calls, request ID tracking, and action type storage for analytics. Supports various addition parameters like pagination behavior and collection focus.
fillFilterTree(filterOptions, selectedFilters, settingOptionValues)		Enriches filter tree with complete option data and metadata. Takes available filter options and selected filters, updates option values based on settings, and fills missing metadata for selected filters. Returns a complete filter tree with display labels, dependencies, and type information.
formatPercentSaleLabel(from, to)		Formats percent sale label
formatPriceLabel(to, from, precision, moneyFormat)		Formats price label with currency
generateFilterDataForList(key, value, filterOption)		Generates filter data object for list filters
getCollectionFilterOptionId(options)		Gets the collection filter option ID from options array
getCurrentCollection()		Gets current collection handle from URL. Extracts the collection handle from the URL pathname by parsing the /collections/{handle} pattern. Returns undefined if not on a collection page.
getFilterTreeParent(_dom)
handleExceededPage()		Checks if current page exceeds total pages and fetches filters if needed Called during initialization to handle edge cases with pagination
initShortenMaps()		Initializes URL shorten maps from app configuration. Loads shortened URL parameter mappings from app configuration and stores them in FilterStore. This allows using shorter query parameters in URLs for better SEO and readability (e.g., 'c' instead of 'pf_c_color').
parseCollectionPath()		Parses collection path from URL and updates app configuration. Extracts collection handle and optional tag from URL path, retrieves collection ID from storage, and updates TAEAppConfig with collection context. Handles both /collections/handle and /collections/handle/tag URLs.
parseHistoryParams()		Parses URL history parameters and updates filter state. Extracts filter parameters, sort options, and pagination from URL, updates FilterStore state, and rewrites URL with proper formatting. Handles URL shortening if enabled in settings.
processPagination(newPage, behavior)		Updates pagination state and fetches new page of results. Handles page navigation, URL parameter updates, and triggers API fetch with the specified behavior. Updates session storage for persistence.
resetFilters()		Resets all filters and pagination to initial state. Clears pagination to page 1, removes page parameter from URL, and fetches fresh filter results. Used when clearing all filters or starting a new filter session.
saveCollectionInfo()		Saves collection information during initialization. Stores the mapping between collection handle and collection ID in localStorage. This enables retrieving collection ID from handle when parsing URLs or processing collection filters.
saveRequestId(type, requestId, bundles)		Saves request ID to localStorage for analytics tracking. Stores API request IDs associated with filter, search, and suggest operations. These IDs are used to correlate user actions (clicks, add-to-cart) with specific API requests for analytics and conversion tracking.
savingCollectionId()		Saves collection ID to localStorage for "all collections" tracking. Stores the collection ID associated with the special "all" collection handle. This enables proper filtering when users navigate between specific collections and the "all collections" view.
setActionLocalStorage(action)		Sets the action type in localStorage for analytics tracking. Stores the most recent action type (filter, search, suggest) to localStorage. Used by analytics to determine the source of user interactions with products.
setupSEOMetaTags()		Sets up SEO meta tags based on filter state. Adds noindex meta tag when filters are active to prevent duplicate content issues. Helps maintain SEO health by preventing search engines from indexing filtered product pages.
syncActiveFiltersToContext()		Synchronizes active URL filter parameters to FilterStore context. Parses current URL parameters and updates selectedFilter state to match. Ensures filter UI reflects the actual URL state, especially important after browser back/forward navigation.
updateValuesOptions(options, settingOptionValues)		Updates option values based on filter settings. Processes filter options to filter by doc_count, create labels, handle single-option hiding, apply sorting, format rating values, and set appropriate select types. This is the main processing method for transforming raw API options into display-ready options.

← Back to Library Reference