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

    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.

Furthermore, the OData V4 model only supports OData SimpleIdentifierInformation published on non-SAP site with characters from the US ASCII code character set, see .

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 meaning that they have no data as long as they have no context. They obtain a context either from a list binding where the context represents an entity for a certain index in an entity collection or from a 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. Once it has a context, a relative binding creates a data service request in the following cases:

  • The relative binding has parameters, such as OData query options like $select, see the Parameters subsection below. If you want a relative binding to create its own data service request, you specify a $select query option as binding parameter in order to reduce the response size. If you do not want to specify a $select, but still want the binding to create its own request, specify $select with value *.

  • You specify a dynamic filter or dynamic sorter for a list binding and use sap.ui.model.odata.OperationMode.Server, see sections Filtering and Sorting.

In all other cases, a relative binding reads data from its parent binding that created the context.

The point in time that is used to actually send the request is determined as explained in the section Batch Control. Bindings which create own data service requests cache data from data service responses. They do not send a data service request if data can be served from this cache.

Note 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. The method also deletes the caches of child bindings of the absolute binding.

Note There must be no pending property changes for a binding and its child bindings when calling the refresh method. Use the binding's hasPendingChanges method to check for pending changes before you delete the cache.

For details, 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.

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'
 }}">
 ...
 <items>
  <ColumnListItem>
   <cells> <Text text="{SalesOrderID}"/>  </cells>
   <cells> <Text text="{SO_2_BP/CompanyName}"/> </cells>
   <cells> <Text text="{BillingStatus}"/> </cells>
  </ColumnListItem>
 </items>
</Table>

<Table items="{
 path : 'SO_2_SOITEM',
 parameters : {
    $select: "DeliveryDate,GrossAmount,SalesOrderID"
 }
>
...
</Table>

The above sample shows an absolute list binding: A table's items aggregation is bound to /SalesOrderList using the $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 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.

The lower table for the line items has a relative binding. As it has parameters defined, it triggers its own data service request once it receives its binding context.

Parameters

When creating a 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, or the value '*' to select all properties.

  • $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

oView.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

<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'
            },
        }">
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.

Context API

The OData V4 model's list and context bindings create sap.ui.model.odata.v4.Context objects which enhance sap.ui.model.Context and provide the following methods:

  • getObject or getProperty for synchronous and requestObject or requestProperty for asynchronous access to values; the methods to access a property can provide the value in internal or external format

  • getBinding to retrieve the binding which created the context

  • getIndex to return the context's list index provided the context has been created by an ODataListBinding

Note

For getObject and requestObject, the data is cloned if the given path points to a non-primitive type. This ensures that internal OData model values cannot be modified.

When a property is read in external format, the format is solely determined by the type defined in the OData meta data of the property, and not by the type or formatter specified for the binding.

// assume oEvent is an event fired when a button is pressed in an item of a table bound to /SalesOrderList
sOrderID = oEvent.getSource().getBindingContext().getProperty("SalesOrderID"); // the SalesOrderID in the same item

// get a value in external format e.g. "1.234,23" instead of 1234.23
sGrossAmount = oEvent.getSource().getBindingContext().getProperty("GrossAmount", true);

For more information, see the sap.ui.model.odata.v4.Context API documentation in the Demo Kit.