Show TOC

Defining the Control MetadataLocate this document in the navigation structure

Control metadata consist of properties, events, as well as aggregations and associations.

The control metadata are defined as follows:

  • Properties

    A property is defined by a name and a type. Additionally, a default value can be defined for a property. The following list gives an overview of the available settings:

    • type: Data type of the control property; SAPUI5 provides an automatic type validation. Valid types are, for example, string (default) for a string property, int or float for number properties, int[], etc. for arrays and sap.ui.core.CSSSize for a custom-defined type.

    • defaultValue: Default value that is set if the application does not set a value; if no default value is defined, the property value is undefined.

    These control-specific settings are only available when inheriting from a control or one of the base classes sap.ui.core.Control, sap.ui.core.Element, sap.ui.base.ManagedObject, see Object Metadata and Implementation.

  • Events

    An event is defined by its name only.

    events: {
   "logout": {}
}

    For each event, methods for registering, de-registering and firing the event are created. For the logout event, for example, the attachLogout, detachLogout, fireLogout methods are created.

    A control can enable events to be interrupted by the application. A tab control, for example, can enable the application to cancel a close event by setting the enablePreventDefault property of the event to true and checking the return value after firing the event:

    events: {
   "close": {enablePreventDefault : true}  
}

  • Aggregations and Associations

    Aggregations and associations are defined by their name and a configuration object with the following information:

    • type: The type should be a subclass of the element or the control; the default is sap.ui.core.control

    • multiple: Defines whether it is a 0..1 aggregation or a 0..n aggregation; the default for aggregations is true = 0..n, and for associations the default is false

    • singularName: For 0..n aggregations, the aggregation name typically is plural, but certain methods are created where the singular form is required (for example, addWorksetItem} for the "worksetItems" aggregation).

    If only the type needs to be set, you can just give it as a string instead of the configuration object.

    One example: 

    aggregations: {
   "acceptButton" : "sap.ui.commons.Button", // if only type is given, no object is required
   "content" : {singularName: "content"},    // default type is "sap.ui.core.Control", 
                                             // which is appropriate for generic containers
   "worksetItems" : {type : "sap.ui.ux3.NavigationItem", multiple : true, singularName : "worksetItem"} 
                                             // a fully specified aggregation
}

    Multiple methods are created automatically at runtime, depending on the multiplicity, for example getWorksetItems, insertWorksetItem, addWorksetItem, removeWorksetItem, removeAllWorksetItems, indexOfWorksetItem, destroyWorksetItems. These methods have a default implementation which does everything to handle the aggregation properly, but they can be overridden and extended by the control implementation.

    If you want to mark one aggregation as default aggregation in order to be able to omit the aggregation tag in XML views, you can do this by setting the defaultAggregation property to the name of the aggregation as shown in the following code snippet:

    aggregations: {
   "content": {singularName: "content"} // default type is "sap.ui.core.Control", multiple is "true"

},
defaultAggregation: "content"

For a brief explanation of the differences between an aggregation and an association, see the Control Metadata section under Working with Controls.


In this section: