Data Binding

Setup

Tabris provides a JSX/decorators-based declarative data binding via the 'tabris-decorators' extension, which has to be installed in addition to the tabris module:

npm install tabris-decorators

This extension works only with TypeScript/JSX projects. Mixed projects work as well, but the modules using the extension need to be .ts or .tsx files. It’s strongly recommended to familiarize yourself with the basic decorators syntax if you aren’t already.

Basic Principles

Data binding in the context of Tabris.js/tabris-decorators refers to a set of APIs that assists you in writing custom UI components (like forms, lists or custom input elements) that provide a type-safe public API that interacts with the internal child elements of the component. This is done either with one-way bindings in which the value of a component property is applied to a child element, or two-way bindings that synchronizes a component property with a child element property.

A very simple example app using both, one-way and two-way bindings, can be found here.

Bindings can also be established with properties of non-widget object that are attached to a component. In one-way bindings the values may also be be converted or transformed before they are applied to the child element.

Both flavors of bindings rely on property change events to detect changes in the objects involved. The framework can assist you with this as well. In case a specific requirement of your component can not be handled via data binding it also provides easy and safe direct access to any child element.

The Decorators

The following data binding related decorators are exported by tabris-decorators:

  • @component - Class decorators that enables data binding within a custom component.
  • @property - Makes any property a valid source of one-way bindings.
  • @bind - Configures a custom component property for two-way bindings.
  • @bindAll - Shorthand for @bind({all})
  • @event - Auto-initializes a Listeners properties to create a type-safe (change) event APIs.
  • @getById - Auto-initializes a (usually private) custom component property for direct access to a child element.