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 LocalizedString
(or 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 string
or LocalizedString
as input type.
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
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"
}
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.
urlMask
s 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=(.*)"
}
Links
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 queries. In this case the href
can be
enriched with query parameters that are bound to the internal state of the component that the user is interacting with.
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
.
Shared Properties
Back-kit web components always retain an eventBus
property. For this reason it is not listed on components. Moreover,
configuration should never interact with this property directly, since it is injected by the element-composer on
configuration parsing. Anyway components mark this property as immutable and JavaScript should not be able to tamper with it.
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:
property
: the unique identifier of the property they filteroperator
: the operator used to filter (i.e., "equal", "includeSome", ...)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.
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'
File Management
Upload and management of files related to a record is handled by 3 components that interact together:
bk-file-client
bk-file-manager
bk-form-drawer
Any file property can be specified in the data schema as:
type: 'object'
format: 'file'
Once a file property is specified in the data schema and its form field is touched the routine will be as follows:
bk-form-drawer
fires acreate-data-with-file
/update-data-with-file
event containing the full payload and list of all thefile
properties that have to be uploaded- The above event is handled by the
file-manager
which will proceed to fire anupload-file
event for each file in the list - The
file-client
handles theupload-file
event by taking its payload (the file object) and upload it to the file service, upon success will fire anuploaded-file
event, containing the fileId to be linked to the record - The
file-manager
listens foruploaded-file
events and links each file to the proper record key, replacing it in the payload that was provided by thebk-form-drawer
- Once all the files have been uploaded, the
file-manager
fires acreate-data
/update-data
event with the full payload as thebk-form-drawer
would have, with the file objects correctly linked
:::caution By design, any file that is unlinked from the record when updating an entry, isn't deleted from the file-service :::