Aggregation Binding

Aggregation binding is used to automatically create child controls according to model data.

You can define aggregation binding either in the settings object in the constructor or by calling the bindAggregation method. Aggregation binding requires the definition of a template, which is cloned for each bound entry of the list. For each clone that is created, the binding context is set to the respective list entry, so that all bindings of the template are resolved relative to the entry. The aggregated elements are destroyed and recreated whenever the bound list in the data model is changed.

Controls for the visualization of large data sets, for example Table or RowRepeater, only create clones for the currently visible entries and not for all list entries by using a custom updateAggregation method.

To bind an aggregation, you create a template or provide a factory function, which is then passed when defining the aggregation binding itself. In the settings object, this looks as follows:

var oItemTemplate = new sap.ui.core.ListItem({text:"{name}"});
var oComboBox = new sap.ui.commons.ComboBox({
    items: {
		path: "/company/contacts", 
		template: oItemTemplate
	}
});

You can also define the aggregation binding by using the bindAggregation method of a control:

oComboBox.bindAggregation("items", "/company/contacts", new sap.ui.core.ListItem({text:"{name}"}));

Some controls have a typed binding method for aggregations that are likely to be bound by the application:

oComboBox.bindItems("/company/contacts", oItemTemplate);

To remove an aggregation binding, you can use the unbindAggregation method. The aggregation binding is then removed automatically whenever a control is destroyed.

oComboBox.unbindAggregation("items");

For more information, see the API Reference.

Using Template Controls

For structured data with list entries with the same properties using template controls within the aggregation binding is recommended. A template is not necessarily a single control as in the examples above, but can be a tree of controls. For each list entry, a deep clone of the template is created and added to the bound aggregation.

var oMatrixLayout = new sap.ui.commons.layout.MatrixLayout();

var oRowTemplate = new sap.ui.commons.layout.MatrixLayoutRow({
	cells: [
		new sap.ui.commons.layout.MatrixLayoutCell({
			content: new sap.ui.commons.Label({text:"Name:"})
		}),
		new sap.ui.commons.layout.MatrixLayoutCell({
			content: new sap.ui.commons.TextView({text:"{name}"})
		})
	]
});

oMatrixLayout.bindAggregation("rows", "/company/contacts", oRowTemplate);

Using Factory Functions

The factory function is a more powerful approach for creating controls from model data. The factory function is called for each list entry to create the controls necessary to represent the current entry. The developer can decide, whether it is the same control with different properties or even a completely different control for each entry.

The factory function gets the parameters sId. These parameters must be used as they identify the created control and the context object oContext, which allows accessing data from the list entry. It returns an instance of sap.ui.core.Element.

oContainer.bindAggregation("content", "/company/properties", function(sId, oContext) {
	var value = oContext.getProperty("value");
	switch(typeof value) {
		case "string":
			return new sap.ui.commons.TextField(sId, {
				value: {
					path: "value",
					type: new sap.ui.model.type.String();
				}
			});
		case "number":
			return new sap.ui.commons.TextField(sId, {
				value: {
					path: "value",
					type: new sap.ui.model.type.Float();
				}
			});
		case "boolean":
			return new sap.ui.commons.CheckBox(sId, {
				checked: {
					path: "value"
				}
			});
	}
});

Initial Sorting and Filtering for Aggregation Binding

You can provide initial sorting and filtering when specifying the aggregation binding. Proceed as follows:

Define a sorter and/or filters:

var oSorter = new sap.ui.model.Sorter("name", true); // sort descending
var oFilter1 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.StartsWith, "M");
var oFilter2 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.Contains, "Paz");
var oFilter3 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.BT, "A","G"); // name between A and G

Hand the sorter and/or filters to the aggregation binding:

var oComboBox = new sap.ui.commons.ComboBox({
    items: {path:"/company/contacts", template:oItemTemplate, sorter:oSorter, filters:[oFilter1,oFilter2,oFilter3]}
});

You can also use the other aggregation binding possibilities (for example bindAggregation, bindItems) and provide the sorter and filters as parameters.

Manual Sorting and Filtering for Aggregation Binding

To sort/filter data manually after the aggregation binding is complete you can do so by getting the corresponding binding and calling the sort/filter function:

var oSorter = new sap.ui.model.Sorter("name", true); // sort descending
var oFilter1 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.StartsWith, "M");
var oFilter2 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.Contains, "Paz");
var oFilter3 = new sap.ui.model.Filter("name", sap.ui.model.FilterOperator.BT, "A","G"); // name between A and G

// manual sorting
oTable.getBinding("rows").sort(oSorter);

// manual filtering
oTable.getBinding("rows").filter([oFilter1,oFilter2,oFilter3]);
oComboBox.getBinding("items").filter([oFilter1,oFilter2,oFilter3]);

To get the binding of a control you have to know the name of the aggregation which is for example 'rows' for the table control.

For more information about the various sorting and filter methods and operators, see the documentation for Filter, Sorter, and Filter operations in the API Reference.