Skip to main content
Version: 10.9.x

Misc

bk-antd-theme-manager​

Logical web component that can be included in applications layout to inject an Ant Design compatible theme. This component is analogous to mlc-antd-theme-manager from micro-lc.

bk-auto-refresh​

Allows refreshing some resources with the selected interval.

<bk-auto-refresh></bk-auto-refresh>

auto-refresh

It emits a change-query event with an empty payload every interval so it needs bk-crud-client to properly work.

Configuration​

It is possible to customize the intervals and the default interval for refreshing the resources. Intervals are expressed in seconds.

Example:

  ...
  {
    "type": "element",
    "tag": "bk-auto-refresh",
    "properties": {
      "intervals": [10, 30, 60, 120],
      "initialInterval": 10
    }
  }
  ...

Properties & Attributes​

propertyattributetypedefaultdescription
intervals-number[] | undefined[5, 10, 30, 60]a list of intervals in seconds
initialInterval-number0initial interval value

Listens to​

eventactionemitson error
loading-datasets internal loading state--

Emits​

eventdescription
change-queryrequires refresh without modifying current CRUD query by attaching an empty payload

Bootstrap​

None

bk-confirmation-modal​

prompts the user for confirmation on certain actions

<bk-confirmation-modal></bk-confirmation-modal>

confirmation-modal

Configure actions​

It is possible to mount custom components as confirmation/cancel buttons in the modal. For instance, the following example shows how to request for confirmation before the action of a button is performed.

Example​

The following snippet of configuration shows an "Abort" button which performs a POST request to a given endpoint.

{
  "tag": "bk-button",
  "properties": {
    "content": "Abort",
    "clickConfig": {
      "type": "http",
      "actionConfig": {
        "url": "lambdas/abort",
        "method": "POST",
        "config": {
          "headers": ...
        },
        "body": ...
      }
    }
  }
}

In order to require confirmation for this action, it is possible to:

  • have the button spawn a Confirmation modal
  • have the "confirm" button of this modal perform the POST request as the following snippet shows:
{
  "tag": "bk-button",
  "properties": {
    "content": "Abort",
    "clickConfig": {
      "type": "event",
      "actionConfig": {
        "label": "require-confirm",
        "payload": {
          "title": {
            "en": "Abort order?",
            "it": "Cancellare ordine?"
          },
          "content": {
            "en": "Are you sure you want to abort this order?",
            "it": "Sei sicuro di voler cancellare l'ordine?"
          },
          "configCancel": {
            "tag": "bk-button",
            "properties": {
              "content": "No",
              "type": "ghost"
            }
          },
          "configOk": {
            "tag": "bk-button",
            "properties": {
              "content": "Ok",
              "clickConfig": {
                "type": "http",
                "actionConfig": {
                  "url": "lambdas/abort",
                  "method": "POST",
                  "config": {
                    "headers": ...
                  },
                  "body": ...
                }
              }
            }
          }
        }
      }
    }
  }
}

The "Abort" button will now launch a require-confirm event. The Confirmation modal listens to it and becomes visible, using its payload to match its state as follows:

  • 'title': the title of the modal
  • 'content': the text content of the modal
  • 'configCancel': a 'tag' / 'properties' pair for the cancel button
  • 'configOk': a 'tag' / 'properties' pair for the confirmation button In particlar, the 'configOk' field is used to build the confirmation button. In this case, we build a button that will perform the POST call that was performed directly by the button in the previous configuration. Once one of the buttons is clicked, the confirmation modal automatically closes. The cancel button does not perform any action: if clicked, the modal will simply close and the endpoint will not be called.

Properties & Attributes​

propertyattributetypedefaultdescription
heightheightstring'50px'height of the modal
widthwidthstring'520px'width of the modal

Listens to​

eventactionemitson error
require-confirmdisplays a confirmationModal with buttons for the user to confirm or cancel the triggering of certain actions--

Emits​

eventdescription
Configurable eventson confirm or on cancel, it can forward events that were specified in the payload as the callback for the relative button click

Bootstrap​

None

bk-drawer​

Generic drawer container for custom content and custom footer

