URL Parameters Adapter

<bk-url-parameters></bk-url-parameters>

The URL Parameters Adapter allows to emit events upon connecting to the DOM, based on the value of the URL.

One common way of using the URL Parameters Adapter component is to fetch only one data element from a collection, retrieving its ID from the URL, as explained in Plugin Navigation dedicated section.

How to configure

Upon connection, the URL Parameters Adapter attempts to match the window URL against the given mask in property urlMask. If it fails, it will redirect according to the provided property redirectUrl. Otherwise it will attempt to emit the matched content as payload of an event using its property eventLabel as label of the event, which defaults to change-query.

{
  "tag": "bk-url-parameters",
  "properties": {
    "urlMask": "/order-details/:_id",
    "redirectTo": "/order-list"
  }
}

Use different masks for pathname and search

By default, the same mask is applied to both the pathname and the search sections of the URL. However, different ones can be specified:

{
  "tag": "bk-url-parameters",
  "properties": {
    "urlMask": {
      "pathname": "/order-details/:_id",
      "search": "\\?pageNumber=:pNumber"
    }
  }
}

Ignoring wildcards

Wildcards ((.*)) can be used in urlMask. These match any string and is included in the payload of the emitted event with numeric keys. If property excludeWildcards is true, matches coming from wildcards are excluded from the payload of the event.

{
  "tag": "bk-url-parameters",
  "properties": {
    "urlMask": "/order-details/(.*)/:_id",
    "excludeWildcards": true
  }
}

Examples

Example: Basic usage

With such configuration for the URL Parameters Adapter:

{
  "tag": "bk-url-parameters",
  "properties": {
    "urlMask": "/order-details/:_id"
  }
}

Assuming the URL to be "/order-details/test-id", then the URL Parameters Adapter emits the following change-query event, upon connection to the DOM:

{
  "label": "change-query",
  "payload": {
    "_id": "test-id"
  }
}

Example: Pathname / search

With such configuration for the URL Parameters Adapter:

{
  "tag": "bk-url-parameters",
  "properties": {
    "urlMask": {
      "pathname": "/order-details/:_id",
      "search": "\\?pageNumber=:pNumber"
    }
  }
}

Assuming the URL to be "/order-details/first-id?pageNumber=25", then the URL Parameters Adapter emits the following event:

{
  "label": "change-query",
  "payload": {
    "_id": "first-id",
    "pNumber": "25"
  }
}

Example: Wildcards

With such configuration for the URL Parameters Adapter:

{
  "tag": "bk-url-parameters",
  "properties": {
    "excludeWildcards": true,
    "urlMask": "/order-details/(.*)/:_id"
  }
}

Assuming the URL to be "/order-details/first-id/second-id", then the URL Parameters Adapter emits the following change-query event:

{
  "label": "change-query",
  "payload": {
    "_id": "second-id"
  }
}

If excludeWildcards property is not explicitly set to true:

{
  "tag": "bk-url-parameters",
  "properties": {
    "urlMask": "/order-details/(.*)/:_id"
  }
}

the following event is emitted:

{
  "label": "change-query",
  "payload": {
    "0": "first-id", // wildcard matches are included in the event payload through numeric keys
    "_id": "second-id"
  }
}

API

Properties & Attributes

property	attribute	type	default	description
waitTime	wait-time	number	500	wait time before initialization event, in milliseconds
urlMask	url-mask	UrlMask	-	url mask to apply to the current path to extract dynamic parameters
eventLabel	event-label	string	'change-query'	label of the event that will be dispatched as result
redirectUrl	redirect-url	string	-	optional parameter that contains the url to redirect when urlMask does not completely match
excludeWildcards	exclude-wildcards	boolean	false	whether or not matches from wildcards ((.*)) should be excluded from event payload

Listens to

This component listens to no event.

Emits

event	description
configurable event	generic event based on its properties (change-query by default)