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

Core concepts

Localization and i18n​

Back-kit web components supports localization and internationalization. Component properties that in turn expose any kind of typography can be easily internationalized by passing a LocalizedText object containing specific translations according to ISO 639-1 codes.

{
  "en": "house",
  "fr": "maison",
  "de": "haus",
  "it": "casa",
  "zh": "房子",
  "ar": "منزل",
  ...
}

Fields that support i18n are marked through this guide as taking either LocalizedText as input type.

Components allow to customize their copies through property customLocale, with support to internationalized strings.

For instance:

{
  "tag": "bk-table",
  "properties": {
    "customLocale": {
      "actionsTitle": {
        "en": "Actions",
        "it": ""
      }
    }
  }
}
info

The example shows how to customize the title of the actions column of a Table. The list of available copies is availbale in the dedicated section of each component documentation.

Not all copies need to be specified. Missing copies are set to their default value, if availbale, or else fallback to the english translation.

Dynamic configuration​

Many components allow the user to build dynamic configurations. Such configurations are really helpful when an event needs to be aware of situation-specific data, such as, while clicking a button onto a given table row, the event must be intertwined with data of that row.

To achieve dynamic configurations logic, Back-Kit components use handlebars syntax and embed a web component property to register a handlebar template. By default, a string is parsed by the handlebar parser without making any changes to it if no {{}}-syntax is present.

For instance, any Back-Kit component is aware of an authenticated user, if any, using the property currentUser. When currentUser has property email with value my-mail@mail.com, a configuration such

{
  "user": "{{curentUser.email}}"
}

would be equivalent to

{
  "user": "my-mail@mail.com"
}

Helpers​

Custom helpers to be used in conjunction with handlebars are provided, most components that allow dynamic configurations support them.

rawObject​

By default, the handlebars interpolation cast everything to string. rawObject allows to avoid to stringify dynamic values within a configuration.

{
  "url": "/url",
  "method": "POST",
  "body": "{{rawObject data}}"
}

rawObject signals that the provided dynamic value (data in this case) should not be stringified. So, with input data:

{
  "data": {
    "name": "Joe",
    "surname": "Smith"
  }
}

the example is equivalent to:

{
  "url": "/url",
  "method": "POST",
  "body": {
    "name": "Joe",
    "surname": "Smith"
  }
}

rawObjectOrEmptyStr​

rawObjectOrEmptyStr is equivalent to rawObject but, if the input value is not defined, an empty string will be put in place of the dynamic configuration.

nFormat​

nFormat allows to format numeric values specifying number of decimal places, decimal separator, group separator.

For instance, given the dynamic configuration:

{
  "amount1": "$ {{nFormat '2.,' value}}",
  "amount2": "$ {{nFormat '4.,' value}}",
  "amount3": "$ {{nFormat '.,' value}}",
  "amount4": "$ {{nFormat '.' value}}",
  "amount5": "$ {{nFormat '' value}}"
}

and input data:

{
  "value": 7654.321
}

the resulting configuration is:

{
  "amount1": "7,654.32",
  "amount2": "7,654.3210",
  "amount3": "7,654.321",
  "amount4": "7654.321",
  "amount5": "7654.321"
}

$dateNow​

$dateNow allows to get the current date and time in ISO format.

For instance, given the dynamic configuration:

{
  "dateTime": "{{ $dateNow }}",
}

the resulting configuration is:

{
  "dateTime": "2024-10-15T12:37:41.302Z",
}

Template - ConfigMap​

Some components allow to specify an object with fields template-configMap instead of a value for their dynamically configurable properties.

{
  "command": {
    "template": "{{color}}",
    "configMap": {
      "red": "stop",
      "yellow": "slow-down",
      "$default": "go"
    }
  }
}

The value of template is matched against keys of configMap. On the first match, the corresponding value in configMap is used as value for the dynamic variable.

For instance, with context

{
  "color": "red"
}

the above example is equivalent to:

{
  "command": "stop"
}

$default key in configMap can be specified, and is used if no other configMap key matches template.

Extracting data from URL - UrlMask​

Some components may expose properties that allow to configure a urlMask. This leverages path-to-regexp syntax to convert a string input (or mask) into a regular expression to be matched against the current URL, allowing to extract information from it, making it availbale in dynamic configurations.