<bk-drawer></bk-drawer>

Properties & Attributes​

propertyattributetypedefaultdescription
content-Taggable | Taggable[]-configurable content of the drawer. Supports both object or array, as: {tag: string; properties?: Object; children?: string}
dataCustomActions-DataCustomAction[]-list of actions
drawerIddrawer-idstring-identifier associated to the drawer
drawerTitle-LocalizedText-title of the drawer
footerCallToAction-CallToAction-alternative way to specify the footer of the drawer. This property is to be set programmatically only
footerComponent-null | Taggable | Taggable[]-configurable footer of the drawer. Supports both object or array, as: {tag: string; properties?: Object; children?: string}
loadingloadingbooleanfalsewhether or not the drawer is loading
maskmaskbooleantruewhether to mask or not the drawer
requireConfirm-boolean | RequireConfirmOptsfalsewhether or not the drawer requires confirmation to close with unsaved data
rootElementSelectorroot-element-selectorstring-root element to append the drawer to
subTitle-LocalizedText-sub-title of the drawer
titleIcontitle-iconstring-icon to place next to to the title
width-string | number-width of the drawer
zIndexz-indexnumber-zIndex of the drawer

Listens to​

eventactionemitson error
using-form-containernotifies a drawer is in use--

Emits​

This component emits no event.

Bootstrap​

None

bk-layout​

Displays a menu, analogous to the micro-lc (version 2.0.0+) menu, which allows to navigate amongst plugins.

layout

<bk-layout></bk-layout>
caution

bk-layout is not supported by micro-lc version <2.0.0. micro-lc version 2.0.0+ (or a custom rendering engine) should be used.

bk-layout can be configured in a number of ways:

Mode​

Three modes are available:

type Menu = 'fixedSideBar' | 'overlaySideBar' | 'topBar'

Controlling how the menu is rendered - either as a side-bar (overlay or fixed) or a top-bar.

type Logo {
  /** Alternative text to display if the logo is not found  */
  altText?: string

  /** Link to navigate to when the logo is clicked */
  onClickHref?: string

  /** URL of the logo image */
  url?: string
}

Help Menu​

type HelpMenu {
  /** Link to the help page */
  helpHref: string
}

User Menu​

type UserMenu {
  /** Configuration needed to perform user logout */
  logout?: {
    /** Method used to perform the call to the URL specified in the 'url' property */
    method?: 'GET' | 'POST'

    /** URL to be redirected to after the logout */
    redirectUrl?: string

    /** URL called to log out the user. The method used is the one specified in the 'method' property */
    url?: string
  }

  /** URL called in GET to retrieve user data */
  userInfoUrl: string

  /** Mapping between the properties returned from the user info URL call and the ones expected by the component */
  userPropertiesMapping?: Record<string, 'name' | 'avatar' | string>
}
type Head {
  /** Url of the fav icon */
  favIconUrl?: string

  /** Title of the tab */
  title?: string
}

Custom locale​

It is possible to override default labels.

type Locale = {
  collapse?: string
  logout?: string
}

Items in the menu. These can be of two types, href or application. href menu items behave lie links, navigating to a configurable page upon click; while application pages navigate to a plugin.

Multiple menu items can be grouped into recursive structures, categories (collapsible) and groups (non-collapsible).

All types of menu item have internationalized labels LocalizedText.

Href​

export interface HrefMenuItem {
  /** Link's destination */
  href: string

  /** Icon of the menu item */
  icon?: string

  /** Unique identifier of the href */
  id: string

  /** Label of the menu item */
  label?: LocalizedText

  /** Specifies where to open the linked document */
  target?: '_blank' | '_self' | '_parent' | '_top'

  /** Type of the item: hyperlink to another page */
  type: 'href'
}

Application​

export interface ApplicationMenuItem {
  /** Icon to visualize */
  icon?: string

  /** Unique identifier of the corresponding micro-lc application  */
  id: string
  
  /** Label of the menu item */
  label?: LocalizedText
  
  /** Identifiers of micro-lc other applications that also correspond to the item */
  selectedAlsoOn?: string[]
  
