Show TOC

BindingsLocate this document in the navigation structure

Bindings connect SAPUI5 view elements to model data, allowing changes in the model to be reflected in the view element and vice versa.

The OData V4 model supports the following types of binding:
  • List bindings, which represent a collection (of OData entities, complex or primitive types) such as /SalesOrderList (see the sap.ui.model.odata.v4.ODataListBinding API documentation in the Demo Kit)

  • Context bindings, which represent a single entity such as /SalesOrderList('0500000000') or a structural property with complex type (see the sap.ui.model.odata.v4.ODataContextBinding API documentation in the Demo Kit)

  • Property bindings, which represent a single, primitive type property in an entity or complex type such as /ProductList('HT-1000')/Name (see the sap.ui.model.odata.v4.ODataPropertyBinding API documentation in the Demo Kit)

Creating Bindings
The OData V4 model offers the factory methods bindList, bindContext and bindProperty for creating bindings. Typically, these methods are not called directly in applications, but indirectly by the following:
  • Binding an SAPUI5 control through an API such as oForm.bindElement("{/SalesOrderList('0500000000')}");

    This sample binds a form to a certain sales order so that form elements can be bound to display or change single properties of the sales order.

    Note that binding expressions can be complex so that they can take additional properties to specify the binding further in addition to the path:
    oForm.bindElement({path : "/SalesOrderList('0500000000')", parameters : {$expand : "SO_2_SOITEM", ...}, events : {dataReceived : '.onDataEvents', ...}});
    This allows you, for instance, to specify OData V4 binding parameters such as $expand or attach to OData V4 Binding Events such as dataReceived.

    For a complete example, see the onSalesOrderSelect method in the SalesOrders sample (Main.controller.js) under Explored in the Demo Kit.

  • Declaring a binding for a control property in an XML view such as the following:
    <Table items="{path : '/SalesOrderList', parameters : $expand : 'SO_2_BP', $filter : 'BuyerName ge \'M\'', ...}, events : {dataReceived : '.onDataEvents', ... } }">

    For a complete example, see the SalesOrders sample (Main.view.xml) under Explored in the Demo Kit.

Path Syntax

According to the specification available under OData Version 4.0 Part 2: URL Conventions, 4 Resource PathInformation published on non-SAP site, every resource path (relative to the service root URL, no query options) is a valid data binding path within this model if a leading slash is added. For example, you can use "/EMPLOYEES('A%2FB%26C')" to access an entity instance with key "A/B&C". Note that appropriate URI encoding is necessary.

Initialization and Read Requests

Bindings are called absolute if their path starts with a forward slash "/"; otherwise they are called relative. Relative bindings are initial (i.e. they have no data) as long as they have no context; they obtain a context from a list binding (where the context represents an entity for a certain index in an entity collection) or context binding (where the context represents the one entity of the context binding). The binding which created the context is called the parent binding of the relative binding; the relative binding is a child binding of its parent binding.

Once data is requested for an absolute binding by a bound control or a child control with a relative binding, it creates a data service request to read data according to its path and query options. The point in time that is used to actually send the request is determined as explained in the section Batch Control. Absolute bindings cache data from data service responses; they do not send a data service request if data can be served from this cache.

Note that list bindings read data in pages, i.e. they only access a certain index range from their bound collection; they only trigger a new data service request if indexes are accessed which have not yet been read.

You can delete the cache for an absolute binding using its refresh method (see the ODataListBinding.refresh, ODataContextBinding.refresh and ODataPropertyBinding.refresh API documentation in the Demo Kit). You can refresh all bindings with ODataModel.refresh (See the ODataModel.refresh API documentation in the Demo Kit).

A relative binding is only initialized when it has a context from a parent binding. It does not send a data service request, but reads data from its parent binding that created the context. Consequently, it is not possible to call the refresh method on a relative binding.

Example: Absolute and relative bindings created via an XML view