urlMasks allow to specify masks for the pathname and search fields of window.location.

type UrlMask = string | {
  pathname?: string,
  search?: string
}

If urlMask is a string, it is matched against both pathname and search fields.

Example​

A urlMask such as

{
  "urlMask": {
    "pathname": "/path-name/:field1/:field2",
    "search": "\\?pageSize=:pSize&sortDirection=:sDirection"
  }
}

matched againsta a window.location like

{
  "pathname": "/path-name/field-1/field-2",
  "search": "?pageSize=25&sortDirection=descend"
}

will produce as output

{
  "path": "/path-name/field-1/field-2",
  "params": {
    "field1": "field-1",
    "field2": "field-2"
  }
}

from pathname and

{
  "path": "?pageSize=25&sortDirection=descend",
  "params": {
    "pSize": "25",
    "sDirection": "descend"
  }
}

from search.

Some components may allow to ignore part of the URL using wildcards, "(.*)". For instance:

{
  "urlMask": "\\?pageNumber=:myPageNumber&pageNumber=(.*)"
}

A standard interface is available for encoding external links and href. This interface can be found as building block of several Back-Kit web components properties.

A basic external href link rendering in a browser new tab can be implemented as

{
  "href": "https://www.mia-platform.eu/",
  "target": "_blank",
  "icon": "fas fa-link"
}

Property href can either be absolute or relative, target can be picked amongst _blank, _self, _parent, _top: most commonly either an href renders into the same window with _self or it opens a new tab with _blank.

The icon properties allow to attach a Fontawesome fas or far icon when the link is rendered by a component which support this interface.

A web component that contains state or data might implement dynamic configurations. In this case the href can be enriched with query parameters that are bound to the internal state of the component with which the user is interacting. Suppose the user with email my-mail@mail.com is in session, then the following link

{
  "href": "customers",
  "query": {
    "name": "John",
    "createdBy": "admin|{{currentUser.email}}"
  }
}

renders the dynamic link ./ingredients?name=John&createdBy=admin%7Cmy-mail%40mail.com.

Filters​

Back-kit web components refine data queries and data views using filters. Filters can be used to enrich a change-query and are building blocks of many tag properties. A filter is made of three required build blocks:

  1. property: the unique identifier of the property they filter
  2. operator: the operator used to filter
  3. value: the value or the regex pattern (where it applies) to filter for

Operators and values vary according to the property type which is set by the data schema. If a DataSchema should be filtered only according with a subset of available operators, a configuration key it available within the field filtersOptions. The key availableOperators is an array of string which, if defined, enables only explicitly selected operators on the given field.

Filter Operators​

Filter operators can be selected from the following list:

type FilterOperator = |
  'equal' |
  'exists' |
  'notEqual' |
  'greater' |
  'greaterEqual' |
  'less' |
  'lessEqual' |
  'regex' |
  'includeSome' |
  'includeAll' |
  'includeExactly' |
  'notIncludeAny' |
  'between' |
  'notBetween' |
  'hasLengthEqual' |
  'hasLengthGreaterEqual' |
  'hasLengthLessEqual'

Inline queries​

Some components allow to filter data based on inline queries - that is, queries that are directly applied to the data in the state of the component, no call to the backend is performed.

The supported syntax for inline queries is mongo-like, and their implementation is based on the SiftJS library.

Supported operators are:

Most components allow queries to include dynamic values. If that is the case, it is the components responsibility to ensure that sufficient context is provided to resolve the query.

For instance, the following query

{
  "$or": [
    {"$name": "{{searchedName}}"},
    {"age": {"$gte": 25}}
  ]
}

provided with context:

{
  "searchedName": "Foo"
}

is equivalent to:

{
  "$or": [
    {"$name": "Foo"},
    {"age": {"$gte": 25}}
  ]
}

Just like a regular mongo query, applying such it to data:

[
  {"name": "Foo", "age": 15},
  {"name": "Bar", "age": 27},
  {"name": "Que", "age": 18},
  {"name": "Asd", "age": 10}
]

matches:

[
  {"name": "Foo", "age": 15},
  {"name": "Bar", "age": 27}
]