  /** Type of the item: micro-lc application */
  type: 'application'
}

Category​

export interface CategoryMenuItem {
  /** Menu items included in the category */
  children?: MenuItem[]

  /** Icon to visualize */
  icon?: string

  /** Unique identifier of the category */
  id: string

  /** Label of the menu item */
  label?: LocalizedText

  /** Type of the item: collapsible sub-menu */
  type: 'category'
}

Group​

export interface GroupMenuItem {
  /** Menu items included in the group */
  children?: MenuItem[]

  /** Unique identifier of the group */
  id: string

  /** Label of the menu item */
  label?: LocalizedText

  /** Type of the item: non-collapsible group of items */
  type: 'group'
}

Properties & Attributes​

propertyattributetypedefaultdescription
modemodeModeoverlaySideBarcontrols how the menu is visualized
logo-Logo-logo to be visualized in the menu
menuItems-MenuItem[]-describes the items in the menu
helpMenu-HelpMenu-controls the help button on the menu
userMenu-UserMenu-controls the user information section of the menu
head-Head-controls tab visualization options
locale-{[x: string]: string}-allows to override component labels

Listens to​

This component listens to no event.

Emits​

This component emits no event.

Bootstrap​

None

bk-layout-container​

allows swapping layouts

<bk-layout-container></bk-layout-container>

