<commit_before>---
title: Data Binding
description: NativeScript Documentation - Data Binding
position: 4
slug: binding
previous_url: /bindings
environment: nativescript
---

#Data Binding

Data binding is the process of connecting application user interface (UI) to a data object (code). It enables changes propagation by reflecting UI modifications on the code and vise versa.

> In the following article **source** is used as any object in the code, and **target** as any UI control (like TextField).

* [Data Flow Direction](#data-flow-direction)
* [Basic Binding Concepts](#basic-binding-concepts)
* [How to Create a Binding](#how-to-create-a-binding)
    * [Two-Way Binding in Code](#two-way-binding-in-code)
    * [Binding in XML](#binding-in-xml)
* [Binding Source](#binding-source)
	* [Binding to a Property](#binding-to-a-property)
	* [Binding to an Event in XML](#binding-to-an-event-in-xml)
	* [Binding to a Plain Object](#binding-to-a-plain-object)
	* [Binding to a Parent Binding Context](#binding-to-a-parent-binding-context)
* [Using Expressions for Bindings](#using-expressions-for-bindings)
* [Using Converters in Bindings](#using-converters-in-bindings)
* [Stop Binding](#stop-binding)

##Data Flow Direction

Part of the data binding settings is the way data flows. NativeScript data binding supports the following data transmissions.

* **One-Way** - this is the default setting, which ensures that the target property updates when a change in the source property occurs. However, UI modification will not update the code and it will stop the binding connection.

* **Two-Way** - this setting ensures the reflection of changes in both directions - from target to source and source to target. You can use two-way data binding when you need to handle user input.

##Basic Binding Concepts

Generally almost every UI control could be bound to a data object (all NativeScript controls are created with data binding in mind). After your code has ,et the following requirements, you can use data-binding out of the box.

* The target object has to be a successor of the **Bindable** class. All NativeScript UI controls already inherit from this class.
* For **two-way** data binding, the target property should to be a **dependency property**.
* For **one-way** binding, using a plain property is sufficient.
* The data object should raise a **propertyChange** event for every change in the value of its property in order to notify all of the listeners, interested in the change.

##How to Create a Binding

###Two-Way Binding in Code

The example below consists of a `Label`, `TextField` and a source property to which the UI controls are bound. The purpose will be, when the user enters an input in the `TextField`, to update the property in the code and the `Label` text.

First, the **source** object is created with a **textSource** property. A constant flow of progating changes from the source property to the Label is necessary. Thus the property in the code has to raise a **propertyChange** event, in order to notify the `Label` for the changes. To raise this event, an built-in class is used, which provides this functionality - `Observable`.

``` JavaScript
var observableModule = require("data/observable");
var source = new observableModule.Observable();
source.textSource = "Text set via twoWay binding";
```
``` TypeScript
import observableModule = require("data/observable");
var source = new observableModule.Observable();
source.textSource = "Text set via twoWay binding";
```

Next, **target** objects are created to bind to the source property. In this case these will be a `Label` and a `TextField`, which inherit from the `Bindable` class (as all of the UI controls do).

``` JavaScript
//create the TextField
var textFieldModule = require("ui/text-field");
var targetTextField = new textFieldModule.TextField();

//create the Label
var labelModule = require("ui/label");
var targetLabel = new labelModule.Label();
```
``` TypeScript
//create the TextField
import textFieldModule = require("ui/text-field");
var targetTextField = new textFieldModule.TextField();

//create the Label
import labelModule = require("ui/label");
var targetLabel = new labelModule.Label();
```
After that the target objects bind to the source object. The TextField uses a two-way binding, so the user input could change the property in the code. And the binding of the Label is set to one-way in order to propagate changes only from the code to the UI.

``` JavaScript
//binding the TextField
var textFieldBindingOptions = {
	sourceProperty: "textSource",
	targetProperty: "text",
	twoWay: true
};
targetTextField.bind(textFieldBindingOptions, source);

//binding the Label
var labelBindingOptions = {
	sourceProperty: "textSource",
	targetProperty: "text",
	twoWay: false
};
targetLabel.bind(labelBindingOptions, source);
```
``` TypeScript
//binding the TextField
var textFieldBindingOptions = {
	sourceProperty: "textSource",
	targetProperty: "text",
	twoWay: true
};
targetTextField.bind(textFieldBindingOptions, source);

//binding the Label
var labelBindingOptions = {
	sourceProperty: "textSource",
	targetProperty: "text",
	twoWay: false
};
targetLabel.bind(labelBindingOptions, source);
```

###Binding in XML

To create a binding in XML, a source object is needed, which will be created the same way, as in the exmple above ([Two-Way Binding in Code](#two-way-binding-in-code)). Then the binding is described in the XML (using a mustache syntax). With an XML declaration only the names of the properties are set- for the target: text and for source: textSource. The interesting thing here is that the source of the binding is not specified explicitly. More about this topic will be discussed in the next article ([Binding source](#binding-source)).


``` XML
<Page>
	<StackLayout>{%raw%}
		<TextField text="{{ textSource }}" />
{%endraw%}	</StackLayout>
</Page>
```

> Note: When creating UI elements with an XML declaration, the data-binding is two-way by default.

##Binding source

###Binding to a Property

An important part of the data binding is setting the source object. For a continuous flow of data changes, the source property needs to emit a **propertyChange** event. NativeScript data-binding works with any object that emits this event. Adding a binding **source** happens by passing it as a second parameter in the method **bind(bindingOptions, source)**. This parameter is optional and could be omited, in which case for source is used a property named **bindingContext** of the `Bindable` class. What is special about this property is that it is inheritable across the visual tree. This means that a UI control can use the `bindingContext` of the first of its **parent** elements, which has an explicitly set **bindingContext**. In the example from [Two-Way Binding in Code](#two-way-binding-in-code), the `bindingContext` can be set either on a `Page` instance or a `StackLayout` instance and the `TextField` will inherit it as a proper source for the binding of its "text" property.

``` JavaScript
page.bindingContext = source;
//or
stackLayout.bindingContext = source;
```
``` TypeScript
page.bindingContext = source;
//or
stackLayout.bindingContext = source;
```
###Binding to an Event in XML
<commit_msg>Fixed a minor spelling mistake<commit_after>---
title: Data Binding
description: NativeScript Documentation - Data Binding
position: 4
slug: binding
previous_url: /bindings
environment: nativescript
---

#Data Binding

Data binding is the process of connecting application user interface (UI) to a data object (code). It enables changes propagation by reflecting UI modifications on the code and vise versa.

> In the following article **source** is used as any object in the code, and **target** as any UI control (like TextField).

* [Data Flow Direction](#data-flow-direction)
* [Basic Binding Concepts](#basic-binding-concepts)
* [How to Create a Binding](#how-to-create-a-binding)
    * [Two-Way Binding in Code](#two-way-binding-in-code)
    * [Binding in XML](#binding-in-xml)
* [Binding Source](#binding-source)
	* [Binding to a Property](#binding-to-a-property)
	* [Binding to an Event in XML](#binding-to-an-event-in-xml)
	* [Binding to a Plain Object](#binding-to-a-plain-object)
	* [Binding to a Parent Binding Context](#binding-to-a-parent-binding-context)
* [Using Expressions for Bindings](#using-expressions-for-bindings)
* [Using Converters in Bindings](#using-converters-in-bindings)
* [Stop Binding](#stop-binding)

##Data Flow Direction

Part of the data binding settings is the way data flows. NativeScript data binding supports the following data transmissions.

* **One-Way** - this is the default setting, which ensures that the target property updates when a change in the source property occurs. However, UI modification will not update the code and it will stop the binding connection.

* **Two-Way** - this setting ensures the reflection of changes in both directions - from target to source and source to target. You can use two-way data binding when you need to handle user input.

##Basic Binding Concepts

Generally almost every UI control could be bound to a data object (all NativeScript controls are created with data binding in mind). After your code has ,et the following requirements, you can use data-binding out of the box.

* The target object has to be a successor of the **Bindable** class. All NativeScript UI controls already inherit from this class.
* For **two-way** data binding, the target property should to be a **dependency property**.
* For **one-way** binding, using a plain property is sufficient.
* The data object should raise a **propertyChange** event for every change in the value of its property in order to notify all of the listeners, interested in the change.

##How to Create a Binding

###Two-Way Binding in Code

The example below consists of a `Label`, `TextField` and a source property to which the UI controls are bound. The purpose will be, when the user enters an input in the `TextField`, to update the property in the code and the `Label` text.

First, the **source** object is created with a **textSource** property. A constant flow of progating changes from the source property to the Label is necessary. Thus the property in the code has to raise a **propertyChange** event, in order to notify the `Label` for the changes. To raise this event, an built-in class is used, which provides this functionality - `Observable`.

``` JavaScript
var observableModule = require("data/observable");
var source = new observableModule.Observable();
source.textSource = "Text set via twoWay binding";
```
``` TypeScript
import observableModule = require("data/observable");
var source = new observableModule.Observable();
source.textSource = "Text set via twoWay binding";
```

Next, **target** objects are created to bind to the source property. In this case these will be a `Label` and a `TextField`, which inherit from the `Bindable` class (as all of the UI controls do).

``` JavaScript
//create the TextField
var textFieldModule = require("ui/text-field");
var targetTextField = new textFieldModule.TextField();

//create the Label
var labelModule = require("ui/label");
var targetLabel = new labelModule.Label();
```
``` TypeScript
//create the TextField
import textFieldModule = require("ui/text-field");
var targetTextField = new textFieldModule.TextField();

//create the Label
import labelModule = require("ui/label");
var targetLabel = new labelModule.Label();
```
After that the target objects bind to the source object. The TextField uses a two-way binding, so the user input could change the property in the code. And the binding of the Label is set to one-way in order to propagate changes only from the code to the UI.

``` JavaScript
//binding the TextField
var textFieldBindingOptions = {
	sourceProperty: "textSource",
	targetProperty: "text",
	twoWay: true
};
targetTextField.bind(textFieldBindingOptions, source);

//binding the Label
var labelBindingOptions = {
	sourceProperty: "textSource",
	targetProperty: "text",
	twoWay: false
};
targetLabel.bind(labelBindingOptions, source);
```
``` TypeScript
//binding the TextField
var textFieldBindingOptions = {
	sourceProperty: "textSource",
	targetProperty: "text",
	twoWay: true
};
targetTextField.bind(textFieldBindingOptions, source);

//binding the Label
var labelBindingOptions = {
	sourceProperty: "textSource",
	targetProperty: "text",
	twoWay: false
};
targetLabel.bind(labelBindingOptions, source);
```

###Binding in XML

To create a binding in XML, a source object is needed, which will be created the same way, as in the example above ([Two-Way Binding in Code](#two-way-binding-in-code)). Then the binding is described in the XML (using a mustache syntax). With an XML declaration only the names of the properties are set- for the target: text and for source: textSource. The interesting thing here is that the source of the binding is not specified explicitly. More about this topic will be discussed in the next article ([Binding source](#binding-source)).


``` XML
<Page>
	<StackLayout>{%raw%}
		<TextField text="{{ textSource }}" />
{%endraw%}	</StackLayout>
</Page>
```

> Note: When creating UI elements with an XML declaration, the data-binding is two-way by default.

##Binding source

###Binding to a Property

An important part of the data binding is setting the source object. For a continuous flow of data changes, the source property needs to emit a **propertyChange** event. NativeScript data-binding works with any object that emits this event. Adding a binding **source** happens by passing it as a second parameter in the method **bind(bindingOptions, source)**. This parameter is optional and could be omited, in which case for source is used a property named **bindingContext** of the `Bindable` class. What is special about this property is that it is inheritable across the visual tree. This means that a UI control can use the `bindingContext` of the first of its **parent** elements, which has an explicitly set **bindingContext**. In the example from [Two-Way Binding in Code](#two-way-binding-in-code), the `bindingContext` can be set either on a `Page` instance or a `StackLayout` instance and the `TextField` will inherit it as a proper source for the binding of its "text" property.

``` JavaScript
page.bindingContext = source;
//or
stackLayout.bindingContext = source;
```
``` TypeScript
page.bindingContext = source;
//or
stackLayout.bindingContext = source;
```
###Binding to an Event in XML

{'fraction_non_alphanumeric': 0.09294960066097493, 'fraction_numerical': 0.00013770311209033325, 'mean_word_length': 4.854494155582427, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 17, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6168248', 'n_tokens_mistral': 3844, 'n_tokens_neox': 3676, 'n_words': 1878}