TURBO for Developers

Home > widget-integration > FilterUrlHelper

FilterUrlHelper class

URL Management Helper for Filter Module

Manages all URL and query parameter operations for the filter system, including parameter get/set/delete operations, history management, and URL shortening schemes.

This helper can be extended by Technical Support teams to customize URL handling for specific shops, including custom parameter formats, separators, and history behavior.

Signature:

export declare class FilterUrlHelper

Remarks

Supports three URL schemes for parameter handling: - Scheme 0: Standard URLSearchParams behavior (multiple parameters with same key) - Scheme 1: Delete then append all values (ensures clean parameter lists) - Scheme 2: Combine values with custom separator (uses sessionStorage, default)

The helper maintains performance by minimizing URL parsing operations and using efficient string manipulation. Protected methods allow TS teams to customize specific behaviors without reimplementing core logic.

Example 1

Extend to customize URL shortening:

window.boostWidgetIntegration.extend('FilterUrlHelper', (FilterUrlHelper) => {
  return class CustomFilterUrlHelper extends FilterUrlHelper {
    protected getShortParamKey(key) {
      // Use shop-specific shortening scheme
      const customMap = {
        'pf_brand': 'brand',
        'pf_color': 'color',
        'pf_size': 'size'
      };
      return customMap[key] || super.getShortParamKey(key);
    }
  };
});

Example 2

Override to use custom parameter separator:

window.boostWidgetIntegration.extend('FilterUrlHelper', (FilterUrlHelper) => {
  return class extends FilterUrlHelper {
    protected getMultipleValueSeparator() {
      return '|'; // Use pipe instead of comma
    }
  };
});

Example 3

Add analytics tracking on history changes:

window.boostWidgetIntegration.extend('FilterUrlHelper', (FilterUrlHelper) => {
  return class extends FilterUrlHelper {
    protected mutateHistory(behavior, urlHref, state) {
      // Track filter changes
      if (window.gtag) {
        window.gtag('event', 'filter_change', { url: urlHref });
      }
      super.mutateHistory(behavior, urlHref, state);
    }
  };
});

Constructors

Constructor	Modifiers	Description
(constructor)(store)		Constructs a new instance of the `FilterUrlHelper` class

Methods

Method	Modifiers	Description
appendQueryParamHistory(key, value, replace, options)		Appends a value to a query parameter in the URL. Used for multiple selection filters to add new values without replacing existing ones. This is different from setQueryParamHistory which replaces all values.
applyParamOperation(url, key, value, options)	`protected`	Applies parameter operation to URL (set or append). Handles both single values and arrays, with optional force-append mode. Override this method to customize how parameters are added to URLs.
buildQueryParams(params)		Builds a URLSearchParams object from filter API parameters. Converts a FilterAPIParams object into URLSearchParams format, handling both single values and arrays. Array values are appended with `[]` suffix.
checkExistFilterOptionParam(isShortenUrlParam)		Checks if filter option parameters exist in current URL. Scans URL parameters for any that start with 'pf_' prefix, mapping shortened keys to long keys if URL shortening is enabled.
clearAllParamHistory(options)		Clears all filter parameters from URL history. Removes all parameters that start with FILTER_KEY_PREFIX ('pf_') or their shortened equivalents if URL shortening is enabled.
deleteQueryParamHistory(key, options)		Deletes a query parameter from the URL history. Handles both shortened and full parameter names with multiple URL schemes. For URL scheme 2, also clears associated sessionStorage data.
deleteQueryParamsHistory(keys, options)
getMultipleValueSeparator()	`protected`	Gets the configured separator for multiple values in a URL parameter. Returns the separator character used to combine multiple filter values in a single URL parameter (URL scheme 2). Override this method to use custom separators for specific shops or regions. The result is cached for performance since this method may be called frequently during URL parsing and construction.
getParamsHistory()		Parses URL search parameters and extracts filter params, sort, and pagination. Handles both shortened and full parameter formats by mapping short keys back to their long form using the longParamsMap from store.
getQueryParamByKey(key)		Gets a query parameter value by key from current URL.
getShortParamKey(key)	`protected`	Gets shortened parameter key if URL shortening is enabled. Maps long parameter keys (e.g., 'pf_brand') to their shortened versions (e.g., 'b') using the shortParamsMap from store. Override this method to implement custom URL shortening schemes for specific shops.
getUrlScheme()		Gets the URL scheme configuration.
mutateHistory(behavior, urlHref, state)	`protected`	Updates browser history with the given URL. Override this method to add custom behavior like analytics tracking, logging, or state management when URL changes occur.
removeQueryParamHistory(key, value, options)		Removes a specific value from a query parameter in the URL. This is different from deleteQueryParamHistory which removes the entire parameter. If the parameter has multiple values, only the specified value is removed.
removeQueryParamsHistory(params, options)		Removes specific values from multiple query parameters in the URL. Handles both shortened and full parameter names with multiple URL schemes. Efficiently processes multiple parameter removals in a single history operation.
removeShortenedParam(url, key)	`protected`	Removes a shortened parameter from URL search params. Handles the custom format used by URL scheme 2. Override this method to customize how shortened parameters are removed from URLs.
rewriteUrlFromParams(data, options)		Rewrites the URL with new filter parameters, sort, and pagination. Clears all existing filter parameters and sets new ones based on provided data. This is a complete URL reconstruction, useful for applying bulk filter changes.
setQueryParamHistory(key, value, replace, options)		Sets a query parameter in the URL history. Handles both shortened and full parameter names with multiple URL schemes. The behavior varies based on the URL scheme configuration.
setShortenedParam(url, key, rawValues)	`protected`	Sets a shortened parameter in URL with combined values. Used for URL scheme 2 to combine multiple values with the configured separator. Override this method to customize how shortened parameters are encoded in URLs.

← Back to Library Reference