This component is meant to allow multiple configurations to live within the same plugin by:

  1. re-using back-kit components without letting functionalities (mostly clients') to trump each other
  2. render multiple layouts together like a page with table, then a card detail, then another table and so on
  3. condensate plugins into a single one. A simple instance would be a user which might want to explore multiple details connected with its user but persisted on different entities. Since a backend resource, like a database collection/table, is mostly mapped 1:1 on a Backoffice plugin using a single client, like the bk-crud-client, it is recommendable to use different plugins to render different collections. For those cases falling outside the previous scope, for instance a customer which might want to check simultaneously both its purchases and its current shopping cart which, if the latter is persisted, are definitively stored on different places, a layout that can be switched might come in handy. By reproducing an element-composer-compatible configuration, bk-layout-container provides a wrapper for different configurations wired to one or many eventBus. Such configurations can be switched by using a single event on the default bus coming from the element-composer, or anyway injected in the bk-layout-container instance on the page.

customer example​

Let's then suppose we have a customer, a list of their previous purchases and a list of their current basket items. We could use different plugins. For previous purchases it would look like:

// previous-purchases.json
{
  "$ref": {
    "ppSchema": {
      "type": "object",
      "properties": {
        "_id": {"type": "string"},
        "items": {"type": "array"}
      }
    }
  },
  "content": {
    "type": "row",
    "content": [
      {
        "type": "element",
        "tag": "bk-table",
        "properties": {
          "dataSchema": {"$ref": "ppSchema"} 
        }
      },
      {
        "type": "element",
        "tag": "bk-crud-client",
        "properties": {
          "dataSchema": {"$ref": "ppSchema"} 
        }
      }
    ]
  }
}

while current basket would look like:

// current-basket.json
{
  "$ref": {
    "cbSchema": {
      "type": "object",
      "properties": {
        "_id": {"type": "string"},
        "description": {"type": "string"},
        "price": {"type": "number"}
      }
    }
  },
  "content": {
    "type": "row",
    "content": [
      {
        "type": "element",
        "tag": "bk-table",
        "properties": {
          "dataSchema": {"$ref": "cbSchema"} 
        }
      },
      {
        "type": "element",
        "tag": "bk-crud-client",
        "properties": {
          "dataSchema": {"$ref": "cbSchema"} 
        }
      }
    ]
  }
}

If the UI should instead include two tables in a page that can be visually swapped by a set of buttons or tabs, by wrapping both configurations in the bk-layout-container does the job.

// single-plugin.json
{
  "$ref": {
    "ppSchema": {
      "type": "object",
      "properties": {
        "_id": {"type": "string"},
        "items": {"type": "array"}
      }
    },
    "cbSchema": {
      "type": "object",
      "properties": {
        "_id": {"type": "string"},
        "description": {"type": "string"},
        "price": {"type": "number"}
      }
    }
  },
  "content": {
    "type": "element",
    "tag": "bk-layout-container",
    "properties": {
      "content": {
        "$default": {/* first plugin */},
        "currentBasket": {/* second plugin */}
      }
    }
  }
}

The $default key is not mandatory but is reserved and marks the layout to render on landing. The bk-layout-container has another property to avoid $default which is currentLayout. By setting currentLayout to currentBasket, the layout starts on the currentBasket config. Each layout has a dedicated EventBus instance which has the same name of the configuration key ( in this case $default and currentBasket). $default is the EventBus currently injected in the bk-layout-container. To override this behavior there is the key busDiscriminator which defaults to $inherit and takes the EventBus of its parent. Overriding means giving a new key to get a different bus, like $default. Any previously not existent key spawns a new EventBus. To swap layout an event has been reserved with label: layout/change and payload

type LayoutChangePayload = {
  layout: string
}

and layout must contain a valid bk-layout-container content prop key. A bk-button can be for instance used

{
  "type": "element",
  "tag": "bk-button",
  "properties": {
    "content": "View Orders",
    "clickConfig": {
      "type": "event",
      "actionConfig": {
        "label": "layout/change",
        "payload": {
          "layout": "orders"
        }
      }
    }
  }
}

Disable shadow dom​

Adding the attribute disable-shadow-dom allows to disable the shadow dom for this component, which can be useful when it has to embed children which bubble events up to the document root such as bk-calendar.

caution

disable-shadow-dom must be passed as attribute to bk-layout-container, and not as property. For instance:

{
  "type": "element",
  "tag": "bk-layout-container",
  "attributes": {
    "disable-shadow-dom":""
  },
  "properties": {
    ...
  }
}

Properties & Attributes​

propertyattributetypedefaultdescription
content-{[x: string]: LayoutNode} | {[x: string]: LayoutNode}-layouts configuration
disableShadowDomdisable-shadow-dom | booleanfalsedisable the shadow dom as render root
currentLayoutcurrent-layoutstring-default layout to view on landing

Listens to​

eventactionemitson error
layout/changerequires the connection of the layout which is referenced in the event payload--

Emits​

This component emits no event.

Bootstrap​

None

bk-layout-swap​

caution

works only with @micro-lc/composer@^2 and @micro-lc/orchestrator@^2

allows swapping between different document fragments / compose configurations

<bk-layout-swap></bk-layout-swap>

The use case this component addresses is when two or more configurations live in the same page but they need to be rendered conditionally, using another component, such as bk-tabs or bk-button to swap them.

Let's say we'd like to swap between a table view like

[
  {
    "tag": "bk-table",
    ...
  }
]

and a calendar component

[
  {
    "tag": "bk-calendar",
    ...
  }
]

and we'd use a pair of buttons, both firing the layout/change event, with the payload layout: table and layout: calendar to reach either layout

[
  {
    "tag": "bk-button",
    "properties": {
      "content": "Go to Table",
      "action": {
        "type": "event",
        "config": {
          "events": {
            "label": "layout/change",
            "payload": {
              "layout": "table"
            }
          }
        }
      }
    }
  },
  {
    "tag": "bk-button",
    "properties": {
      "content": "Go to Calendar",
      "action": {
        "type": "event",
        "config": {
          "events": {
            "label": "layout/change",
            "payload": {
              "layout": "calendar"
            }
          }
        }
      }
    }
  }
]

This structure can be inserted within a bk-layout-swap. This component has a property layout and a mirror attribute bootstrap-layout which choose the layout to display. Each layout must be a unique HTML element with a slot property set to the layout it represents. The content of the layout stays inside the relative HTML element.

<bk-layout-swap bootstrap-layout="layout1">
  <div slot="table">
    <bk-table />
  </div>
  <div slot="calendar">
    <bk-calendar />
  </div>
</bk-layout-swap>

when a layout/change event is fired the bk-layout-swap will show only the matching branch amongst is direct children according to the slot attribute.

The initial layout is controlled either by the layout property or the bootstrap-layout attribute.

The configuration looks like this:

[
  {
    "tag": "bk-button", "properties": {...}
  },
  {
    "tag": "bk-layout-swap",
    "properties": {
      "layout": "table"
    },
    "content": [
      {
        "tag": "div",
        "attributes": {
          "slot": "table"
        },
        "content": {
          "tag": "bk-table",
          "properties": {
            ...
          }
        }
      },
      {
        "tag": "div",
        "attributes": {
          "slot": "calendar"
        },
        "content": {
          "tag": "bk-table",
          "properties": {
            ...
          }
        }
      }
    ]
  }
]

There are differences between bk-layout-container and this component:

  1. the inner elements are never in shadow DOM -> disable-shadow-dom is not needed here
  2. there's no composing on layouts after the initialization
  3. this component does not handle the communication layer of components. eventBus is injected by the composer on each component. To isolate components the property eventBus must be tuned locally for each component.
caution

this component, due to the fact it must be loaded in advance, is bundled separately at /bk-layout-swap.esm.js

Let's say we have two layouts with different CRUD clients and we'd like to scope them on different channels

  • a couple of bk-buttons must have the same bus of the bk-layout-swap to swap layouts
  • a bk-table must talk with an instance of a bk-crud-client
  • another bk-table must talk with another instance of a bk-crud-client

That summarizes to

{
  {
    "tag": "bk-crud-client",
    "properties" {
      "reflectToUrl": false,
      "eventBus": "eventBus.pool.table1",
      ...
    }
  },
  {
    "tag": "bk-crud-client",
    "properties" {
      "reflectToUrl": false,
      "eventBus": "eventBus.pool.table2",
      ...
    }
  },
  {
    "tag": "bk-layout-swap",
    "properties": {
      "layout": "table"
    },
    "content": [
      {
        "tag": "div",
        "attributes": {
          "slot": "table"
        },
        "content": {
          "tag": "bk-table",
          "properties": {
            "eventBus": "eventBus.pool.table1",
            ...
          }
        }
      },
      {
        "tag": "div",
        "attributes": {
          "slot": "calendar"
        },
        "content": {
          "tag": "bk-table",
          "properties": {
            "eventBus": "eventBus.pool.table2",
            ...
          }
        }
      }
    ]
  }
}

Properties & Attributes​

propertyattributetypedefaultdescription
layoutbootstrap-layoutstring-default layout to view on landing and then current layout

Listens to​

eventactionemitson error
layout/changerequires the connection of the layout which is referenced in the event payload--

Emits​

This component emits no event.

Bootstrap​

None

bk-loading-animation​

Web component to display a loading animation until one of its children has finished loading. This component is analogous to mlc-loading-animation from micro-lc.

bk-modal​

Generic modal container for custom content and custom footer

<bk-modal></bk-modal>

Properties & Attributes​

propertyattributetypedefaultdescription
content-Taggable | Taggable[]-configurable content of the modal. Supports both object or array, as: {tag: string; properties?: Object; children?: string}
footerCallToAction-CallToAction-alternative way to specify the footer of the modal. This property is to be set programmatically only
footerComponent-null | Taggable | Taggable[] | Object-configurable footer of the modal. Supports both object or array, as: {tag: string; properties?: Object; children?: string}
heightheightstring-height of the modal
loadingloadingbooleanfalsewhether or not the modal is loading
modalIdmodal-idstring-identifier associated to the modal
modalTitle-LocalizedText-title of the modal
requireConfirm-boolean | RequireConfirmOptsfalsewhether or not the modal requires confirmation to close with unsaved data
rootElementSelectorroot-element-selectorstring-root element to append the modal to
subTitle-LocalizedText | Taggable | Taggable[]-sub-title of the modal
titleIcontitle-iconstring-icon to place next to to the title
widthwidthstring-width of the modal
zIndexz-indexnumber-zIndex of the modal

Listens to​

eventactionemitson error
open-modalopens the modal--
close-modalcloses the modal--

Emits​

This component emits no event.

Bootstrap​

None

bk-notification-center​

allows to handle notifications. It works by dealing with a backend source with a simple REST API interface.

notification-center

<bk-notification-center></bk-notification-center>

Notification object​

The expected notification object is of type:

type Notification = {
  _id: string
  creatorId: string
  createdAt: string
  title: string
  readState?: boolean
  content?: string
  onClickCallback?: CallbackHref
}

where

type CallbackHref = {
  content: content: string | {url: string, data: any};
}

onClickCallback field in retrieved notifications allows to controls the navigation destination upon clicking the notification.

Click strategies​

Clicking on a notification within bk-notification-center may trigger a navigation event. Component property clickStrategy controls what navigation method should be executed, which will use as input arguments the value of the field onClickCallback of the clicked notification.

enum ClickStrategies =
  'default' |
  'href' |
  'replace' |
  'push'

An on-click-strategy correspond to what happens when a notification is clicked. default and href create an invisible anchor and click it, replace triggers window.location.replace, push pushes onto window.history stack.

The value of onClickCallback field in a clicked notification is used as input arguments for the triggered navigation method. Consequently, for any value of clickStrategy, the type of onClickCallback can be a string. Additionally, if clickStrategy is push, onClickCallback may also be an object with keys url and data, corresponding to the main arguments of the window.history.pushState method. The value of data will be injected into the state of the destination page through a key set by property pushStateKey.

info

When clickConfig is set to push, bk-notification-center may be used in conjunction with a component such as bk-state-adapter, which consumes the page state to emit custom events.

For instance, given two plugins located at "/plugin-1" and "/plugin-2", with configurations:

  • /plugin-1

    {
      ...
      {
        "tag": "bk-notification-center",
        "properties": {
          ...
          "clickConfig": "push",
          "pushStateKey": "notification-center-state"
        }
      }
      ...
    }

  • /plugin-2

    {
      ...
      {
        "tag": "bk-state-adapter",
        "properties": {
          ...
          "configMap": {
            "notification-center-state": "add-filter"
          }
        }
      }
      ...
    }

clicking in plugin-1 on a notification like:

{
  ...
  "onClickCallback": {
    "url": "/plugin-1",
    "data": {
      "property": "lastname",
      "operator": "equal",
      "value": "Smith"
    }
  }
}

triggers navigation to /plugin-2, and once there an event with label add-filter and payload

{
  "property": "lastname",
  "operator": "equal",
  "value": "Smith"
}

is emitted by bk-state-adapter.

Further control over the navigation behavior is provided by property allowExternalHrefs, controlling whether or not browsing to external external web pages and href is allwed when clickStrategy is default, href or replace.

Partial translations​

PartialTranslations enables the user to apply custom translations within the webcomponent, works by key. Keys are given by the type:

type LanguageKeys =
  'title' |
  'loadingButton' |
  'dateFormat' |
  'errorMessage' |
  'noNotification' |
  'readAll' |
  'reload' |
  'backOnTop'

and to each key, one could attach either a string value (which will override any browser language settings) or a localized string given by a key/value map such as

{
  en: "English Translation",
  'en-AU': "English Translation",
  zh: "中文翻译",
  ...
}

Example​

The following is a valid configuration, in the default title of bk-notification-center is overwritten. The other language keys will still have their default values:

{
  "tag": "bk-notification-center",
  "properties": {
    ...
    "locales": {
      "title": {
        "en": "Notification center title",
        "it": "Titolo centro notifiche"
      }
    }
  }
}

Resource fetching mode​

enum ClickStrategies =
  'polling' |
  'default' |
  'none'

Determines how the data is automatically fetched. If polling, the property pollingFrequency determines the fetching frequency (in milliseconds). If default or none, data is not fetched automatically.

Backend communication​

The notification center needs a backend service to retrieve and interact with notifications. It follows a description of the endpoints called by the component that should be exposed by the service.

Backend base endpoint can be configured using the endpoint property, defaults to /api/v1/bk-notification-center.

GET - /own​

This endpoint should return the list of paged notifications that the currently logged-in user should visualize. The notifications should be ordered by creation date descending.

Query Parameters​

Query parameters skip and limit help querying the notification pagination. These can be configured using properties limitQueryParam, skipQueryParam, limit.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Limits the number of documents, max 200 elements, minimum 1",
      "type": "integer",
      "minimum": 1
    },
    "skip": {
      "description": "Skip the specified number of documents",
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["skip", "limit"]
}
Response​
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "title": {
        "anyOf": [
          {"type": "string"},
          {"type": "object"}
        ]
      },
      "content": {
        "anyOf": [
          {"type": "string"},
          {"type": "object"}
        ]
      },
      "readState": {
        "type": "boolean"
      },
      "createdAt": {
        "type": "string"
      },
      "onClickCallback": {
        "kind": {
          "type": "string",
          "enum": [
            "href"
          ]
        },
        "content": {
          "type": "string"
        }
      }
    },
    "required": [
      "title",
      "createdAt"
    ]
  }
}

