# Data Binding

- What is Data Binding?
- Basic Data Binding Concepts
- Creating a Data Binding
- Specifying the path expression of data binding

### What is Data Binding?

Data Binding is the process that establishes a connection between the application UI and business logic. If the binding has the correct settings and the data provides the proper notifications, then, when the data changes its value, the elements bound to the data reflect changes automatically. Data binding can also mean that if an outer representation of the data in an element changes, then the underlying data can be automatically updated to reflect the change. For example, if the user edits the value in a Text element, the underlying data is automatically updated to reflect that change.

A typical use of data binding is to place server or local configuration data into forms or other UI controls. In XWT, this concept is expanded to include the binding of a broad range of properties to a variety of data sources. In XWT, dependency properties of elements can be bound to CLR objects and XML data.

### Basic Data Binding Concepts

Regardless of what element you are binding and the nature of your data source, each binding always follows the model illustrated by the following figure:

As illustrated by the above figure, data binding is essentially the bridge between your binding target and your binding source. The figure demonstrates the following fundamental XWT data binding concepts.

- Typically, each binding has these four components: a binding target object, a target property, a binding source and a path to the value in the binding source to use.
- The target property must be a dependency property. Most UIElement properties are dependency properties and most dependency properties, except read-only ones, support data binding by default.
- Although not specified in the figure, it should be noted that the binding source object is not restricted to being a custom CLR object. XWT data binding supports data in the form of CLR objects and XML.

It is important to remember that when you are establishing a binding, you are binding a binding target to a binding source. For example, if you are displaying some underlying XML data in a Text using data binding, you are binding your Text to the XML data.

To establish a binding, you use the Binding object. The rest of this topic discusses many of the concepts associated with and some of the properties and usage of the Binding object.

Direction of the Data Flow

As mentioned previously and as indicated by the arrow in the figure above, the data flow of a binding can go from the binding target to the binding source or from the binding source to the binding target if the binding source provides the proper notifications.

You may want your application to enable users to change the data and propagate it back to the source object. Or you may not want to enable users to update the source data. You can control this by setting the Mode property of your Binding object. XWT supports three ways to handle the binding: `One Way`, `One Time` and `Two Way`.

- `One Way` binding causes changes to the source property to automatically update the target property, but changes to the target property are not propagated back to the source property. This type of binding is appropriate if the control being bound is implicitly read-only. For instance, you may bind to a source such as a stock ticker or perhaps your target property has no control interface provided for making changes, such as a data-bound background color of a table. If there is no need to monitor the changes of the target property, using the OneWay binding mode avoids the overhead of the TwoWay binding mode.
- `One Time` bind causes changes to the source property to the target property only at the startup, and any changes to the source property are ignored once the control is filled with data the first time.
- `Two Way` binding causes changes to either the source property or the target property to automatically update the other. This type of binding is appropriate for editable forms or other fully-interactive UI scenarios. All properties default to `TwoWay` binding.

### Creating a Data Binding

In XWT project, you establish a data binding using the Binding object, and each binding usually has four components: binding target, target property, binding source, and a path to the source value to use. This section discusses how to set up a data binding.

    <Shell xmlns="http://www.eclipse.org/xwt/presentation"
        xmlns:x="http://www.eclipse.org/xwt"
        xmlns:y="clr-namespace:org.eclipse.e4.xwt.tests.databinding"
        Size="400, 300" DataContext="{StaticResource myData}">
        <Shell.layout>
            <GridLayout numColumns="3" />
        </Shell.layout>

        <x:Shell.Resources>
            <y:Person x:Key="myData" />
        </x:Shell.Resources>

        <Label text="Name" />
        <Text x:style="BORDER" text="{Binding Path=name}">
            <Text.layoutData>
                <GridData horizontalAlignment="FILL" grabExcessHorizontalSpace="true" />
            </Text.layoutData>
        </Text>
        <Label text="{Binding Path=name}">
            <Label.layoutData>
                <GridData horizontalAlignment="FILL" grabExcessHorizontalSpace="true" />
            </Label.layoutData>
        </Label>
    </Shell>

Notice that in the previous example, the binding source is specified by setting the text property on the Text element. To reiterate, the binding source object is necessary components of a binding. Therefore, without the binding source object being specified, the binding would do nothing.

we associate a new Person object in Shell to a key "myData" to a property initialization.

        <x:Shell.Resources>
            <y:Person x:Key="myData" />
        </x:Shell.Resources>

But you must define the DataContext first, then the data binding can works.

        DataContext="{StaticResource myData}"

In this example we specify the binding source by setting the source property directly on the binding declaration of Text and Label. There are several ways to specify the binding source object. Also can using one property on a parent element is useful when you are binding multiple properties to the same source.

If your binding source is an object, you use the Path property to specify the value to use for your binding. If you are binding to XML data, you use the XPath property to specify the value. In some cases, it may be applicable to use the Path property event when your data is XML.

Here we associate the property value of the Person object to Text and Label. So keep synchronously the value of Text and Label. Please see the following codes.

        <Text x:style="BORDER" text="{Binding Path=name}">

        <Label text="{Binding Path=name}">

Notice that the Path value `name` is declared in the Person class.

### Specifying the path expression of data binding

Notice that in the previous example, the binding source is specified by setting the `DataContext` property on the Shell element. The Text and Label inherits the DataContext value from the Shell, which is its parent element. Here the binding path `name` is declared in the Person class. So the binding target can find the binding source directly. But in some case, the binding source is not the associated class, in XWT, there is a another solutions: specifying the path expression of the data binding.

For example, in an application we associate a Company object in Shell to a key "myData".

    <Shell
        ...
        DataContext="{StaticResource myData}">
        ...
        <Shell.Resources>
            <y:Company x:Key="myData"/>
        </Shell.Resources>
        ...
    </Shell>

There are three object class: Company, Person and Address. The Address object contains a string city. And the `address` is initialized in Person constructor.

Person:

    public class Person {
        private Address address;

        public Person() {
            address = new Address();
        }
        ...
    }

In Company class, there instance a Person type variable `manager`.

Company:

    public class Company {
        ...
        private Person manager = new Person();
        ...
    }

Now, if the user wants to create a Text in Shell and bind the value to the city member, XWT supplies a simple way of path expression to set in the Path property value of Binding as `manager.address.city`, See the code below.

        <Text x:style="BORDER" text="{Binding Path=manager.address.city}">
            <Text.layoutData>
                <GridData horizontalAlignment="FILL"
                    grabExcessHorizontalSpace="true"/>
            </Text.layoutData>
        </Text>