Show TOC

Custom Data - Attaching Data Objects to ControlsLocate this document in the navigation structure

SAPUI5 provides the data() method to attach data objects to controls.

The data() method is contained in sap.ui.core.Element. You can use this method to set and get data. The API is equivalent to jQuery.data().

The following additional options exist for attaching data to SAPUI5 controls:

Setting and Retrieving Data

To set and retrieve data, use the following code:

myButton.data("myData", "Hello");  // attach some data to the Button

alert(myButton.data("myData"));     // alerts "Hello"

var dataObject = myButton.data();  // a JS object containing ALL data
alert(dataObject.myData);          // alerts "Hello"
Binding Data: Use in a List Binding

For list bindings, use the following code:

// create a JSONModel, fill in the data and bind the ListBox to this model

var oModel = new sap.ui.model.json.JSONModel();
oModel.setData(aData);                                      // aData is a data array consisting of elements like {question:"Some question?",answer:"Some answer!"}
var ctrl = new sap.ui.commons.ListBox({select:giveAnswer}); // method giveAnswer() retrieves the custom data from the selected ListItem
ctrl.setModel(oModel);

// create an item template and bind the question data to the "text" property

var oItemTemplate = new sap.ui.core.ListItem();
oItemTemplate.bindProperty("text", "question");


// create a CustomData template, set its key to "answer" and bind its value to the answer data

var oDataTemplate = new sap.ui.core.CustomData({key:"answer"});
oDataTemplate.bindProperty("value", "answer");


// add the CustomData template to the item template

oItemTemplate.addCustomData(oDataTemplate);


// bind the items to the "questions" (which is the name of the data array)

ctrl.bindAggregation("items", "questions", oItemTemplate);

You can find a productive example in the SAPUI5 test suite by searching for CustomData in sap.ui.core.

Use in XML Views

In XML views, CustomData objects can be written as normal aggregated objects. However, to reduce the amount of code and improve the readability, a shortcut notation has been introduced: You can directly write the data attributes into the control tags. Simply use the following namespace for the respective attributes:

myNamespace="http://schemas.sap.com/sapui5/extension/sap.ui.core.CustomData/1".

The difference between this more formal namespace and the existing MVC namespaces is intentional.

Example Use without Data Binding

The following example shows how you attach the string "just great" to a button:

<mvc:View xmlns:core="sap.ui.core" xmlns:mvc="sap.ui.core.mvc" xmlns="sap.ui.commons" controllerName="my.own.controller" 
           xmlns:app="http://schemas.sap.com/sapui5/extension/sap.ui.core.CustomData/1">
     <Button id="myBtn" text="Click to show stored coordinates data" app:mySuperExtraData="just great" press="alertCoordinates"></Button>
</mvc:View>

The string is returned at runtime by calling button.data("mySuperExtraData").

Example Use with Data Binding

You can use data binding with the following notation:

<mvc:View xmlns:core="sap.ui.core" xmlns:mvc="sap.ui.core.mvc" xmlns="sap.ui.commons" controllerName="my.own.controller" 
           xmlns:app="http://schemas.sap.com/sapui5/extension/sap.ui.core.CustomData/1">
     <Button id="myBtn" text="Click to show stored coordinates data" app:coords="{data}" press="alertCoordinates"></Button>
</mvc:View>
Use in JSON Views

To add custom data to an element in a JSON view, add the following code to the element properties (examples with data binding):

customData: {
  Type:"sap.ui.core.CustomData",
    key:"coords",
    value:"{data}" // bind custom data
  }

To add multiple data elements, use an array:

customData: [{
  Type:"sap.ui.core.CustomData",
    key:"coords",
    value:"{data}" // bind custom data
  },
  {
  Type:"sap.ui.core.CustomData",
    key:"coords",
    value:"{data}" // bind custom data
  }]

In context, this looks as follows:

var json = 
            { 
                Type: "sap.ui.core.JSONView",
                controllerName:"my.own.controller",
                content: [{
                    Type:"sap.ui.commons.Panel",
                    content:[{
                        Type:"sap.ui.commons.Button",
                        text:"{actionName}",
                        press: "doSomething",
                        customData: {
                            Type:"sap.ui.core.CustomData",
                            key:"coords",
                            value:"{data}" // bind custom data
                        }
                    }]
                }]
            };
Use in HTML Views

To add custom data objects to a control or an element in HTML views, use a specific HTML attribute with the following syntax: data-custom-data:my-key="myValue". A custom data attribute starts with data-custom-data: followed by the name of the key. The dashes convert the respective following character into an upper case character. The value can be either a string or a binding expression:

<div data-sap-ui-type="sap.ui.commons.Button" data-text="This button is added dynamically" data-custom-data:my-key="myValue" data-custom-data:my-bound-key="{/mypath}"></div>