PATCH - /read-state/:notificationId​

This endpoint should change the read state of a specific notification given its id.

Body​
{
  "type": "object",
  "properties": {
    "readState": {
      "type": "boolean"
    }
  }
}

PATCH - /read-state/own​

This endpoint should change the read state of all the notifications that the currently logged-in user can retrieve.

{
  "type": "object",
  "properties": {
    "readState": {
      "type": "boolean"
    }
  }
}

Properties & Attributes​

propertyattributetypedefaultdescription
endpointendpointstring/api/v1/bk-notification-centerAPI endpoint for HTTP calls
headers-{ [x: string]: string; }{}headers included in any HTTP request
limitlimitnumber10controls pagination limit while fetching notifications
locales-PartialTranslations{}key-value list to customize components default labels. Keys are paired to either a string, which overrides language support or to a key-value map that matches a language to a translation
clickStrategyclick-strategyClickStrategies'default'enum taking values 'default', 'href', 'replace', 'push', which correspond to what happens when a notification is clicked
limitQueryParamlimit-query-paramstring'limit'the query parameter which controls notification pagination page size while fetching data
skipQueryParamskip-query-paramstring'skip'the query parameter which controls notification pagination skip while fetching data
pushStateKeypush-state-keystring'bk-notification-center'the key used to scope the content callback context in window.history.state when clickStrategy is 'push'. Otherwise it is neglected
allowExternalHrefsallow-external-hrefsstringfalsewhen true, notification links can browse to external web pages and href are not checked to ensure they are relative to self-website
modemodeResourceFetchingMode'default'strategy to implement for automatically fetching notifications
pollingFrequencypollingFrequencynumber10000frequency of notifications automatic fetching (in milliseconds), if mode is set to polling

