Skip to content
This repository was archived by the owner on Nov 17, 2022. It is now read-only.

Improved some parts of documentation. #19

Merged
merged 1 commit into from
Jan 14, 2015
Merged

Improved some parts of documentation. #19

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 14 additions & 16 deletions bindings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,25 @@ position: 6

##Overview

Data binding is the process of connecting application user interface (UI) to a data object (business model). With a correct data binding settings and if data provides proper notifications when data changes then application UI will reflect changes accordingly (source to target). Depending on settings and requirements there is a possibility to update data from UI to data object (target to source). Where source is the business logic object, and target is an UI control like TextField.
Data binding is the process of connecting application user interface (UI) to a data object (business model). With a correct data binding settings and if data object provides proper notifications then when data changes application UI will reflect changes accordingly (source to target). Depending on settings and requirements there is a possibility to update data from UI to data object (target to source).

> **source** is used as any business logic object, and **target** as any UI control (like TextField).

##Basic data binding concepts

Generally almost every UI control (since all controls are created with data binding in mind) could be bound to a data object. However there are few restrictions for data binding to work out of the box.

* Target object should be a successor of **Bindable** class.
* Target property should be a **dependency property** in order to use data binding from target to source (or two way data binding).
* Target property should be a **dependency property** in order to use data binding from target to source (or two way data binding). A plain property could be used if there is no need of **twoWay** binding.
* Data (business) object should raise **propertyChanged** event for every change in the value of the property.

##Direction of data flow

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

* OneWay - this is a setting that indicates that a change in the source object will update target property, but a change in target property will not be propagated back to source (data object). Any update to the target property (except binding) will stop the binding connection. - this is the **default** option.
* **OneWay** - this is a setting that indicates that a change in the source object will update target property, but a change in target property will not be propagated back to source (data object). Any update to the target property (except binding) will stop the binding connection. - this is the **default** option.

* TwoWay - this setting indicates that both changes in source object will be reflected to the target and changes from target will update the source object. Very useful in cases when user input should be handled (for example user writes a text - text is written within a TextField control and is updated to a underlying data property of the source object).
* **TwoWay** - this setting indicates that both changes in source object will be reflected to the target and changes from target will update the source object. Very useful in cases when user input should be handled (for example user writes a text - text is written within a TextField control and is updated to a underlying data property of the source object).
In order to use this option binding options should set **twoWay as true**. Following examples show how to do that.

##Creating a binding
Expand Down Expand Up @@ -74,7 +76,7 @@ In order to use this option binding options should set **twoWay as true**. Follo
targetTextField.bind(bindingOptions, source);
source.set("textSource", "Text set via binding");
```
This example will update targetTextField.text property with a "Text set via binding" value, **twoWay** option ensures that every change of the targetTextField.text property (via user input) will be stored within source.text property. The new value of the text property could be get via:
This example will update **targetTextField.text** property with a *"Text set via binding"* value, **twoWay** option ensures that every change of the **targetTextField.text** property (via user input) will be stored within **source.text** property. The new value of the text property could be get via:

``` JavaScript
source.get("textSource");
Expand All @@ -91,11 +93,9 @@ This example will update targetTextField.text property with a "Text set via bind

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

Expand All @@ -105,7 +105,7 @@ With an xml declaration we set only properies names both for target (text) and s

##Binding source

The important part of the data binding is setting the source object. NativeScript data binding works with any object that emits a **propertyChanged** event. On the process of creating binding source can be set as second parameter of the bind(bindingOptions, source) or could be omitted. In that case for source is used a special property named **bindingContext** of the Bindable class. The special about this property is that it is inheritable across the visual tree. This means that control can use the **bindingContext** of the first **parent** element with a valid **bindingContext**. With the previous example **bindingContext** can be set either on Page instance or StackPanel instance and TextField will have a proper source for its "text" property binding.
The important part of the data binding is setting the source object. NativeScript data binding works with any object that emits a **propertyChanged** event. On the process of creating binding source can be set as second parameter of the bind(bindingOptions, source) or could be omitted. In that case for source is used a special property named **bindingContext** of the Bindable class. The special about this property is that it is inheritable across the visual tree. This means that control can use the **bindingContext** (as source) of the first **parent** element with a explicitly set **bindingContext**. With the previous example **bindingContext** can be set either on Page instance or StackPanel instance and TextField will have a proper source for its "text" property binding.

``` JavaScript
page.bindingContext = source;
Expand All @@ -120,7 +120,7 @@ stackPanel.bindingContext = source;

* Create a data binding to an event in xml

There is an option to bind a function to execute on a specific event (MVVM command like). This option is available only through xml declaration (code behind has different way to hook for events). The different part is that the source property should have an event handler function as value.
There is an option to bind a function to execute on a specific event (MVVM command like). This option is available only through an xml declaration. The different part is that the source property should have an event handler function as value.

``` JavaScript
page.bindingContext = source;
Expand All @@ -139,11 +139,9 @@ and how xml will look like:

``` XML
<Page>
<StackPanel>
{%raw%}
<Button text="Test Button For Binding" tap={{ onTap }}
{%endraw%}
</StackPanel>
<StackPanel>{%raw%}
<Button text="Test Button For Binding" tap={{ onTap }} />
{%endraw%} </StackPanel>
</Page>
```

Expand Down