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

Value type dropdown

To bind a component property value directly to a variable, click the dropdown to the left of the value input field and choose the variable type you want to bind to.

After this, the value input field changes to a dropdown you can use to select the correct binding.

Bindings are strongly typed: if your page variable is a boolean, you will not be able to bind it to a component property that is expecting a string value.

However, you can use formulas for type casting, e.g. converting a number into a string or a generic string into a date/time string.

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, select one of the static value types from the value type dropdown.

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 value type dropdown, 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 value is bound to current.name, but view canvas will render "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 static array, a formula that resolves to an array of objects, or any dynamic variable whose type is an array 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 array: one component instance is rendered for every object in the array.

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 array 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 array 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.

Some available current.* bindings for the RestCountries data resource

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.