Listens to​

This component listens to no event.

Emits​

This component emits no event.

Bootstrap​

None

bk-notifications​

displays toast notifications about events happening on the EventBus according to the maps provided as props notifications

<bk-notifications></bk-notifications>

NotificationsMap​

type NotificationsMap {
  [key: string]: {
    title?: LocalizedText
    content?: LocalizedText
    type?: "success" | "error"
  }
}

Properties successEventMap and errorEventMap map the triggeredBy field of success and error events to notification properties, while customEventMap allows to map notifications to the label of other events.

Notification object​

Each notification can be configured with the following properties:

propertytypevaluesdescription
titlelocalizedTextanylocalized text to be used as notification title
contentlocalizedTextanylocalized text to be used as notification content
typestringsuccess, error, info, warningenum of possible notification styling (i.e. icons, color...)

Example​

{
  "successEventMap": {
    "create-data": {
      "title": {
        "en": "Data was created correctly!",
        "it": "Dato creato correttamente!"
      },
      "content": {
        "en": "The data has been created correctly",
        "it": "I dati sono stati creati correttamente"
      },
      "type": "success"
    },
    "update-data": {
      "title": {
        "en": "Data was updated correctly!",
        "it": "Dato aggiornato correttamente!"
      },
      "content": {
        "en": "The data has been updated correctly",
        "it": "I dati sono stati aggiornati correttamente"
      },
      "type": "success"
    },
    "delete-data": {
      "title": {
        "en": "Data was updated correctly!",
        "it": "Dato aggiornato correttamente!"
      },
      "content": {
        "en": "The data has been updated correctly",
        "it": "I dati sono stati aggiornati correttamente"
      },
      "type": "success"
    }
  }
}

