Skip to main content
Version: 13.x (Current)

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"
}
}

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"
}
}

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

propertyattributetypedefaultdescription
waitTimewait-timenumber500wait time before initialization event, in milliseconds
urlMaskurl-maskUrlMask-url mask to apply to the current path to extract dynamic parameters
eventLabelevent-labelstring'change-query'label of the event that will be dispatched as result
redirectUrlredirect-urlstring-optional parameter that contains the url to redirect when urlMask does not completely match
excludeWildcardsexclude-wildcardsbooleanfalsewhether or not matches from wildcards ((.*)) should be excluded from event payload

Listens to

This component listens to no event.

Emits

eventdescription
configurable eventgeneric event based on its properties (change-query by default)