Binding data

A key concept in Composer is the ability to bind component properties to data stored in variables.

The basic use case is binding a property directly to a variable. For example, I can bind a Title component's Content property to my CurrentCar.brand data variable.

Bindings are resolved automatically. For example, whenever I fetch new data from the backend and store it to my data variable using the Set data variable flow function, the component updates to show the new data.

If you're familiar with React, you might be wondering where you should define your state management logic.

In Composer, this is all handled internally. There's no need to define anything – you just bind your data, and when the bound variable changes, your component state updates too.

Binding component properties

The binding editor view for a Content property

To bind a component property value directly to a variable, click the binding icon to the left of the value input field, this opens up the binding editor.

From the binding editor you can choose the binding type, for example a page variable (under Data and Variables).

Bindings are typed: if your page variable is type True/false and the component property is expecting type Text, then the binding editor will indicate the page variable as "incompatible".

However, formulas can return different types, and can be used to convert values to an appropriate type for the binding.

Formulas and incompatible types

Formulas show a warning if they resolve to a type that's incompatible with the current property binding. Similarly, a warning is shown if the formula result type is unknown, such as when accessing a property of an object without explicit schema, since such a property can be "anything".

However, you can still bind incompatible data to properties via formulas – you can just ignore the warnings and click OK, and the binding will be resolved normally in the runtime.

This is not advised, though, and passing incompatible data to a component (or a flow function) can cause erroneous behaviour or even crash the application.

To remove the binding, use the binding editor to select one of the static value types (Text, Number).

Binding component styles

Component style properties can be bound directly only to theme variables.

To bind a style property, click the link icon next to the value input field, and pick the desired option from the dropdown. The input field will change to show the calculated value of the theme variable as a placeholder text.

To remove the binding, click the link icon again and select Component default value or Custom value.

Binding formulas

An extremely powerful feature of Composer is to bind formulas to component properties.

For example, I might have dates in ISO 8601 format in the data that's coming in from my backend, e.g. 2019-11-28T15:00:39.442Z stored in pageVars.lastPurchaseAt.

To display this in a nice format in the app, I can select Formula from the binding editor, and write e.g.

FORMAT_DATETIME_LOCAL(pageVars.lastPurchaseAt, "MM/DD/YYYY HH:mm"),

which results in my UI displaying 11.28.2019 17:00.

Formula bindings are recalculated automatically when any of the dynamic parameters change. Thus, whenever I update my lastPurchaseAt page variable, my UI will automatically update accordingly.

Formulas can be used in style bindings, too – for example, you could use systemVars.runtime in your formula to render different styles if the app is running on native vs. mobile.

Preview value

Below a bound value for a component property, there is another input that lets you enter a preview value.

The preview value is rendered on the view canvas only, and is useful when you want your view to look as close as possible to what the actual app will look like during runtime.

The label is bound to a page variable, but UI will display "Finland".

Emptying the preview value will show the binding key or formula directly on the view canvas, e.g. current.name or AVERAGE(pageVars.prices).

Repeated components

A component can be set to repeat itself based on your app data via the Repeat with component property.

By default, the Repeat with property is set to Not repeated, so only a single instance of the component is rendered.

To make the component repeat, change the value type to one of the available options. You can repeat from a List, a formula that resolves to a List of Objects, or any dynamic variable whose type is a List of Objects.

A repeating component renders three copies of itself with a blue stripe overlay

Runtime vs. view canvas

The number of repeated components during app runtime is based on the length of the List: one component instance is rendered for every object in the List.

In the view canvas, however, repeated components always render three extra instances, overlaid with blue stripes, to denote that "here will be some number of repeated items".

If the source List is empty, no components will be rendered during runtime.

Like other bound properties, repeated components react to changes in the source binding: adding an item to the source List will cause an additional component to be rendered.

Currently repeated property value

A repeating component has a new special value type available for its properties: Currently repeated property value.

For each rendered instance of the repeated component, this property type resolves to a different value, based on which item in the source array is the "current" one.

For example, if you are repeating from an array of countries where the country object has a name field, and you bind your repeated list component to display Currently repeated property value name, the first list item will show the first country's name, the second one the second country's name, and so forth.

Choosing the bound field

After selecting this value type, the value input changes to a dropdown where you can choose one of the fields in the repeated array's schema.

For example, if you were repeating an array of countries from the RestCountries data resource (available on the marketplace), you would see fields like name and nativeName and alpha2Code.

Example of properties of the "current" variable

Usage within formulas

Currently repeated property values are available under the current namespace in formulas.

Usage within flow functions

When a component is repeating, any flow functions run in its context also have the currently repeated property values available.

Thus, if you are repeating a list of data from the backend, you can easily pass the ID of the selected record to a new page by passing current.id as a page parameter via the Open page node.

Nested repeats

If the objects in your source array contain another array of objects, you can create a nested repeat.

The steps to do this are:

  1. Repeat a container

  2. In the repeated container, select a child component

  3. For the child component's Repeat with property, choose Currently repeated property value as the value type

  4. Set a Repeat as key, such as currentLanguage.

  5. Choose a key that contains an array of objects, such as languages when repeating countries

Now, a new binding option appears in the context of the nested-repeated component, which is Currently repeated property value of 'currentLanguage', or whatever you named your Repeat as.

The nested repeat values are available in formulas under the repeated namespace, e.g. repeated.currentLanguage.nativeName.