Triggering notifications from success and error events​

Some components automatically emit success and error events to notify the result of a generic action, not needing to be configured to do so. For instance, bk-crud-client reacts to events like create-data and update-data by performing REST calls against a configurable endpoint, then emitting a success/error event with the name of the triggering event as value of meta.triggeredBy.

Example​

{
  ...
  {
    "tag": "bk-notifications",
    "properties": {
      "successEventMap": {
        "create-data": {
          "title": "Data correctly created!",
          "content": "The data has been created correctly",
          "type": "success"
        }
      },
      "errorEventMap": {
        "create-data": {
          "title": "Data not created",
          "content": "An error occurred while creating data",
          "type": "error"
        }
      }
    }
  },
  {
    "tag": "bk-crud-client",
    "properties": {
      "dataSchema": ...,
      "basePath": "/some-endpoint"
    }
  }
}

With a configuration like the one in the example, when a create-data event is emitted:

1) bk-crud-client performs a POST call 2) assuming the call to be successful, bk-crud-client emits a success event with meta:

{
  ...
  "triggeredBy": "create-data"
}

3) bk-notifications emits a notification with properties:

{
  "title": "Data correctly created!",
  "content": "The data has been created correctly",
  "type": "success"
}

Triggering notifications from other events​

bk-notifications can be configured to listen to specific events and display notifications when they are received, through the property customEventMap.

