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

Back-Kit Events

Events are data structures sent into a communication channel to enable event-driven component behavior. They extend an any object and they come as

type Event<P, M> = {
label: string
payload: P
meta?: M
}

where label is a unique string identifying the event such as "create-data" or "delete-file", payload contains transactional data and meta other data with extra information like what action triggered this event, a transaction ID if there's any and so on.

To create a new event within src/events there's a factory method which is a generic function that takes the P and M types with the label

export function factory<P extends Payload = Payload, M extends Meta = Meta> (
label: string, options: FactoryOptions = {}
): Factory<P, M> {
...
}

This function generates a function with hybrid prototype that contains:

  1. an event generator
  2. a predicate .is( to check whether an event was made with the current generator
  3. a label which returns the generator and its spawned events label

for instance

const addNew = factory<Record<string, never>>('add-new')

const addNewEvent = addNew({})

expect(addNew.is(addNewEvent)).toBeTruthy()
expect(addNew.label).toStrictlyEqual('add-new')

There's also the concept of a register which automatically adds event is on factory call the constant

const REGISTERED = true

is provided. In that case, src/events/eventRegister.ts exports an eventBuilderRegister map that contains only registered event generators. It has an .add( method which is idempotent on a factory with the same label already contained in the register.

An eventBus conforming event is an object like

{
label: string,
payload: object,
meta: object,
}
  • label is a unique event identifier. Standard Back-kit events are always kebab-case idiomatic strings,
  • payload is an object, possibly empty,
  • meta helps to keep track of transaction states or enhance event scoping. Meta is not required and its value might be an empty object.

For instance an upload-file event looks like:

{
label: "upload-file",
payload: {
file: {
lastModified: 1627457290180,
lastModifiedDate: "Wed Jul 28 2021 09:28:10 GMT+0200 (Central European Summer Time)",
name: "file.pdf",
size: "9090",
type: "application/json",
uid: "rc-upload-1630930409639-3"
}
},
meta: {
transactionId: "97de9662-70aa-48a0-bdee-25113fc66c8f"
}
}

A

Add Filter

delivers data to add a new filter

  • Label: add-filter
  • Payload:
{
operator:
| "equal"
| "exists"
| "notEqual"
| "greater"
| "greaterEqual"
| "less"
| "lessEqual"
| "regex"
| "includeSome"
| "includeAll"
| "includeExactly"
| "notIncludeAny"
| "between"
| "notBetween"
| "hasLengthEqual"
| "hasLengthGreaterEqual"
| "hasLengthLessEqual"
property: string
value: string | number | boolean | any[]
applied?: boolean
name: string
}
  • Meta:
{
hash: string
}

Add New

notifies adding a new item

  • Label: add-new
  • Payload:
{
[key: string]: any
}

Add New External

notifies adding a new item on an external collection

  • Label: add-new-external
  • Payload:
{
[key: string]: any
}

B

Bulk update - Boolean and Enums

allows to modify enums or boolean values from an array of items

  • Label: bulk-update
  • Payload:
{
data: {
[key: string]: any
}[]
changes: {
[key: string]: string | boolean
}[]
}

C

Cancel

notifies operation abort via a given transactionId

  • Label: event-bus-cancel
  • Payload:
{}
  • Meta:
{
transactionId: string
}

Change Filter

delivers data on an edited filter

  • Label: change-filter
  • Payload:
{
operator:
| "equal"
| "notEqual"
| "greater"
| "greaterEqual"
| "less"
| "lessEqual"
| "regex"
| "includeSome"
| "includeAll"
| "includeExactly"
| "notIncludeAny"
| "between"
| "hasLengthEqual"
| "hasLengthGreaterEqual"
| "hasLengthLessEqual"
property: string
value: string | number | boolean | any[]
applied?: boolean
name: string
}

Change Query

requires a modification of the currently viewed dataset (filtering, sorting, paging)

  • Label: change-query
  • Payload:
{
characteristic?: string
pageNumber?: number
pageSize?: number
search?: string
sortDirection?: SortDirection
sortProperty?: string
filters?: {
operator:
| "equal"
| "notEqual"
| "greater"
| "greaterEqual"
| "less"
| "lessEqual"
| "regex"
| "includeSome"
| "includeAll"
| "includeExactly"
| "notIncludeAny"
| "between"
| "hasLengthEqual"
| "hasLengthGreaterEqual"
| "hasLengthLessEqual"
property: string
value: string | number | boolean | any[]
applied?: boolean
name: string
}[]
}

Close Modal

closes a modal

  • Label: close-modal
  • Payload:
{
modalId: string
}
  • Meta:
{
sessionId?: string
}

Count Data

sends count and pagination of current dataset

  • Label: count-data
  • Payload:
{
total: number
pageSize: number
pageNumber: number
}

Create Data

notifies the request for creation of a new item and carries its value

  • Label: create-data
  • Payload:
{
[key: string]: any
}

Create Data With File

create data that have one or more files within their properties, the current file property is set into meta

  • Label: create-data-with-file
  • Payload:
{
data: {
[key: string]: any
}
}
  • Meta:
{
property: string
}

D

Delete Data

notifies the request for deletion of an item

  • Label: delete-data
  • Payload:
{
[key: string]: any
}
| {
[key: string]: any
}[]

Delete File

notifies that a given file, identified by its unique id, must be deleted

  • Label: delete-file
  • Payload:
{
file: string
}
  • Meta:
{
transactionId: string
}

Deleted File

notifies that a given file was deleted, carries a transaction ID to rollback

  • Label: deleted-file
  • Payload:
{
[key: string]: any
}
  • Meta:
{
transactionId: string
}

Display Data

carries a dataset

  • Label: display-data
  • Payload:
{
data: any
}

Download File

notifies that a given file must be downloaded. Payload could be either the file identifier or a structure that contains it. In the latter case, the object property to find the file must be set into the meta. It carries transaction ID to rollback. Allows to request in-browser view of the file.

  • Label: download-file
  • Payload:
{
file?: string
[key: string]: any
}
  • Meta:
{
transactionId?: string
property?: string
showInViewer?: boolean | "skip-checks"
}

Downloaded File

notifies that a given file was downloaded, carries a transaction ID to rollback

  • Label: downloaded-file
  • Payload:
{
file: string
}
  • Meta:
{
transactionId: string
}

Duplicate Data

notifies the request for duplication of an item and carries its value

  • Label: duplicate-data
  • Payload:
{
[key: string]: any
}

E

Error

notifies a generic error event

  • Label: error
  • Payload:
{
error: any
}
  • Meta:
{
triggeredBy: string
transactionId: string
}

Export Data

raised when the export button is clicked

  • Label: export-data
  • Payload:
{}

Export Data - Request Config

prompts for export configuration payload

  • Label: awaiting-for-export-configuration
  • Payload:
{
total?: number
selected?: number
columns: {
label: string
value: T
}[]
}
  • Meta:
{
transactionId?: string
}

Export Data - User Config

sends user configuration payload to perform export

  • Label: export-user-config
  • Payload:
{
exportType: "json" | "csv" | "html" | "xlsx"
csvSeparator?: "COMMA" | "SEMICOLON"
filters: "all" | "filtered" | "selected"
columns: string[]
columnName: "id" | "label"
dateFormat: string
timezone: string
}
  • Meta:
{
transactionId?: string
}

F

Fetch Files

notifies to requests to fetch files

  • Label: fetch-files
  • Payload:
{
limit?: string | number
page?: string | number
dateFrom?: string
}
  • Meta:
{
transactionId?: string
}

Fetched Files

carries result of files fetching operation

  • Label: fetched-files
  • Payload:
{
files: {
[key: string]: unknown
}[]
}
  • Meta:
{
transactionId?: string
}

Filter

notifies opening of UI component that handles form creation

  • Label: filter
  • Payload:
{}

H

Http Delete

notifies the request for permanent deletion of an item

  • Label: http-delete
  • Payload:
{
[key: string]: any
}
| {
[key: string]: any
}[]

I

Import Data

raised when the import button is clicked

  • Label: import-data
  • Payload:
{}

Import Data - User Config

sends user configuration payload to perform import

  • Label: import-data/user-config
  • Payload:
{
file: File
encoding?: "utf8" | "ucs2" | "utf16le" | "latin1" | "ascii" | "base64" | "hex"
delimiter?: string
escape?: string
}

L

Layout Change

requires a layout change from bk-layout-container

  • Label: layout-change
  • Payload:
{
layout: string
}

sends file upload data

  • Label: link-file-to-record
  • Payload:
{
data: {
[key: string]: any
}
}
  • Meta:
{
property: string
}

Loading Data

notifies whether dataset is loading or not. It also advices that a dataset may be inbound

  • Label: loading-data
  • Payload:
{
loading: boolean
}

Lookup Data

carries lookup data information and dataset

  • Label: lookup-data
  • Payload:
{
[key: string]: any[]
}
  • Meta:
{
dataOrigin?: string
}

Lookup Live Found

fired when options for a Select form input are found

  • Label: lookup-live-found
  • Payload:
{
[key: string]: any[]
}

Lookup Live Searching

fired upon searching on a Select form input

  • Label: lookup-live-searching
  • Payload:
{
property: string
input: string
}
  • Meta:
{
limit: number
input: {
[key: string]: any[]
}
currentValues?: any[]
keys?: string[]
}

N

Nested Navigation State - Display

displays data or a slice of data

  • Label: display-state
  • Payload:
Array<{
data: Record<string, any>[]
from?: number
to?: number
sort?: number[]
}>
  • Meta:
{
keys?: string[]
}

Nested Navigation State - Go Back

goes back an arbitrary number of levels of nesting

  • Label: back-state
  • Payload:
{
steps?: number
}

Nested Navigation State - Push

adds a new level of nesting

  • Label: push-state
  • Payload:
{
data: Record<string, any>[]
origin: Record<string, any>
selectedKey?: string
}

O

Open Modal

opens a modal

  • Label: open-modal
  • Payload:
{
modalId: string
}
  • Meta:
{
sessionId?: string
}

R

Require Confirm

Signals that a certain action requires confirmation to be performed

  • Label: require-confirm
  • Payload:
{
cancelText?: LocalizedText
content?: LocalizedText
okText?: LocalizedText
onCancel?: () => {}
onOk?: () => {}
title?: LocalizedText
configOk?: {
tag: string
properties?: Record<string, any>
children?: string | ReactNode
}
configCancel?: {
tag: string
properties?: Record<string, any>
children?: string | ReactNode
}
}

S

Search Lookups

notifies that all lookups having excludeFromSearch set to false should be searched against a value

  • Label: search-lookups
  • Payload:
{
input: string
}
  • Meta:
{
limit: number
}

Search Lookups Found

fired when values from a text search for lookups are found

  • Label: search-lookups-found
  • Payload:
{
[key: string]: any[]
}
  • Meta:
{
input: string
}

Selected Data

notifies that a single datum has been selected from a dataset

  • Label: selected-data
  • Payload:
{
data: {
[key: string]: any
}
}

Selected Data Bulk

notifies data selection in a dataset

  • Label: selected-data-bulk
  • Payload:
{
data: Array<{
[key: string]: any
}>
}

Show In Viewer

notifies the request for starting/updating the visualization of a PDF file

  • Label: show-in-viewer
  • Payload:
{
show: boolean
url: string
}

Submit Form - Request

requests submission of form

  • Label: submit-form-request
  • Payload:
{}
  • Meta:
{
openingEvent: string
formId: string
}

Submit Form - Success

notifies correct submission of form

  • Label: submit-form-success
  • Payload:
{}
  • Meta:
{
transactionId?: string
}

Success

notifies a successful action

  • Label: success
  • Payload:
{}
  • Meta:
{
triggeredBy: string
transactionId: string
}

U

Update Data

notifies the request for creation of a new item and carries its value

  • Label: update-data
  • Payload:
{
[key: string]: any
}
| {
[key: string]: any
}[]
  • Meta:
{
transactionId: string
}

Update Data With File

update data that have one or more files within their properties, the current file property is set into meta

  • Label: update-data-with-file
  • Payload:
{
data: {
[key: string]: any
}
}
  • Meta:
{
property: string
}

Update State Bulk

updates multiple data state (STATE or _st) in a dataset

  • Label: update-state-bulk
  • Payload:
{
rows: any[]
newState: string
}

Upload File

requests the upload of a file and carries its data.

  • Label: upload-file
  • Payload:

Uploaded File

returns file upload metadata, typically when storing on an external service like files-service

  • Label: uploaded-file
  • Payload:
{
_id: string
name: string
file: string
size: number
location: string
}

Using Form Container

notifies that a form container with given ID is currently in use

  • Label: using-form-container
  • Payload:
{
id: string
}