Bindings

According to the specification available under OData Version 4.0 Part 2: URL Conventions, 4 Resource Path, 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.

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.

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

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

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.

Example: Binding with parameters in JavaScript

#!jsoView.byId("SalesOrderTable").bindItems({
    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

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

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 facets "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.

The OData V4 model supports one-time binding, one-way binding and two-way binding modes (see sap.ui.model.BindingMode 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 setDefaultBindingMode in the Demo Kit.