Example​

The following configurations displays a notification everytime an event with label add-filter is emitted.

{
  "tag": "bk-notifications",
  "properties": {
    "customEventMap": {
      "add-filter": {
        "title": "Filter applied!",
        "content": "The filter has been created applied",
        "type": "success"
      }
    }
  }
}

Triggering notifications from Actions​

Components that allow to configure Actions, such as bk-button or bk-gallery, may integrate with bk-notifications.

Some actions trigger a success or error event based on their result (for instance, actions of type http). In such cases, it is possible in the action configuration to specify the triggeredBy key that is injected into the meta field of such events, which is then matched by bk-notifications with its properties successEventMap and errorEventMap. On the other hand, actions that emit events can be mapped to notifications leveraging property customEventMap.

Example​

In the following configuration, bk-button component is configured to perform an HTTP call, and bk-notifications to emit a notification that alerts on whether or not the call was successful.

{
  ...
  {
    "tag": "bk-notifications",
    "properties": {
      "successEventMap": {
        "data-fetch": {
          "title": "Data correctly fetched!",
          "content": "The data has been fetch correctly",
          "type": "success"
        }
      },
      "errorEventMap": {
        "data-fetch": {
          "title": "Data not fetched",
          "content": "An error occurred while fetching data",
          "type": "error"
        }
      }
    }
  },
  {
    "tag": "bk-button",
    "properties": {
      ...
      "action": {
        "type": "http",
        "config": {
          "url": "/some-endpoint",
          "method": "GET",
          "triggeredBy": "data-fetch"
        }
      }
    }
  }
}

Properties & Attributes​

propertyattributetypedefaultdescription
customEventMap-NotificationsMap{}map containing the labels of any event that should be notified and the related notificationProps
durationdurationnumber-lingering time for the notification in seconds
errorEventMap-NotificationsMap{}map containing the labels of any event that triggered a error that should be notified with the related notificationproperties
location-"topRight" | "topLeft" | "bottomRight" | "bottomLeft""topRight"corner location where the notification should be displayed
rootElementSelectorsroot-element-selectorsstring-selector to specify where the notification should be appended
successEventMap-NotificationsMap{}map containing the labels of any event that triggered a success that should be notified with the related notificationproperties

Listens to​

eventactionemitson error
successdisplays a notification if the triggeredBy field contained in the meta of the event has been mapped in the successEventMap property--
errordisplays a notification if the triggeredBy field contained in the meta of the event has been mapped in the errorEventMap property--
Configurable custom eventsdisplays a notification on any event mapped in the customEventMap property--

Emits​

This component emits no event.

Bootstrap​

None