Services

All services have configuration options, or alternatively can be turned off by being set to the boolean false.

A list of all services is available here. This list is automatically generated as the product core is updated, and thus is always up-to-date.

Here is an example of how to disable the logging and past purchase services:

new storefront({
  ...
  services: {
    logging: false,
    pastPurchases: false
  }
});

Adding a service

You can add a custom service by providing a key associated with your class. It will have the app instance passed through its constructor. When the services are initialized, their init functions are called with services as an argument, so you must include an init function in your custom service.

If you need to pass additional properties to your constructor you can also use the following example to create a custom service:

Logging

Search

The search service listens to store updates and triggers a search request. It also keeps a record of past searches.

Url

Beautifier

URL beautifier object allows configuring URL beautification options. If a function is passed it will be used as a URL beautifier factory for creating a custom beautifier.

As a configuration object

refinementMapping

Accepts objects in the form { <referenceKey>: <refinementName> }, where the referenceKey is the key to be used in the url path. The key must be a single character.

params

An object with the keys refinement, page, pageSize, sort, and collection, indicating the parameter name which will be used as a reference for these items as a URL parameter.

queryToken

A single character to be used as the query parameter in the URL.

suffix

A suffix to be pre-pended to the path.

useReferenceKeys

true to use referenceKeys in the URL, false to use params only.

details

An object containing params, which itself is an object with the keys area and collection. The values located at area and collection will be used as the names of the corresponding query string parameters when building details-type URLs.

Disable either area or collection with false as the key-value.

The following is an example of setting custom area and collection references:

As a factory function

The function will receive the running instance of the StoreFront application and the generated routing table based off of the routes configuration.

beautifierFactory(app, routes)

• app: StoreFront
• routes: { [key: string]: string }
• returns: { parse: function, build: function } - Must return an object with a build() function and a parse() function.

build(type, request)

• type: string - The type of route to generate, either 'search' or 'details'.
• request: object - The request data needed to generate the url.
• returns string - The generated URL.

parse(url)

• url: string - The URL to parse into state.
• returns { route: string, request: } - The type of route found and the extracted request data. The URL service will trigger a request based on the provided route type. For example, returning { route: 'search', request: { query: 'hello' } } will trigger a search request with the query hello. To prevent StoreFront from dispatching a request, this function may return either:

• an object with an unknown route key (ie. { route: 'home', request: {} }.
• null (please note: StoreFront will print a warning when running in debug mode).

Routes

search

A string indicating what path to use for search results page.

details

A string indicating what path to use for details page

History

pushState(data, title, url)

• data: object - the state for the given history section. Will be used to re-build the store state.
• title: string
• url: string - the url for the state.

Serves the same purpose as the window.history.pushState function, but can be replaced with any function. Is called when the URL needs to be updated to reflect a change in history.

replaceState(data, title, url)

• data: object - the state for the given history section. Will be used to re-build the store state.
• title: string
• url: string - the url for the state.

Serves the same purpose as the window.history.replaceState function, but can be replaced with any function. Is called when the state for the current history entry needs to be updated to reflect changes.

initialUrl

The url to use on initial page load.

listener(event, cb)

• event: 'popstate' - the event type.
• cb: function - the url service rewind function.

The history listener will fire history transitions, eg, window.history.back(), window.history.forward(), window.history.go(1), window.history.go(-1). It is the responsibility of the listener to trigger the callback for a given event. This is to allow easy integration with window.addEventListener, and also enables users to set up the url listener with a listener that has several responsibilities in addition to listening for popstate. Currently the callback is not configurable and always calls the url service rewind function.

Redirects

Causes a redirect to value path for each key when key matches the next url path. For example, the example configuration would cause a redirect from www.example.com/search/shoes/q to www.example.com/special-shoes-sale.

URL Handler - urlHandler(url)

• url: string - the URL to navigate to

If supplied, this function will be called with every newly generated URL rather than using the single-page application style on-page routing native to StoreFront. This can be used to hard redirect to custom URLs not handled by StoreFront using window.location.assign().

Tracker

warnings

true to return warnings from the tracker service, false to hide them.

Using an override function for Tracker events

All of the Tracker service methods can be modified by specifying functions in the service’s configuration object. The associated method will run first, then pass the relevant value and currentEvent to your override function, allowing you to modify the event before it is beaconed.

new storefront({
  ...
  services: {
    tracker: {
      sendSearchEvent: (id, event) => ({ ...event, metadata: event.metadata.concat({ key: 'gbi', value: true }) })
    }
  }
})