Show TOC

Property BindingLocate this document in the navigation structure

Property binding allows properties of the control to get automatically initialized and updated from model data.

To define a property binding on a control, the following two options exist:

  • In the settings object in the constructor of a control
  • Using the bindProperty method of a control

Once you have defined the property binding, the property is updated automatically every time the bound model property value is changed.

The most convenient way to define a property binding, which is sufficient in most cases, is to include the binding path within curly brackets as a string literal in the settings object: 

var oTextField = new sap.ui.commons.TextField({
    value: "{/company/name}"
});

Alternatively, you can use an extended syntax for property bindings. This extended syntax allows you to define additional binding information to be contained in the settings object, such as a formatter function. In this case you use a JS object instead of a string literal. This must contain a path property containing the binding path and can contain additional properties: 

var oTextField = new sap.ui.commons.TextField({
    value: {
		path: "/company/name", 
		mode: sap.ui.model.BindingMode.OneWay
	}
});

Depending on the use case, it can be useful to define the binding at a later time, using the bindProperty method: 

oTextField.bindProperty("value", "/company/name");

This option also allows the use of the same object-literal as in the constructor to define the binding 

oTextField.bindProperty("value", {
	path: "value",
	type: new sap.ui.model.type.Integer()
});

Some controls offer convenience methods for the main properties of a control that are most likely to be bound by an application. 

oTextField.bindValue("/company/name");

To remove a property binding, you can use the unbindProperty method. The property binding is removed automatically whenever a control is destroyed. 

oTextField.unbindProperty("value");

For a complete list of supported parameters, see the API Reference.

Formatting Property Values

The values in the data are often represented in some internal format and need to be converted to an external format for visual representation. This is especially necessary for numbers, dates, and times with locale dependent external formats. SAPUI5 provides two different conversion options: Formatter functions allow one-way conversion only, while data types can also be used for two-way binding as they cannot only format, but also parse user input. You can choose freely for each binding, depending on your scenario.

The formatter function can either be passed as a third parameter to the bindProperty method, or contained in the binding info with the key "formatter". It has a single parameter value, which is the value which needs to be formatted to an external representation, and is executed as a member of the control, so can access additional control properties or model data. 

oTextField.bindProperty("value", "/company/title", function(sValue) {
    return sValue && sValue.toUpperCase();
});

oControl = new sap.ui.commons.TextField({
    value: {
        path:"/company/revenue",
        formatter: function(fValue) {
            if (fValue) {
                return "> " + Math.floor(fValue/1000000) + "M";
            }
            return "0";
        }
    }
})

The formatter function, as it can contain any JavaScript, can not only be used for formatting a value, but can also do type conversion or calculate results from a given value, for example to show a special traffic light image depending on a boolean value: 

oImage.bindProperty("src", "/company/trusted", function(bValue) {
    return bValue ? "green.png" : "red.png";
});
Using Data Types

The type system provides the possibility to format and parse data, as well as validating if the entered data is within defined constraints. You can define a type to be used for a property binding, by passing it as a third parameter in bindProperty or by adding it to the binding information with the key "type". 

oTextField.bindProperty("value", "/company/title", new sap.ui.model.type.String());

oControl = new sap.ui.commons.TextField({
    value: {
        path:"/company/revenue",
        type: new sap.ui.model.type.Float({
            minFractionDigits: 2,
            maxFractionDigits: 2
        })
    }
})

You can define custom types by inheriting from sap.ui.model.SimpleType and implementing the three methods formatValue, parseValue and validateValue. formatValue will be called whenever the value in the model is changed to convert it to the type of the control property it is bound to and may throw a FormatException. parseValue is called, whenever the user modified a value in the UI and the change is transported back into the model. It may throw a ParseException in case the value cannot be converted. In case of successful parsing validateValue is called to check additional constraints, like minimum or maximum value, and throws a ValidateException in case constraints are violated. 

sap.ui.model.SimpleType.extend("sap.test.PLZ", {
    formatValue: function(oValue) {
        return oValue;
    },
    parseValue: function(oValue) {
        return oValue;
    },
    validateValue: function(oValue) {
       if (!/^(\d{5})?$/.test(oValue)) {
            throw new sap.ui.model.ValidateException("PLZ must have 5 digits!");
       }
    }
});

For more information, see Using the Data Binding Type System.

Binding Mode

By default, all bindings of a model instance have the default binding mode of the model. You can change this behavior. When creating a PropertyBinding, you can specify a different binding mode, which is then used exclusively for this specific binding. Of course, a binding can only have a supported binding mode of the model. 

var oModel = new sap.ui.model.json.JSONModel();
// default binding mode is Two Way
oModel.setData(myData);
sap.ui.getCore().setModel(oModel);
var oText = new sap.ui.commons.TextField();
// bind value property one way only 
// propertyname, formatter function, binding mode
oText.bindValue("/firstName", null, sap.ui.model.BindingMode.OneWay);
oText.placeAt("target1");
oText = new sap.ui.commons.TextField();
// bind value property two way which is the default
oText.bindValue("/firstName");
oText.placeAt("target2");
}

In the example above, two TextFields are created and their value property is bound to the same property in the model. The first TextField binding has a one-way binding mode, whereas the second TextField has the default binding mode of the model instance, which is two-way. So, when text is entered in the first TextField, the value will not be changed in the model. This happens only if text is entered in the second TextField. Then, of course, the value of the first TextField will be updated as it has a one-way binding, which means from model to view.