Show TOC

Working with Controls in SAPUI5Locate this document in the navigation structure

Controls are used to define the appearance and behavior of screen areas.

Controls consist of:

  • Control name

    The control name is a string that consists of the library name and the control name, separated by a dot. The library name can be omitted if there is no need to assign the control to a library. It is possible, for example, to use Square as control name. For controls that are reused by others, we recommend to use a unique library name, for example sap.byd.Square.

  • Control metadata

    The metadata defines the properties, events, aggregations and associations of a control.

    Control properties, such as text or width, are used to modify the appearance or to relate to data that is displayed by the control. The controls are defined by the control metadata, which is the public API of the control. The API can be used by applications at runtime and also contains information on runtime features such as data binding and type validation checks.

    Controls can aggregate other controls. These controls with aggregations serve as a container or layout control to which the application can add child controls. They can also serve as composite controls if the control itself adds child controls and reuses available components. In an aggregation, child controls are owned by the parent control and are destroyed together with the parent control. A control can only have one aggregation parent. Adding the control to another aggregation removes it from the previous parent control.

    Associated controls are not part or children of an aggregation control. They are connected by ID instead of reference. Destroying a control in an association does not affect the other control. It is possible that an associated control does not yet or no longer exist.

    Controls fire events. Events typically relate to the control's purpose and functionality on a semantically higher level than browser events such as click. Examples for control events are triggerSearch for a search field or collapse in a panel.

  • Elements

    Elements are parts of controls or rather configuration packages for parts of controls. Elements cannot be used standalone and do not have their own renderer. Instead, the control that uses the element does the rendering: The ListBox control, for example, renders the ListItem elements. The information provided for controls also applies to elements but not to the renderer. The sap.ui.core.Element class is the base class of sap.ui.core.Control.

  • Methods

    By convention, methods are public, unless their name starts with an underscore or if it is one of the special method types. When developing control libraries, public methods must be annotated with @public in the JSDoc, and private methods with @private. The generated getter/setter methods for properties are also public methods.

    Methods are added to a new control by simply providing the implementation. It is not necessary to add the method to the metadata. Other controls and the application must only call public methods and the control ensures that they remain compatible. There are no technical rules that prevent the call of private methods, but it is not allowed.

The base class for all controls in SAPUI5 is sap.ui.core.Control. To inherit and extend the functionality, specific controls can either inherit from the base class, or from another control.