<Table items="{
 path : '/SalesOrderList',
 parameters : {
  $expand : 'SO_2_BP',
  $select : 'BuyerName,CurrencyCode,GrossAmount,Note,SalesOrderID'
   <cells> <Text text="{SalesOrderID}"/>  </cells>
   <cells> <Text text="{SO_2_BP/CompanyName}"/> </cells>
   <cells> <Text text="{BillingStatus}"/> </cells>

The above sample shows an absolute list binding: A table's items aggregation is bound to /SalesOrderList using $expand and $select query options as binding parameters. The columns define relative bindings with paths SalesOrderID, SO_2_BP/CompanyName and BillingStatus with the absolute list binding as parent binding. Note that the BillingStatus remains empty and logs an error to the browser console as this structural property is not part of the $select specified for the list binding.

When creating an absolute binding, you can provide a parameter map which can contain the following:
  • OData query options; the values determine parameters for data service requests triggered by the binding. For more information about these options, see OData Version 4.0 Part 2: URL Conventions, 5 Query OptionsInformation published on non-SAP site.

  • Binding-specific parameters starting with "$$" to influence the behavior of the binding. Currently, $$groupId and $$updateGroupId are supported. For more information about these parameters, see Batch Control.

The binding's OData query options are combined with the query options passed to the OData V4 model; the binding's query options overwrite model query options with the same name. The resulting query options are appended to each data service request by this binding. The following query options are supported; all others are not allowed and lead to an error: All query options can be specified with a string value. In addition to strings, the following alternatives are possible:
  • $select can be specified as an array of strings where each string specifies a select item.

  • $expand can be an object where each object property corresponds to an expand item: the key is the complete expand path. The value can be set as follows:

    a) true or null if no expand options are required

    b) An object with query options for the $expand. Numeric options (like $levels) may be given as numbers. If the option is $expand or $select, the value may again be an object or array.

Example: Binding with parameters in JavaScript

    path : "/SalesOrderList",
    parameters : {
        "$expand" : {
            "SO_2_SOITEM" : {
                "$orderby" : "ItemPosition",
                "$select" : ["ItemPosition", "Quantity", "QuantityUnit", "SalesOrderID"]
        "$filter" : "BuyerName ge 'M'",
        "$orderby" : "GrossAmount desc",
        "$select" : ["BuyerName", "CurrencyCode", "GrossAmount", "Note", "SalesOrderID"]

Example: Binding with parameters in an XML view

<Table growing="true" growingThreshold="5" id="SalesOrders"
            path : '/SalesOrderList',
            parameters : {
                $expand : 'SO_2_BP',
                $filter : 'BuyerName ge \'M\'',
                $orderby : 'GrossAmount desc',
                $select : 'BuyerName,CurrencyCode,GrossAmount,Note,SalesOrderID'
Type Determination

The property binding automatically determines the appropriate type depending on the property's metadata, unless a type is specified explicitly. For example, the binding "{DeliveryDate}" will determine the type sap.ui.model.odata.type.DateTimeOffset (assuming the metadata specifies "Edm.DateTimeOffset" for this property), but "{path : 'DeliveryDate', type : 'sap.ui.model.odata.type.String'}" uses the hardcoded type sap.ui.model.odata.type.String instead (and does not require metadata). You cannot specify format options or constraints unless you also hardcode the type.

Automatic type determination will take constraints from metadata into account, namely the OData property facetsInformation published on non-SAP site "MaxLength", "Nullable", "Precision" and "Scale". Currently, the types "Edm.Boolean", "Edm.Byte", "Edm.Date", "Edm.DateTimeOffset", "Edm.Decimal", "Edm.Double", "Edm.Guid", "Edm.Int16", "Edm.Int32", "Edm.Int64", "Edm.SByte", "Edm.Single", "Edm.String" and "Edm.TimeOfDay" are supported and mapped to the corresponding type in the namespace sap.ui.model.odata.type. All other types, including collections, are mapped to the generic type sap.ui.model.odata.type.Raw which can only be used to access the raw model value "as is", but not to convert it to a human readable representation. This allows specialized controls to work with types that would otherwise not be supported.

For more information, see the sap.ui.model.odata.type and sap.ui.model.odata.type.Raw API documentation in the Demo Kit.

Binding Modes

The OData V4 model supports one-time binding, one-way binding and two-way binding modes (see the sap.ui.model.BindingMode API documentation in the Demo Kit). The two-way binding mode is the default binding mode of the OData V4 model. You can use the setDefaultBindingMode method on the model to change the binding mode. For more information, see the setDefaultBindingMode API documentation in the Demo Kit.