abstract class sap.ui.base.ManagedObject

Control sample: sap.ui.base.ManagedObject
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/base/ManagedObject
Application Component: CA-UI5-COR

Base Class that introduces some basic concepts, such as, state management and data binding.

New subclasses of ManagedObject are created with a call to ManagedObject.extend and can make use of the following managed features:

Properties

Managed properties represent the state of a ManagedObject. They can store a single value of a simple data type (like 'string' or 'int'). They have a name (e.g. 'size') and methods to get the current value (getSize), or to set a new value (setSize). When a property is modified by calling the setter, the ManagedObject is marked as invalidated. A managed property can be bound against a property in a sap.ui.model.Model by using the #bindProperty method. Updates to the model property will be automatically reflected in the managed property and - if TwoWay databinding is active, changes to the managed property will be reflected in the model. An existing binding can be removed by calling #unbindProperty.

If a ManagedObject is cloned, the clone will have the same values for its managed properties as the source of the clone - if the property wasn't bound. If it is bound, the property in the clone will be bound to the same model property as in the source.

Details about the declaration of a managed property, the metadata that describes it and the set of methods that are automatically generated to access it, can be found in the documentation of the extend method.

Aggregations

Managed aggregations can store one or more references to other ManagedObjects. They are a mean to control the lifecycle of the aggregated objects: one ManagedObject can be aggregated by at most one parent ManagedObject at any time. When a ManagedObject is destroyed, all aggregated objects are destroyed as well and the object itself is removed from its parent. That is, aggregations won't contain destroyed objects or null/undefined.

Aggregations have a name ('e.g 'header' or 'items'), a cardinality ('0..1' or '0..n') and are of a specific type (which must be a subclass of ManagedObject as well or a UI5 interface). A ManagedObject will provide methods to set or get the aggregated object for a specific aggregation of cardinality 0..1 (e.g. setHeader, getHeader for an aggregation named 'header'). For an aggregation of cardinality 0..n, there are methods to get all aggregated objects (getItems), to locate an object in the aggregation (e.g. indexOfItem), to add, insert or remove a single aggregated object (addItem, insertItem, removeItem) or to remove or destroy all objects from an aggregation (removeAllItems, destroyItems).

Details about the declaration of a managed aggregation, the metadata that describes the aggregation, and the set of methods that are automatically generated to access it, can be found in the documentation of the extend method.

Aggregations of cardinality 0..n can be bound to a collection in a model by using #bindAggregation (and unbound again using #unbindAggregation). For each context in the model collection, a corresponding object will be created in the managed aggregation, either by cloning a template object or by calling a factory function.

Aggregations also control the databinding context of bound objects: by default, aggregated objects inherit all models and binding contexts from their parent object.

When a ManagedObject is cloned, all aggregated objects will be cloned as well - but only if they haven't been added by databinding. In that case, the aggregation in the clone will be bound to the same model collection.

Associations

Managed associations also form a relationship between objects, but they don't define a lifecycle for the associated objects. They even can 'break' in the sense that an associated object might have been destroyed already although it is still referenced in an association. For the same reason, the internal storage for associations are not direct object references but only the IDs of the associated target objects.

Associations have a name ('e.g 'initialFocus'), a cardinality ('0..1' or '0..n') and are of a specific type (which must be a subclass of ManagedObject as well or a UI5 interface). A ManagedObject will provide methods to set or get the associated object for a specific association of cardinality 0..1 (e.g. setInitialFocus, getInitialFocus). For an association of cardinality 0..n, there are methods to get all associated objects (getRefItems), to add, insert or remove a single associated object (addRefItem, insertRefItem, removeRefItem) or to remove all objects from an association (removeAllRefItems).

Details about the declaration of a managed association, the metadata that describes it and the set of methods that are automatically generated to access it, can be found in the documentation of the extend method.

Associations can't be bound to the model.

When a ManagedObject is cloned, the result for an association depends on the relationship between the associated target object and the root of the clone operation. If the associated object is part of the to-be-cloned object tree (reachable via aggregations from the root of the clone operation), then the cloned association will reference the clone of the associated object. Otherwise the association will reference the same object as in the original tree. When a ManagedObject is destroyed, other objects that are only associated, are not affected by the destroy operation.

Events

Managed events provide a mean for communicating important state changes to an arbitrary number of 'interested' listeners. Events have a name and (optionally) a set of parameters. For each event there will be methods to add or remove an event listener as well as a method to fire the event. (e.g. attachChange, detachChange, fireChange for an event named 'change').

Details about the declaration of managed events, the metadata that describes the event, and the set of methods that are automatically generated to access it, can be found in the documentation of the extend method.

When a ManagedObject is cloned, all listeners registered for any event in the clone source are also registered to the clone. Later changes are not reflected in any direction (neither from source to clone, nor vice versa).

Low Level APIs:

The prototype of ManagedObject provides several generic, low level APIs to manage properties, aggregations, associations, and events. These generic methods are solely intended for implementing higher level, non-generic methods that manage a single managed property etc. (e.g. a function setSize(value) that sets a new value for property 'size'). sap.ui.base.ManagedObject.extend creates default implementations of those higher level APIs for all managed aspects. The implementation of a subclass then can override those default implementations with a more specific implementation, e.g. to implement a side effect when a specific property is set or retrieved. It is therefore important to understand that the generic low-level methods ARE NOT SUITABLE FOR GENERIC ACCESS to the state of a managed object, as that would bypass the overriding higher level methods and their side effects.


Constructor

Constructs and initializes a managed object with the given sId and settings.

If the optional mSettings are given, they must be a simple object that defines values for properties, aggregations, associations or events keyed by their name.

Valid Names and Value Ranges:

The property (key) names supported in the object literal are exactly the (case sensitive) names documented in the JSDoc for the properties, aggregations, associations and events of the current class and its base classes. Note that for 0..n aggregations and associations this name usually is the plural name, whereas it is the singular name in case of 0..1 relations.

The possible values for a setting depend on its kind:

Each subclass should document the name and type of its supported settings in its constructor documentation.

Example usage:

new Dialog({
   title: "Some title text",            // property of type "string"
   showHeader: true,                    // property of type "boolean"
   endButton: new Button(...),          // 0..1 aggregation
   content: [                           // 0..n aggregation
      new Input(...),
      new Input(...)
   ],
   afterClose: function(oEvent) { ... } // event handler function
});

Instead of static values and object instances, data binding expressions can be used, either embedded in a string or as a binding info object as described in #bindProperty or #bindAggregation.

Example usage:

new Dialog({
   title: "{/title}",       // embedded binding expression, points to a string property in the data model
   ...
   content: {               // binding info object
      path : "/inputItems", // points to a collection in the data model
      template : new Input(...)
   }
});

Note that when setting string values, any curly braces in those values need to be escaped, so they are not interpreted as binding expressions. Use #escapeSettingsValue to do so.

Besides the settings documented below, ManagedObject itself supports the following special settings:

new sap.ui.base.ManagedObject(sId?, mSettings?, oScope?)
Param Type Default Value Description
sId? string

ID for the new managed object; generated automatically if no non-empty ID is given Note: this can be omitted, no matter whether mSettings will be given or not!

mSettings? object

Optional map/JSON-object with initial property values, aggregated objects etc. for the new object

oScope? object

Scope object for resolving string based type and formatter references in bindings. When a scope object is given, mSettings cannot be omitted, at least null or an empty object literal must be given.


Events Overview

Event Description
formatError

Fired when a new value for a bound property should have been propagated from the model, but formatting the value failed with an exception.

This event bubbles up the control hierarchy.

modelContextChange

Fired when models or contexts are changed on this object (either by calling setModel/setBindingContext or due to propagation)

parseError

Fired when a new value for a bound property should have been propagated to the model, but parsing the value failed with an exception.

This event bubbles up the control hierarchy.

validationError

Fired when a new value for a bound property should have been propagated to the model, but validating the value failed with an exception.

This event bubbles up the control hierarchy.

validationSuccess

Fired after a new value for a bound property has been propagated to the model. Only fired, when the binding uses a data type.

This event bubbles up the control hierarchy.

formatError

Fired when a new value for a bound property should have been propagated from the model, but formatting the value failed with an exception.

This event bubbles up the control hierarchy.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
element sap.ui.base.ManagedObject

ManagedObject instance whose property should have received the model update.

property string

Name of the property for which the binding should have been updated.

type sap.ui.model.Type

Data type used in the binding (if any).

newValue any

New value (model representation) as propagated from the model.

oldValue any

Old value (external representation) as previously stored in the ManagedObject.

modelContextChange

Fired when models or contexts are changed on this object (either by calling setModel/setBindingContext or due to propagation)

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

parseError

Fired when a new value for a bound property should have been propagated to the model, but parsing the value failed with an exception.

This event bubbles up the control hierarchy.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
element sap.ui.base.ManagedObject

ManagedObject instance whose property initiated the model update.

property string

Name of the property for which the bound model property should have been been updated.

type sap.ui.model.Type

Data type used in the binding.

newValue any

New value (external representation) as parsed by the binding.

oldValue any

Old value (external representation) as previously stored in the ManagedObject.

message string

Localized message describing the parse error

validationError

Fired when a new value for a bound property should have been propagated to the model, but validating the value failed with an exception.

This event bubbles up the control hierarchy.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
element sap.ui.base.ManagedObject

ManagedObject instance whose property initiated the model update.

property string

Name of the property for which the bound model property should have been been updated.

type sap.ui.model.Type

Data type used in the binding.

newValue any

New value (external representation) as parsed and validated by the binding.

oldValue any

Old value (external representation) as previously stored in the ManagedObject.

message string

Localized message describing the validation issues

validationSuccess

Fired after a new value for a bound property has been propagated to the model. Only fired, when the binding uses a data type.

This event bubbles up the control hierarchy.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
element sap.ui.base.ManagedObject

ManagedObject instance whose property initiated the model update.

property string

Name of the property for which the bound model property has been updated.

type sap.ui.model.Type

Data type used in the binding.

newValue any

New value (external representation) as propagated to the model.

Note: the model might modify (normalize) the value again and this modification will be stored in the ManagedObject. The 'newValue' parameter of this event contains the value before such a normalization.

oldValue any

Old value (external representation) as previously stored in the ManagedObject.


Methods Overview

Method Description
_onContextualSettingsChanged

Hook method to let descendants of ManagedObject know when propagated contextual settings have changed

addAggregation

Adds some entity oObject to the aggregation identified by sAggregationName.

If the given object is not valid with regard to the aggregation (if it is not an instance of the type specified for that aggregation) or when the method is called for an aggregation of cardinality 0..1, then an Error is thrown (see #validateAggregation.

If the aggregation already has content, the new object will be added after the current content. If the new object was already contained in the aggregation, it will be moved to the end.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically add an object to an aggregation. Use the concrete method addXYZ for aggregation 'XYZ' or the generic #applySettings instead.

addAssociation

Adds some object with the ID sId to the association identified by sAssociationName and marks this ManagedObject as changed.

This method does not avoid duplicates.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically add an object to an association. Use the concrete method addXYZ for association 'XYZ' or the generic #applySettings instead.

addPropagationListener

Adds a listener function that will be called during each propagation step on every control

applySettings

Sets all the properties, aggregations, associations and event handlers as given in the object literal mSettings. If a property, aggregation, etc. is not listed in mSettings, then its value is not changed by this method.

For properties and 0..1 aggregations/associations, any given setting overwrites the current value. For 0..n aggregations, the given values are appended; event listeners are registered in addition to existing ones.

For the possible keys and values in mSettings see the general documentation in sap.ui.base.ManagedObject or the specific documentation of the constructor of the concrete managed object class.

attachFormatError

Attaches event handler fnFunction to the formatError event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired when a new value for a bound property should have been propagated from the model, but formatting the value failed with an exception.

attachModelContextChange

Attaches event handler fnFunction to the modelContextChange event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired when models or contexts are changed on this object (either by calling setModel/setBindingContext or due to propagation)

attachParseError

Attaches event handler fnFunction to the parseError event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired when a new value for a bound property should have been propagated to the model, but parsing the value failed with an exception.

attachValidationError

Attaches event handler fnFunction to the validationError event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired when a new value for a bound property should have been propagated to the model, but validating the value failed with an exception.

attachValidationSuccess

Attaches event handler fnFunction to the validationSuccess event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired after a new value for a bound property has been propagated to the model. Only fired, when the binding uses a data type.

bindAggregation

Bind an aggregation to the model.

Whenever the corresponding model becomes available or changes (either via a call to setModel or propagated from a parent), its bindList method will be called to create a new ListBinding with the configured binding options.

The bound aggregation will use the given template, clone it for each item which exists in the bound list and set the appropriate binding context.

This is a generic method which can be used to bind any aggregation to the model. A class may flag aggregations in its metadata with bindable: "bindable" to get typed bindSomething and unbindSomething methods for those aggregations.

Also see List Binding (Aggregation Binding) in the documentation.

For more information on the oBindingInfo.key property and its usage, see Extended Change Detection.

bindContext

Bind the object to the referenced entity in the model, which is used as the binding context to resolve bound properties or aggregations of the object itself and all of its children relatively to the given path.

Since 1.11.1 please use {@link #bindObject} instead.
bindObject

Bind the object to the referenced entity in the model.

The entity is used as the binding context to resolve bound properties or aggregations of the object itself and all of its children relatively to the given path. If a relative binding path is used, it will be evaluated anew whenever the parent context changes.

Whenever the corresponding model becomes available or changes (either via a call to setModel or propagated from a parent), its bindContext method will be called to create a new ContextBinding with the configured binding options.

There's no difference between bindObject and bindElement. Method bindObject was introduced together with ManagedObject to make context bindings also available on ManagedObjects. The new name was chosen to reflect that the binding is not necessarily applied to an Element, it also could be applied to a component or some other ManagedObject.

Also see Context Binding in the documentation.

bindProperty

Binds a property to the model.

Whenever the corresponding model becomes available or changes (either via a call to setModel or propagated from a parent), its bindProperty method will be called to create a new PropertyBinding with the configured binding options.

The Setter for the given property will be called by the binding with the value retrieved from the data model. When the binding mode is OneTime, the property will be set only once. When it is OneWay, the property will be updated whenever the corresponding data in the model changes. In mode TwoWay, changes to the property (not originating in the model) will be reported back to the model (typical use case: user interaction changes the value of a control).

This is a generic method which can be used to bind any property to the model. A managed object may flag any property in its metadata with bindable: "bindable" to additionally provide named methods to bind and unbind the corresponding property.

Composite Binding
A composite property binding which combines data from multiple model paths can be declared using the parts parameter instead of path. The formatter function or a composite type then can be used to combine the parts, Properties with a composite binding are also known as "calculated fields".

Example:

  oTxt.bindValue({
    parts: [
      {path: "/firstName", type: "sap.ui.model.type.String"},
      {path: "myModel2>/lastName"}
    ]
  });

Note that a composite binding will be forced into mode OneWay when one of the binding parts is not in mode TwoWay.

Static Binding
A StaticBinding allows to define static values within a sap.ui.model.CompositeBinding. It behaves like a property binding but always returns the value that is stored in the binding itself. The binding does not have a sap.ui.model.Context, a sap.ui.model.Model or a oBindingInfo.path. A StaticBinding is created when a oBindingInfo.value is passed instead of a oBindingInfo.path or oBindingInfo.parts[i].path.

Also see StaticBinding in the documentation.

Formatter Functions
When a formatter function is specified for the binding or for a binding part, it will be called with the value of the bound model property. After setting the initial property value, the formatter function will only be called again when the bound model property changes (simple property binding) or when at least one of the bound model properties changes (formatter function of a composite binding). Note that a binding only monitors the bound model data for changes. Dependencies of the formatter implementation to other model data is not known to the binding and changes won't be detected.

When the formatter for a property binding (simple or composite) is called, the managed object will be given as this context. For formatters of binding parts in a composite binding, this is not the case.

Also see Property Binding in the documentation.

clone

Clones a tree of objects starting with the object on which clone is called first (root object).

The IDs within the newly created clone tree are derived from the original IDs by appending the given sIdSuffix (if no suffix is given, one will be created; it will be unique across multiple clone calls).

The oOptions configuration object can have the following properties:

  • The boolean value cloneChildren specifies whether associations/aggregations will be cloned
  • The boolean value cloneBindings specifies if bindings will be cloned
Note: In case the configuration oOptions is specified, the default values true no longer apply, which means in case cloneChildren or cloneBindings is not specified, then this ia assumed to be false and associations/aggregations or bindings are not cloned.

For each cloned object, the following settings are cloned based on the metadata of the object and the defined options:

  • All properties that are not bound. If cloneBindings is false, also the bound properties will be cloned; in general, values are referenced 1:1, not cloned. For some property types, however, the getters or setters might clone the value (e.g. array types and properties using metadata option byValue)
  • All aggregated objects that are not bound. If cloneBindings is false, also the ones that are bound will be cloned; they are all cloned recursively using the same sIdSuffix
  • All associated controls; when an association points to an object inside the cloned object tree, then the cloned association will be modified so that it points to the clone of the target object. When the association points to a managed object outside of the cloned object tree, then its target won't be changed.
  • All models set via setModel(); used by reference.
  • All property and aggregation bindings (if cloneBindings is true); the pure binding information (path, model name) is cloned, but all other information like template control or factory function, data type or formatter function are copied by reference. The bindings themselves are created anew as they are specific for the combination (object, property, model). As a result, any later changes to a binding of the original object are not reflected in the clone, but changes to e.g the type or template etc. are.

Each clone is created by first collecting the above mentioned settings and then creating a new instance with the normal constructor function. As a result, any side effects of mutator methods (setProperty etc.) or init hooks are repeated during clone creation. There is no need to override clone() just to reproduce these internal settings!

Custom controls however can override clone() to implement additional clone steps. They usually will first call clone() on the super class and then modify the returned clone accordingly.

Applications must never provide the second parameter aLocaleIds. It is determined automatically for the root object (and its non-existence also serves as an indicator for the root object). Specifying it will break the implementation of clone().

sap.ui.base.ManagedObject.create

Creates a new ManagedObject from the given data.

If vData is a managed object already, that object is returned. If vData is an object (literal), then a new object is created with vData as settings. The type of the object is either determined by a property of name Type (capital 'T') in the vData or by a property type (lower case 't') in the oKeyInfo object. In both cases, the type can be specified by name (dot separated name of the class) or by the constructor function of the class.

destroy

Cleans up the resources associated with this object and all its aggregated children.

After an object has been destroyed, it can no longer be used!

Applications should call this method if they don't need the object any longer.

destroyAggregation

Destroys (all) the managed object(s) in the aggregation named sAggregationName and empties the aggregation. If the aggregation did contain any object, this ManagedObject is marked as changed.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically destroy all objects in an aggregation. Use the concrete method destroyXYZ for aggregation 'XYZ' instead.

detachFormatError

Detaches event handler fnFunction from the formatError event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

detachModelContextChange

Detaches event handler fnFunction from the modelContextChange event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

detachParseError

Detaches event handler fnFunction from the parseError event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

detachValidationError

Detaches event handler fnFunction from the validationError event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

detachValidationSuccess

Detaches event handler fnFunction from the validationSuccess event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

sap.ui.base.ManagedObject.escapeSettingsValue

Escapes the given value so it can be used in the constructor's settings object. Should be used when property values are initialized with static string values which could contain binding characters (curly braces).

sap.ui.base.ManagedObject.extend

Defines a new subclass of ManagedObject with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo can contain the same information that sap.ui.base.Object.extend already accepts, plus the following new properties in the 'metadata' object literal:

  • library : string
  • properties : object
  • defaultProperty : string
  • aggregations : object
  • defaultAggregation : string
  • associations : object
  • events : object
  • specialSettings : object// this one is still experimental and not for public usage!

Each of these properties is explained in more detail lateron.

Example:

ManagedObect.extend('sap.mylib.MyClass', {
  metadata : {
    library: 'sap.mylib',
    properties : {
      value: 'string',
      width: 'sap.ui.core.CSSSize',
      height: { type: 'sap.ui.core.CSSSize', defaultValue: '100%'}
      description: { type: 'string', defaultValue: '', selector: '#{id}-desc'}
    },
    defaultProperty : 'value',
    aggregations : {
      header : { type: 'sap.mylib.FancyHeader', multiple : false }
      items : 'sap.ui.core.Control',
      buttons: { type: 'sap.mylib.Button', multiple : true, selector: '#{id} > .sapMLButtonsSection'}
    },
    defaultAggregation : 'items',
    associations : {
      initiallyFocused : { type: 'sap.ui.core.Control' }
    },
    events: {
      beforeOpen : {
        parameters : {
          opener : { type: 'sap.ui.core.Control' }
        }
      }
    },
  },

  init: function() {
  }

}); // end of 'extend' call

Detailed explanation of properties

'library' : string
Name of the library that the new subclass should belong to. If the subclass is a control or element, it will automatically register with that library so that authoring tools can discover it. By convention, the name of the subclass should have the library name as a prefix, e.g. 'sap.ui.commons.Panel' belongs to library 'sap.ui.commons'.

'properties' : object
An object literal whose properties each define a new managed property in the ManagedObject subclass. The value can either be a simple string which then will be assumed to be the type of the new property or it can be an object literal with the following properties

  • type: string type of the new property. Must either be one of the built-in types 'string', 'boolean', 'int', 'float', 'object', 'function' or 'any', or a type created and registered with sap.ui.base.DataType.createType or an array type based on one of the previous types (e.g. 'int[]' or 'string[]', but not just 'array').
  • visibility: string either 'hidden' or 'public', defaults to 'public'. Properties that belong to the API of a class must be 'public' whereas 'hidden' properties can only be used internally. Only public properties are accepted by the constructor or by applySettings or in declarative representations like an XMLView. Equally, only public properties are cloned.
  • byValue: boolean (either can be omitted or set to the boolean value true) If set to true, the property value will be deep cloned on write and read operations to ensure that the internal value can't be modified by the outside. The property byValue is currently limited to a boolean value. Other types are reserved for future use. Class definitions must only use boolean values for the flag (or omit it), but readers of ManagedObject metadata should handle any truthy value as true to be future safe. Note that using byValue:true has a performance impact on property access and therefore should be used carefully. It also doesn't make sense to set this option for properties with a primitive type (they have value semantic anyhow) or for properties with arrays of primitive types (they have been cloned already in the past with a cheaper implementation). Future versions of UI5 might encourage this as a limitation during class definition.
  • group:string a semantic grouping of the properties, intended to be used in design time tools. Allowed values are (case sensitive): Accessibility, Appearance, Behavior, Data, Designtime, Dimension, Identification, Misc
  • defaultValue: any the default value for the property or null if there is no defaultValue.
  • bindable: boolean|string (either can be omitted or set to the boolean value true or the magic string 'bindable') If set to true or 'bindable', additional named methods bindName and unbindName are generated as convenience. Despite its name, setting this flag is not mandatory to make the managed property bindable. The generic methods #bindProperty and #unbindProperty can always be used.
  • selector: string Optional; can be set to a valid CSS selector (as accepted by the Element.prototype.querySelector method). When set, it locates the DOM element that represents this property's value. It should only be set for properties that have a visual text representation in the DOM.

    The purpose of the selector is to allow other framework parts or design time tooling to identify the DOM parts of a control or element that represent a specific property without knowing the control or element implementation in detail.

    As an extension to the standard CSS selector syntax, the selector string can contain the placeholder {id} (multiple times). Before evaluating the selector in the context of an element or control, all occurrences of the placeholder have to be replaced by the (potentially escaped) ID of that element or control. In fact, any selector should start with #{id} to ensure that the query result is limited to the desired element or control.

    Note: there is a convenience method sap.ui.core.Element#getDomRefForSetting that evaluates the selector in the context of a concrete element or control instance. It also handles the placeholder {id}. Only selected framework features may use that private method, it is not yet a public API and might be changed or removed in future versions of UI5. However, instead of maintaining the selector in the metadata, element and control classes can overwrite getDomRefForSetting and determine the DOM element dynamically.

Property names should use camelCase notation, start with a lowercase letter and only use characters from the set [a-zA-Z0-9_$]. If an aggregation in the literal is preceded by a JSDoc comment (doclet) and if the UI5 plugin and template are used for JSDoc3 generation, the doclet will be used as generic documentation of the aggregation.

For each public property 'foo', the following methods will be created by the "extend" method and will be added to the prototype of the subclass:

  • getFoo() - returns the current value of property 'foo'. Internally calls #getProperty
  • setFoo(v) - sets 'v' as the new value of property 'foo'. Internally calls #setProperty
  • bindFoo(c) - (only if property was defined to be 'bindable'): convenience function that wraps #bindProperty
  • unbindFoo() - (only if property was defined to be 'bindable'): convenience function that wraps #unbindProperty
For hidden properties, no methods are generated.

'defaultProperty' : string
When specified, the default property must match the name of one of the properties defined for the new subclass (either own or inherited). The named property can be used to identify the main property to be used for bound data. E.g. the value property of a field control.

'aggregations' : object
An object literal whose properties each define a new aggregation in the ManagedObject subclass. The value can either be a simple string which then will be assumed to be the type of the new aggregation or it can be an object literal with the following properties

  • type: string type of the new aggregation. must be the full global name of a ManagedObject subclass or UI5 interface (in dot notation, e.g. 'sap.m.Button')
  • [multiple]: boolean whether the aggregation is a 0..1 (false) or a 0..n aggregation (true), defaults to true
  • [singularName]: string. Singular name for 0..n aggregations. For 0..n aggregations the name by convention should be the plural name. Methods affecting multiple objects in an aggregation will use the plural name (e.g. getItems(), whereas methods that deal with a single object will use the singular name (e.g. addItem). The framework knows a set of common rules for building plural form of English nouns and uses these rules to determine a singular name on its own. if that name is wrong, a singluarName can be specified with this property.
  • [visibility]: string either 'hidden' or 'public', defaults to 'public'. Aggregations that belong to the API of a class must be 'public' whereas 'hidden' aggregations typically are used for the implementation of composite classes (e.g. composite controls). Only public aggregations are accepted by the constructor or by applySettings or in declarative representations like an XMLView. Equally, only public aggregations are cloned.
  • bindable: boolean|string (either can be omitted or set to the boolean value true or the magic string 'bindable') If set to true or 'bindable', additional named methods bindName and unbindName are generated as convenience. Despite its name, setting this flag is not mandatory to make the managed aggregation bindable. The generic methods #bindAggregation and #unbindAggregation can always be used.
  • forwarding: object If set, this defines a forwarding of objects added to this aggregation into an aggregation of another ManagedObject - typically to an inner control within a composite control. This means that all adding, removal, or other operations happening on the source aggregation are actually called on the target instance. All elements added to the source aggregation will be located at the target aggregation (this means the target instance is their parent). Both, source and target element will return the added elements when asked for the content of the respective aggregation. If present, the named (non-generic) aggregation methods will be called for the target aggregation. Aggregations can only be forwarded to non-hidden aggregations of the same or higher multiplicity (i.e. an aggregation with multiplicity "0..n" cannot be forwarded to an aggregation with multiplicity "0..1"). The target aggregation must also be "compatible" to the source aggregation in the sense that any items given to the source aggregation must also be valid in the target aggregation (otherwise the target element will throw a validation error). If the forwarded elements use data binding, the target element must be properly aggregated by the source element to make sure all models are available there as well. The aggregation target must remain the same instance across the entire lifetime of the source control. Aggregation forwarding will behave unexpectedly when the content in the target aggregation is modified by other actors (e.g. by the target element or by another forwarding from a different source aggregation). Hence, this is not allowed. The forwarding configuration object defines the target of the forwarding. The available settings are:
    • idSuffix: stringA string which is appended to the ID of this ManagedObject to construct the ID of the target ManagedObject. This is one of the two options to specify the target. This option requires the target instance to be created in the init() method of this ManagedObject and to be always available.
    • getter: stringThe name of the function on instances of this ManagedObject which returns the target instance. This second option to specify the target can be used for lazy instantiation of the target. Note that either idSuffix or getter must be given. Also note that the target instance returned by the getter must remain the same over the entire lifetime of this ManagedObject and the implementation assumes that all instances return the same type of object (at least the target aggregation must always be defined in the same class).
    • aggregation: stringThe name of the aggregation on the target into which the objects shall be forwarded. The multiplicity of the target aggregation must be the same as the one of the source aggregation for which forwarding is defined.
    • [forwardBinding]: booleanWhether any binding should happen on the forwarding target or not. Default if omitted is false, which means any bindings happen on the outer ManagedObject. When the binding is forwarded, all binding methods like updateAggregation, getBindingInfo, refreshAggregation etc. are called on the target element of the forwarding instead of being called on this element. The basic aggregation mutator methods (add/remove etc.) are only called on the forwarding target element. Without forwardBinding, they are called on this element, but forwarded to the forwarding target, where they actually modify the aggregation.
  • selector: string Optional; can be set to a valid CSS selector (as accepted by the Element.prototype.querySelector method). When set, it locates the DOM element that surrounds the aggregation's content. It should only be set for aggregations that have a visual representation in the DOM. A DOM element surrounding the aggregation's rendered content should be available in the DOM, even if the aggregation is empty or not rendered for some reason. In cases where this is not possible or not intended, getDomRefForSetting can be overridden, see below.

    The purpose of the selector is to allow other framework parts like drag and drop or design time tooling to identify those DOM parts of a control or element that represent a specific aggregation without knowing the control or element implementation in detail.

    As an extension to the standard CSS selector syntax, the selector string can contain the placeholder {id} (multiple times). Before evaluating the selector in the context of an element or control, all occurrences of the placeholder have to be replaced by the (potentially escaped) ID of that element or control. In fact, any selector should start with #{id} to ensure that the query result is limited to the desired element or control.

    Note: there is a convenience method sap.ui.core.Element#getDomRefForSetting that evaluates the selector in the context of a concrete element or control instance. It also handles the placeholder {id}. Only selected framework features may use that private method, it is not yet a public API and might be changed or removed in future versions of UI5. However, instead of maintaining the selector in the metadata, element and control classes can overwrite getDomRefForSetting to calculate or add the appropriate DOM Element dynamically.

Aggregation names should use camelCase notation, start with a lowercase letter and only use characters from the set [a-zA-Z0-9_$]. The name for a hidden aggregations might start with an underscore. If an aggregation in the literal is preceded by a JSDoc comment (doclet) and if the UI5 plugin and template are used for JSDoc3 generation, the doclet will be used as generic documentation of the aggregation.

For each public aggregation 'item' of cardinality 0..1, the following methods will be created by the "extend" method and will be added to the prototype of the subclass:

  • getItem() - returns the current value of aggregation 'item'. Internally calls #getAggregation with a default value of undefined
  • setItem(o) - sets 'o' as the new aggregated object in aggregation 'item'. Internally calls #setAggregation
  • destroyItem(o) - destroy a currently aggregated object in aggregation 'item' and clears the aggregation. Internally calls #destroyAggregation
  • bindItem(c) - (only if aggregation was defined to be 'bindable'): convenience function that wraps #bindAggregation
  • unbindItem() - (only if aggregation was defined to be 'bindable'): convenience function that wraps #unbindAggregation
For a public aggregation 'items' of cardinality 0..n, the following methods will be created:
  • getItems() - returns an array with the objects contained in aggregation 'items'. Internally calls #getAggregation with a default value of []
  • addItem(o) - adds an object as last element in the aggregation 'items'. Internally calls #addAggregation
  • insertItem(o,p) - inserts an object into the aggregation 'items'. Internally calls #insertAggregation
  • indexOfItem(o) - returns the position of the given object within the aggregation 'items'. Internally calls #indexOfAggregation
  • removeItem(v) - removes an object from the aggregation 'items'. Internally calls #removeAggregation
  • removeItems() - removes all objects from the aggregation 'items'. Internally calls #removeAllAggregation
  • destroyItems() - destroy all currently aggregated objects in aggregation 'items' and clears the aggregation. Internally calls #destroyAggregation
  • bindItems(c) - (only if aggregation was defined to be 'bindable'): convenience function that wraps #bindAggregation
  • unbindItems() - (only if aggregation was defined to be 'bindable'): convenience function that wraps #unbindAggregation
For hidden aggregations, no methods are generated.

'defaultAggregation' : string
When specified, the default aggregation must match the name of one of the aggregations defined for the new subclass (either own or inherited). The named aggregation will be used in contexts where no aggregation is specified. E,g. when an object in an XMLView embeds other objects without naming an aggregation, as in the following example:

 <!-- assuming the defaultAggregation for Dialog is 'content' -->
 <Dialog>
   <Text/>
   <Button/>
 </Dialog>

'associations' : object
An object literal whose properties each define a new association of the ManagedObject subclass. The value can either be a simple string which then will be assumed to be the type of the new association or it can be an object literal with the following properties

  • type: string type of the new association
  • multiple: boolean whether the association is a 0..1 (false) or a 0..n association (true), defaults to false(1) for associations
  • [singularName]: string. Singular name for 0..n associations. For 0..n associations the name by convention should be the plural name. Methods affecting multiple objects in an association will use the plural name (e.g. getItems(), whereas methods that deal with a single object will use the singular name (e.g. addItem). The framework knows a set of common rules for building plural form of English nouns and uses these rules to determine a singular name on its own. if that name is wrong, a singluarName can be specified with this property.
  • visibility: string either 'hidden' or 'public', defaults to 'public'. Associations that belong to the API of a class must be 'public' whereas 'hidden' associations can only be used internally. Only public associations are accepted by the constructor or by applySettings or in declarative representations like an XMLView. Equally, only public associations are cloned.
Association names should use camelCase notation, start with a lowercase letter and only use characters from the set [a-zA-Z0-9_$]. If an association in the literal is preceded by a JSDoc comment (doclet) and if the UI5 plugin and template are used for JSDoc3 generation, the doclet will be used as generic documentation of the association.

For each association 'ref' of cardinality 0..1, the following methods will be created by the "extend" method and will be added to the prototype of the subclass:

  • getRef() - returns the current value of association 'item'. Internally calls #getAssociation with a default value of undefined
  • setRef(o) - sets 'o' as the new associated object in association 'item'. Internally calls #setAssociation
For a public association 'refs' of cardinality 0..n, the following methods will be created:
  • getRefs() - returns an array with the objects contained in association 'items'. Internally calls #getAssociation with a default value of []
  • addRef(o) - adds an object as last element in the association 'items'. Internally calls #addAssociation
  • removeRef(v) - removes an object from the association 'items'. Internally calls #removeAssociation
  • removeAllRefs() - removes all objects from the association 'items'. Internally calls #removeAllAssociation
For hidden associations, no methods are generated.

'events' : object
An object literal whose properties each define a new event of the ManagedObject subclass. The value can either be a simple string which then will be assumed to be the type of the new association or it can be an object literal with the following properties

  • allowPreventDefault: boolean whether the event allows to prevented the default behavior of the event source
  • parameters: object an object literal that describes the parameters of this event.
Event names should use camelCase notation, start with a lower-case letter and only use characters from the set [a-zA-Z0-9_$]. If an event in the literal is preceded by a JSDoc comment (doclet) and if the UI5 plugin and template are used for JSDoc3 generation, the doclet will be used as generic documentation of the event.

For each event 'Some' the following methods will be created by the "extend" method and will be added to the prototype of the subclass:

  • attachSome(fn,o) - registers a listener for the event. Internally calls #attachEvent
  • detachSome(fn,o) - deregisters a listener for the event. Internally calls #detachEvent
  • fireSome() - fire the event. Internally calls #fireEvent

'specialSettings' : object
Special settings are an experimental feature and MUST NOT BE DEFINED in controls or applications outside of the sap.ui.core library. There's no generic or general way how to set or get the values for special settings. For the same reason, they cannot be bound against a model. If there's a way for consumers to define a value for a special setting, it must be documented in the class that introduces the setting.

findAggregatedObjects

Searches and returns all aggregated objects that pass the given check function.

When the search is done recursively (bRecursive === true), it will be executed depth-first and ancestors will be added to the result array before their descendants.

If no check function is given, all aggregated objects will pass the check and be added to the result array.

When setting bIncludeBindingTemplates to true, binding templates will be included in the search.

Take care: this operation might be expensive.

fireFormatError

Fires event formatError to attached listeners.

fireModelContextChange

Fires event modelContextChange to attached listeners.

fireParseError

Fires event parseError to attached listeners.

fireValidationError

Fires event validationError to attached listeners.

fireValidationSuccess

Fires event validationSuccess to attached listeners.

getAggregation

Returns the aggregated object(s) for the named aggregation of this ManagedObject.

If the aggregation does not contain any objects(s), the given oDefaultForCreation (or null) is set as new value of the aggregation and returned to the caller.

Note: the need to specify a default value and the fact that it is stored as new value of a so far empty aggregation is recognized as a shortcoming of this API but can no longer be changed for compatibility reasons.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically read the content of an aggregation. Use the concrete method getXYZ for aggregation 'XYZ' instead.

getAssociation

Returns the content of the association with the given name.

For associations of cardinality 0..1, a single string with the ID of an associated object is returned (if any). For cardinality 0..n, an array with the IDs of the associated objects is returned.

If the association does not contain any objects(s), the given oDefaultForCreation is set as new value of the association and returned to the caller. The only supported values for oDefaultForCreation are null and undefined in the case of cardinality 0..1 and null, undefined or an empty array ([]) in case of cardinality 0..n. If the argument is omitted, null is used independently from the cardinality.

Note: the need to specify a default value and the fact that it is stored as new value of a so far empty association is recognized as a shortcoming of this API but can no longer be changed for compatibility reasons.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically retrieve the content of an association. Use the concrete method getXYZ for association 'XYZ' instead.

getBinding

Get the binding object for a specific aggregation/property

getBindingContext

Get the binding context of this object for the given model name.

If the object does not have a binding context set on itself and has no own model set, it will use the first binding context defined in its parent hierarchy.

Note: to be compatible with future versions of this API, you must not use the following model names:

  • null
  • empty string ""
  • string literals "null" or "undefined"
Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

Note: A ManagedObject inherits binding contexts from the Core only when it is a descendant of a UIArea.

getBindingInfo

Returns the binding info for the given property or aggregation.

The binding info contains information about path, binding object, format options, sorter, filter etc. for the property or aggregation. As the binding object is only created when the model becomes available, the binding property may be undefined.

getBindingPath

Get the binding path for a specific aggregation/property

getEventingParent

Returns the parent managed object as new eventing parent to enable control event bubbling or null if this object hasn't been added to a parent yet.

getId

Returns the object's ID.

There is no guarantee or check or requirement for the ID of a ManagedObject to be unique. Only some subclasses of ManagedObject introduce this as a requirement, e.g. Component or Element. All elements existing in the same window at the same time must have different IDs. A new element will fail during construction when the given ID is already used by another element. But there might be a component with the same ID as an element or another ManagedObject.

For the same reason, there is no general lookup for ManagedObjects via their ID. Only for subclasses that enforce unique IDs, there might be lookup mechanisms (e.g. sap.ui.getCore().byId() for elements).

getMetadata

Returns the metadata for the class that this object belongs to.

sap.ui.base.ManagedObject.getMetadata

Returns the metadata for the ManagedObject class.

getModel

Get the model to be used for data bindings with the given model name. If the object does not have a model set on itself, it will use the first model defined in its parent hierarchy.

The name can be omitted to reference the default model or it must be a non-empty string.

Note: to be compatible with future versions of this API, you must not use the following model names:

  • null
  • empty string ""
  • string literals "null" or "undefined"
Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

getObjectBinding

Get the object binding object for a specific model.

Note: to be compatible with future versions of this API, you must not use the following model names:

  • null
  • empty string ""
  • string literals "null" or "undefined"
Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

getOriginInfo

Returns the origin info for the value of the given property.

The origin info might contain additional information for translatable texts. The bookkeeping of this information is not active by default and must be activated by configuration. Even then, it might not be present for all properties and their values depending on where the value came form.

getOwnModels

Returns a map of all models assigned to this ManagedObject.

The default model is available on key undefined.

Note: Models propagated from the parent are not included.

getParent

Returns the parent managed object or null if this object hasn't been added to a parent yet.

The parent returned by this method is the technical parent used for data binding, invalidation, rendering etc. It might differ from the object on which the application originally added this object (the so called 'API parent'): some composite controls internally use hidden controls or containers to store their children. This method will return the innermost container that technically contains this object as a child.

Example:

Assume that a Dialog internally uses a (hidden) VerticalLayout to store its content:

  Dialog (API parent)
   \__ VerticalLayout (hidden composite part)
      \__ Text (API child)

If you add some content by calling the Dialog.prototype.addContent API, this will lead to the following observations:

  oDialog.addContent(oText);
  console.log(oText.getParent() === oDialog);  // false
  console.log(oText.getParent() instanceof VerticalLayout); // true
  console.log(oText.getParent().getParent() === oDialog); // true now, but might fail with later versions

Technically, from API perspective, oText is added as a child to Dialog. But internally, the Dialog adds the child to the hidden VerticalLayout container. If you now call the getParent method of the child, you will get the internal VerticalLayout object and not the Dialog API parent.

Note: The internal (hidden) structure of a composite control is not fixed and may be changed (see also our "Compatibility Rules"). Therefore, you should never rely on a specific structure or object being returned by getParent.

Note: There is no API to determine the original API parent.

getPropagationListeners

get propagation listeners

getProperty

Returns the value for the property with the given sPropertyName.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically retrieve the value of a property. Use the concrete method getXYZ for property 'XYZ' instead.

hasModel

Check if any model is set to the ManagedObject or to one of its parents (including UIArea and Core).

Note: A ManagedObject inherits models from the Core only when it is a descendant of a UIArea.

indexOfAggregation

Searches for the provided ManagedObject in the named aggregation and returns its 0-based index if found, or -1 otherwise. Returns -2 if the given named aggregation is of cardinality 0..1 and doesn't reference the given object.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically determine the position of an object in an aggregation. Use the concrete method indexOfXYZ for aggregation 'XYZ' instead.

insertAggregation

Inserts managed object oObject to the aggregation named sAggregationName at position iIndex.

If the given object is not valid with regard to the aggregation (if it is not an instance of the type specified for that aggregation) or when the method is called for an aggregation of cardinality 0..1, then an Error is thrown (see #validateAggregation.

If the given index is out of range with respect to the current content of the aggregation, it is clipped to that range (0 for iIndex < 0, n for iIndex > n).

Please note that this method does not work as expected when an object is added that is already part of the aggregation. In order to change the index of an object inside an aggregation, first remove it, then insert it again.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically insert an object into an aggregation. Use the concrete method insertXYZ for aggregation 'XYZ' instead.

invalidate

Marks this object and its aggregated children as 'invalid'.

The term 'invalid' originally was introduced by controls where a change to the object's state made the rendered DOM invalid. Later, the concept of invalidation was moved up in the inheritance hierarchy to ManagedObject, but the term was kept for compatibility reasons.

Managed settings (properties, aggregations, associations) invalidate the corresponding object automatically. Changing the state via the standard mutators, therefore, does not require an explicit call to invalidate. The same applies to changes made via data binding, as it internally uses the standard mutators.

By default, a ManagedObject propagates any invalidation to its parent. Controls or UIAreas handle invalidation on their own by triggering a re-rendering.

isBound

Find out whether a property or aggregation is bound

isDestroyed

Returns whether this object is destroyed or not. A destroyed object cannot be used anymore.

isDestroyStarted

Checks if an object's destruction has been started. During the descruction of an object its ID is still registered, and child objects could be still aggregated. Creating another object with the same ID would lead to duplicate ID issues. To check if the destruction is finished, call isDestroyed.

isInvalidateSuppressed

Returns whether re-rendering is currently suppressed on this ManagedObject.

isPropertyInitial

Returns whether the given property value is initial and has not been explicitly set or bound. Even after setting the default value or setting null/undefined (which also causes the default value to be set), the property is no longer initial. A property can be reset to initial state by calling resetProperty(sPropertyName).

isTreeBinding

This method is used internally and should only be overridden by a tree managed object which utilizes the tree binding. In this case and if the aggregation is a tree node the overridden method should then return true. If true is returned the tree binding will be used instead of the list binding.

onOwnerActivation

This lifecycle hook is called during activation of the owner component

onOwnerDeactivation

This lifecycle hook is called during deactivation of the owner component

propagateMessages

Generic method which is called, whenever messages for this object exist.

refreshAggregation

Generic method which can be called, when an aggregation needs to be refreshed. This method does not make any change on the aggregation, but just calls the getContexts method of the binding to trigger fetching of new data.

Subclasses should call this method only in the implementation of a named refresh method and for no other purposes. The framework might change the conditions under which the method is called and the method implementation might rely on those conditions.

removeAggregation

Removes an object from the aggregation named sAggregationName with cardinality 0..n.

The removed object is not destroyed nor is it marked as changed.

If the given object is found in the aggregation, it is removed, it's parent relationship is unset and this ManagedObject is marked as changed. The removed object is returned as result of this method. If the object could not be found, undefined is returned.

This method must only be called for aggregations of cardinality 0..n. The only way to remove objects from a 0..1 aggregation is to set a null value for them.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically remove an object from an aggregation. Use the concrete method removeXYZ for aggregation 'XYZ' instead.

removeAllAggregation

Removes all objects from the 0..n-aggregation named sAggregationName.

The removed objects are not destroyed nor are they marked as changed.

Additionally, it clears the parent relationship of all removed objects, marks this ManagedObject as changed and returns an array with the removed objects.

If the aggregation did not contain any objects, an empty array is returned and this ManagedObject is not marked as changed.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically remove all objects from an aggregation. Use the concrete method removeAllXYZ for aggregation 'XYZ' instead.

removeAllAssociation

Removes all the objects in the 0..n-association named sAssociationName and returns an array with their IDs. This ManagedObject is marked as changed, if the association contained any objects.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically remove all object from an association. Use the concrete method removeAllXYZ for association 'XYZ' instead.

removeAssociation

Removes a ManagedObject from the association named sAssociationName.

If an object is removed, the ID of that object is returned and this ManagedObject is marked as changed. Otherwise null is returned.

If the same object was added multiple times to the same association, only a single occurrence of it will be removed by this method. If the object is not found or if the parameter can't be interpreted neither as a ManagedObject (or ID) nor as an index in the association, nothing will be removed. The same is true if an index is given and if that index is out of range for the association.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically remove an object from an association. Use the concrete method removeXYZ for association 'XYZ' instead.

removePropagationListener

remove a propagation listener

resetProperty

Resets the given property to the default value and also restores the "initial" state (like it has never been set).

As subclasses might have implemented side effects in the named setter setXYZ for property 'xyz', that setter is called with a value of null, which by convention restores the default value of the property. This is only done to notify subclasses, the internal state is anyhow reset.

When the property has not been modified so far, nothing will be done.

sap.ui.base.ManagedObject.runWithPreprocessors

Activates the given ID and settings preprocessors, executes the given function and restores the previously active preprocessors.

When a preprocessor is not defined in oPreprocessors, then the currently active preprocessor is temporarily deactivated while fn is executed.

See the _fnIdPreprocessor and _fnSettingsPreprocessor members in this class for a detailed description of the preprocessors.

This method is intended for internal use in the sap/ui/base and sap/ui/core packages only.

setAggregation

Sets a new object in the named 0..1 aggregation of this ManagedObject and marks this ManagedObject as changed.

If the given object is not valid with regard to the aggregation (if it is not an instance of the type specified for that aggregation) or when the method is called for an aggregation of cardinality 0..n, then an Error is thrown (see #validateAggregation.

If the new object is the same as the currently aggregated object, then the internal state is not modified and this ManagedObject is not marked as changed.

If the given object is different, the parent of a previously aggregated object is cleared (it must have been this ManagedObject before), the parent of the given object is set to this ManagedObject and #invalidate is called for this object.

Note that this method does neither return nor destroy the previously aggregated object. This behavior is inherited by named set methods (see below) in subclasses. To avoid memory leaks, applications therefore should first get the aggregated object, keep a reference to it or destroy it, depending on their needs, and only then set a new object.

Note that ManagedObject only implements a single level of change tracking: if a first call to setAggregation recognizes a change, 'invalidate' is called. If another call to setAggregation reverts that change, invalidate() will be called again, the new status is not recognized as being 'clean' again.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically set an object in an aggregation. Use the concrete method setXYZ for aggregation 'XYZ' or the generic #applySettings instead.

setAssociation

Sets the associated object for the given managed association of cardinality '0..1' and marks this ManagedObject as changed.

The associated object can either be given by itself or by its id. If null or undefined is given, the association is cleared.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically set an object in an association. Use the concrete method setXYZ for association 'XYZ' or the generic #applySettings instead.

setBindingContext

Set the binding context for this ManagedObject for the model with the given name.

Note: to be compatible with future versions of this API, you must not use the following model names:

  • null
  • empty string ""
  • string literals "null" or "undefined"
Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

A value of null for oContext hides the parent context. The parent context will no longer be propagated to aggregated child controls. A value of undefined removes a currently active context or a null context and the parent context gets visible and propagated again.

Note: A ManagedObject inherits binding contexts from the Core only when it is a descendant of a UIArea.

setModel

Sets or unsets a model for the given model name for this ManagedObject.

The sName must either be undefined (or omitted) or a non-empty string. When the name is omitted, the default model is set/unset. To be compatible with future versions of this API, you must not use the following model names:

  • null
  • empty string ""
  • string literals "null" or "undefined"

When oModel is null or undefined, a previously set model with that name is removed from this ManagedObject. If an ancestor (parent, UIArea or Core) has a model with that name, this ManagedObject will immediately inherit that model from its ancestor.

All local bindings that depend on the given model name are updated (created if the model references became complete now; updated, if any model reference has changed; removed if the model references became incomplete now).

Any change (new model, removed model, inherited model) is also applied to all aggregated descendants as long as a descendant doesn't have its own model set for the given name.

Note: By design, it is not possible to hide an inherited model by setting a null or undefined model. Applications can set an empty model to achieve the same.

Note: A ManagedObject inherits models from the Core only when it is a descendant of a UIArea.

setProperty

Sets the given value for the given property after validating and normalizing it, marks this object as changed.

If the value is not valid with regard to the declared data type of the property, an Error is thrown. In case null or undefined is passed, the default value for this property is used (see #validateProperty). To fully reset the property to initial state, use #resetProperty instead. If the validated and normalized oValue equals the current value of the property, the internal state of this object is not changed (apart from the result of #isPropertyInitial). If the value changes, it is stored internally and the #invalidate method is called on this object. In the case of TwoWay databinding, the bound model is informed about the property change.

Note that ManagedObject only implements a single level of change tracking: if a first call to setProperty recognizes a change, 'invalidate' is called. If another call to setProperty reverts that change, invalidate() will be called again, the new status is not recognized as being 'clean' again.

Note: This method is a low level API as described in the class documentation. Applications or frameworks must not use this method to generically set a property. Use the concrete method setXYZ for property 'XYZ' or the generic #applySettings instead.

toString

Returns a simple string representation of this managed object.

Mainly useful for tracing purposes.

unbindAggregation

Unbind the aggregation from the model.

After unbinding, the current content of the aggregation is destroyed by default. When the bSuppressReset parameter is set, it is however retained.

unbindContext

Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.

Since 1.11.1 please use {@link #unbindObject} instead.
unbindObject

Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.

unbindProperty

Unbind the property from the model

updateAggregation

Generic method which is called whenever an aggregation binding has changed.

Depending on the type of the list binding and on additional configuration, this method either destroys all elements in the aggregation sName and recreates them anew or tries to reuse as many existing objects as possible. It is up to the method which strategy it uses.

In case a managed object needs special handling for an aggregation binding, it can create a named update method (e.g. updateRows for an aggregation rows) which then will be called by the framework instead of this generic method. THe method will be called with two arguments sChangeReason and oEventInfo.

Subclasses should call this method only in the implementation of such a named update method and for no other purposes. The framework might change the conditions under which the method is called and the method implementation might rely on those conditions.

validateAggregation

Checks whether the given value is of the proper type for the given aggregation name.

This method is already called by #setAggregation, #addAggregation and #insertAggregation. In many cases, subclasses of ManagedObject don't need to call it again in their mutator methods.

validateProperty

Checks whether the given value is of the proper type for the given property name.

In case null or undefined is passed, the default value for this property is used as value. If no default value is defined for the property, the default value of the type of the property is used.

If the property has a data type that is an instance of sap.ui.base.DataType and if a normalize function is defined for that type, that function will be called with the resulting value as only argument. The result of the function call is then used instead of the raw value.

This method is called by #setProperty. In many cases, subclasses of ManagedObject don't need to call it themselves.

_onContextualSettingsChanged

Hook method to let descendants of ManagedObject know when propagated contextual settings have changed

addAggregation

Adds some entity oObject to the aggregation identified by sAggregationName.

If the given object is not valid with regard to the aggregation (if it is not an instance of the type specified for that aggregation) or when the method is called for an aggregation of cardinality 0..1, then an Error is thrown (see #validateAggregation.

If the aggregation already has content, the new object will be added after the current content. If the new object was already contained in the aggregation, it will be moved to the end.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically add an object to an aggregation. Use the concrete method addXYZ for aggregation 'XYZ' or the generic #applySettings instead.

Param Type DefaultValue Description
sAggregationName string

the string identifying the aggregation that oObject should be added to.

oObject sap.ui.base.ManagedObject

the object to add; if empty, nothing is added

bSuppressInvalidate boolean

if true, this ManagedObject as well as the added child are not marked as changed

addAssociation

Adds some object with the ID sId to the association identified by sAssociationName and marks this ManagedObject as changed.

This method does not avoid duplicates.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically add an object to an association. Use the concrete method addXYZ for association 'XYZ' or the generic #applySettings instead.

Param Type DefaultValue Description
sAssociationName string

the string identifying the association the object should be added to.

sId string sap.ui.base.ManagedObject

the ID of the ManagedObject object to add; if empty, nothing is added; if a sap.ui.base.ManagedObject is given, its ID is added

bSuppressInvalidate boolean

if true, this managed object as well as the newly associated object are not marked as changed

addPropagationListener

Adds a listener function that will be called during each propagation step on every control

Param Type DefaultValue Description
listener function

function

applySettings

Sets all the properties, aggregations, associations and event handlers as given in the object literal mSettings. If a property, aggregation, etc. is not listed in mSettings, then its value is not changed by this method.

For properties and 0..1 aggregations/associations, any given setting overwrites the current value. For 0..n aggregations, the given values are appended; event listeners are registered in addition to existing ones.

For the possible keys and values in mSettings see the general documentation in sap.ui.base.ManagedObject or the specific documentation of the constructor of the concrete managed object class.

Param Type DefaultValue Description
mSettings object

the settings to apply to this managed object

oScope object

Scope object to resolve types and formatters

attachFormatError

Attaches event handler fnFunction to the formatError event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired when a new value for a bound property should have been propagated from the model, but formatting the value failed with an exception.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself

attachModelContextChange

Attaches event handler fnFunction to the modelContextChange event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired when models or contexts are changed on this object (either by calling setModel/setBindingContext or due to propagation)

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself

attachParseError

Attaches event handler fnFunction to the parseError event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired when a new value for a bound property should have been propagated to the model, but parsing the value failed with an exception.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself

attachValidationError

Attaches event handler fnFunction to the validationError event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired when a new value for a bound property should have been propagated to the model, but validating the value failed with an exception.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself

attachValidationSuccess

Attaches event handler fnFunction to the validationSuccess event of this sap.ui.base.ManagedObject.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.base.ManagedObject itself.

Fired after a new value for a bound property has been propagated to the model. Only fired, when the binding uses a data type.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself

bindAggregation

Bind an aggregation to the model.

Whenever the corresponding model becomes available or changes (either via a call to setModel or propagated from a parent), its bindList method will be called to create a new ListBinding with the configured binding options.

The bound aggregation will use the given template, clone it for each item which exists in the bound list and set the appropriate binding context.

This is a generic method which can be used to bind any aggregation to the model. A class may flag aggregations in its metadata with bindable: "bindable" to get typed bindSomething and unbindSomething methods for those aggregations.

Also see List Binding (Aggregation Binding) in the documentation.

For more information on the oBindingInfo.key property and its usage, see Extended Change Detection.

Param Type DefaultValue Description
sName string

Name of a public aggregation to bind

oBindingInfo sap.ui.base.ManagedObject.AggregationBindingInfo

Binding info

bindContext

Bind the object to the referenced entity in the model, which is used as the binding context to resolve bound properties or aggregations of the object itself and all of its children relatively to the given path.

Since 1.11.1 please use {@link #bindObject} instead.
Param Type DefaultValue Description
sPath string

the binding path

bindObject

Bind the object to the referenced entity in the model.

The entity is used as the binding context to resolve bound properties or aggregations of the object itself and all of its children relatively to the given path. If a relative binding path is used, it will be evaluated anew whenever the parent context changes.

Whenever the corresponding model becomes available or changes (either via a call to setModel or propagated from a parent), its bindContext method will be called to create a new ContextBinding with the configured binding options.

There's no difference between bindObject and bindElement. Method bindObject was introduced together with ManagedObject to make context bindings also available on ManagedObjects. The new name was chosen to reflect that the binding is not necessarily applied to an Element, it also could be applied to a component or some other ManagedObject.

Also see Context Binding in the documentation.

Param Type DefaultValue Description
oBindingInfo object

An object describing the binding

path string

Path in the model to bind to, either an absolute path or relative to the binding context for the corresponding model; when the path contains a '>' sign, the string preceding it will override the model property and the remainder after the '>' will be used as binding path

model string

Name of the model to bind against; when undefined or omitted, the default model is used

parameters object

Map of additional parameters for this binding; the names and value ranges of the supported parameters depend on the model implementation, they should be documented with the bindContext method of the corresponding model class or with the model specific subclass of sap.ui.model.ContextBinding

suspended boolean false

Whether the binding should be suspended initially

events object

Map of event handler functions keyed by the name of the binding events that they should be attached to

bindProperty

Binds a property to the model.

Whenever the corresponding model becomes available or changes (either via a call to setModel or propagated from a parent), its bindProperty method will be called to create a new PropertyBinding with the configured binding options.

The Setter for the given property will be called by the binding with the value retrieved from the data model. When the binding mode is OneTime, the property will be set only once. When it is OneWay, the property will be updated whenever the corresponding data in the model changes. In mode TwoWay, changes to the property (not originating in the model) will be reported back to the model (typical use case: user interaction changes the value of a control).

This is a generic method which can be used to bind any property to the model. A managed object may flag any property in its metadata with bindable: "bindable" to additionally provide named methods to bind and unbind the corresponding property.

Composite Binding
A composite property binding which combines data from multiple model paths can be declared using the parts parameter instead of path. The formatter function or a composite type then can be used to combine the parts, Properties with a composite binding are also known as "calculated fields".

Example:

  oTxt.bindValue({
    parts: [
      {path: "/firstName", type: "sap.ui.model.type.String"},
      {path: "myModel2>/lastName"}
    ]
  });

Note that a composite binding will be forced into mode OneWay when one of the binding parts is not in mode TwoWay.

Static Binding
A StaticBinding allows to define static values within a sap.ui.model.CompositeBinding. It behaves like a property binding but always returns the value that is stored in the binding itself. The binding does not have a sap.ui.model.Context, a sap.ui.model.Model or a oBindingInfo.path. A StaticBinding is created when a oBindingInfo.value is passed instead of a oBindingInfo.path or oBindingInfo.parts[i].path.

Also see StaticBinding in the documentation.

Formatter Functions
When a formatter function is specified for the binding or for a binding part, it will be called with the value of the bound model property. After setting the initial property value, the formatter function will only be called again when the bound model property changes (simple property binding) or when at least one of the bound model properties changes (formatter function of a composite binding). Note that a binding only monitors the bound model data for changes. Dependencies of the formatter implementation to other model data is not known to the binding and changes won't be detected.

When the formatter for a property binding (simple or composite) is called, the managed object will be given as this context. For formatters of binding parts in a composite binding, this is not the case.

Also see Property Binding in the documentation.

Param Type DefaultValue Description
sName string

Name of a public property to bind; public aggregations of cardinality 0..1 that have an alternative, simple type (e.g. "string" or "int") can also be bound with this method

oBindingInfo sap.ui.base.ManagedObject.PropertyBindingInfo

Binding information

clone

Clones a tree of objects starting with the object on which clone is called first (root object).

The IDs within the newly created clone tree are derived from the original IDs by appending the given sIdSuffix (if no suffix is given, one will be created; it will be unique across multiple clone calls).

The oOptions configuration object can have the following properties:

Note: In case the configuration oOptions is specified, the default values true no longer apply, which means in case cloneChildren or cloneBindings is not specified, then this ia assumed to be false and associations/aggregations or bindings are not cloned.

For each cloned object, the following settings are cloned based on the metadata of the object and the defined options:

Each clone is created by first collecting the above mentioned settings and then creating a new instance with the normal constructor function. As a result, any side effects of mutator methods (setProperty etc.) or init hooks are repeated during clone creation. There is no need to override clone() just to reproduce these internal settings!

Custom controls however can override clone() to implement additional clone steps. They usually will first call clone() on the super class and then modify the returned clone accordingly.

Applications must never provide the second parameter aLocaleIds. It is determined automatically for the root object (and its non-existence also serves as an indicator for the root object). Specifying it will break the implementation of clone().

Param Type DefaultValue Description
sIdSuffix string

a suffix to be appended to the cloned object ID

aLocalIds string[]

an array of local IDs within the cloned hierarchy (internally used)

oOptions Object '\{cloneChildren:true, cloneBindings:true\}'

Configuration object; when omitted, both properties default to true; when specified, undefined properties default to false

cloneChildren boolean false

Whether associations and aggregations will be cloned

cloneBindings boolean false

Whether bindings will be cloned

sap.ui.base.ManagedObject.create

Creates a new ManagedObject from the given data.

If vData is a managed object already, that object is returned. If vData is an object (literal), then a new object is created with vData as settings. The type of the object is either determined by a property of name Type (capital 'T') in the vData or by a property type (lower case 't') in the oKeyInfo object. In both cases, the type can be specified by name (dot separated name of the class) or by the constructor function of the class.

Param Type DefaultValue Description
vData sap.ui.base.ManagedObject object

The data to create the object from

oKeyInfo object

Info object for the aggregation to which the created object will be added; serves as a fallback for determining the type of the object to be created

oScope object

Scope object to resolve types and formatters in bindings

destroy

Cleans up the resources associated with this object and all its aggregated children.

After an object has been destroyed, it can no longer be used!

Applications should call this method if they don't need the object any longer.

Param Type DefaultValue Description
bSuppressInvalidate boolean false

If true, this ManagedObject and all its ancestors won't be invalidated.
This flag should be used only during control development to optimize invalidation procedures. It should not be used by any application code.

destroyAggregation

Destroys (all) the managed object(s) in the aggregation named sAggregationName and empties the aggregation. If the aggregation did contain any object, this ManagedObject is marked as changed.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically destroy all objects in an aggregation. Use the concrete method destroyXYZ for aggregation 'XYZ' instead.

Param Type DefaultValue Description
sAggregationName string

the name of the aggregation

bSuppressInvalidate boolean

if true, this ManagedObject is not marked as changed

detachFormatError

Detaches event handler fnFunction from the formatError event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachModelContextChange

Detaches event handler fnFunction from the modelContextChange event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachParseError

Detaches event handler fnFunction from the parseError event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachValidationError

Detaches event handler fnFunction from the validationError event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachValidationSuccess

Detaches event handler fnFunction from the validationSuccess event of this sap.ui.base.ManagedObject.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.ui.base.ManagedObject.escapeSettingsValue

Escapes the given value so it can be used in the constructor's settings object. Should be used when property values are initialized with static string values which could contain binding characters (curly braces).

Param Type DefaultValue Description
vValue any

Value to escape; only needs to be done for string values, but the call will work for all types

sap.ui.base.ManagedObject.extend

Defines a new subclass of ManagedObject with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo can contain the same information that sap.ui.base.Object.extend already accepts, plus the following new properties in the 'metadata' object literal:

Each of these properties is explained in more detail lateron.

Example:

ManagedObect.extend('sap.mylib.MyClass', {
  metadata : {
    library: 'sap.mylib',
    properties : {
      value: 'string',
      width: 'sap.ui.core.CSSSize',
      height: { type: 'sap.ui.core.CSSSize', defaultValue: '100%'}
      description: { type: 'string', defaultValue: '', selector: '#{id}-desc'}
    },
    defaultProperty : 'value',
    aggregations : {
      header : { type: 'sap.mylib.FancyHeader', multiple : false }
      items : 'sap.ui.core.Control',
      buttons: { type: 'sap.mylib.Button', multiple : true, selector: '#{id} > .sapMLButtonsSection'}
    },
    defaultAggregation : 'items',
    associations : {
      initiallyFocused : { type: 'sap.ui.core.Control' }
    },
    events: {
      beforeOpen : {
        parameters : {
          opener : { type: 'sap.ui.core.Control' }
        }
      }
    },
  },

  init: function() {
  }

}); // end of 'extend' call

Detailed explanation of properties

'library' : string
Name of the library that the new subclass should belong to. If the subclass is a control or element, it will automatically register with that library so that authoring tools can discover it. By convention, the name of the subclass should have the library name as a prefix, e.g. 'sap.ui.commons.Panel' belongs to library 'sap.ui.commons'.

'properties' : object
An object literal whose properties each define a new managed property in the ManagedObject subclass. The value can either be a simple string which then will be assumed to be the type of the new property or it can be an object literal with the following properties

Property names should use camelCase notation, start with a lowercase letter and only use characters from the set [a-zA-Z0-9_$]. If an aggregation in the literal is preceded by a JSDoc comment (doclet) and if the UI5 plugin and template are used for JSDoc3 generation, the doclet will be used as generic documentation of the aggregation.

For each public property 'foo', the following methods will be created by the "extend" method and will be added to the prototype of the subclass:

For hidden properties, no methods are generated.

'defaultProperty' : string
When specified, the default property must match the name of one of the properties defined for the new subclass (either own or inherited). The named property can be used to identify the main property to be used for bound data. E.g. the value property of a field control.

'aggregations' : object
An object literal whose properties each define a new aggregation in the ManagedObject subclass. The value can either be a simple string which then will be assumed to be the type of the new aggregation or it can be an object literal with the following properties

Aggregation names should use camelCase notation, start with a lowercase letter and only use characters from the set [a-zA-Z0-9_$]. The name for a hidden aggregations might start with an underscore. If an aggregation in the literal is preceded by a JSDoc comment (doclet) and if the UI5 plugin and template are used for JSDoc3 generation, the doclet will be used as generic documentation of the aggregation.

For each public aggregation 'item' of cardinality 0..1, the following methods will be created by the "extend" method and will be added to the prototype of the subclass:

For a public aggregation 'items' of cardinality 0..n, the following methods will be created: For hidden aggregations, no methods are generated.

'defaultAggregation' : string
When specified, the default aggregation must match the name of one of the aggregations defined for the new subclass (either own or inherited). The named aggregation will be used in contexts where no aggregation is specified. E,g. when an object in an XMLView embeds other objects without naming an aggregation, as in the following example:

 <!-- assuming the defaultAggregation for Dialog is 'content' -->
 <Dialog>
   <Text/>
   <Button/>
 </Dialog>

'associations' : object
An object literal whose properties each define a new association of the ManagedObject subclass. The value can either be a simple string which then will be assumed to be the type of the new association or it can be an object literal with the following properties

Association names should use camelCase notation, start with a lowercase letter and only use characters from the set [a-zA-Z0-9_$]. If an association in the literal is preceded by a JSDoc comment (doclet) and if the UI5 plugin and template are used for JSDoc3 generation, the doclet will be used as generic documentation of the association.

For each association 'ref' of cardinality 0..1, the following methods will be created by the "extend" method and will be added to the prototype of the subclass:

For a public association 'refs' of cardinality 0..n, the following methods will be created: For hidden associations, no methods are generated.

'events' : object
An object literal whose properties each define a new event of the ManagedObject subclass. The value can either be a simple string which then will be assumed to be the type of the new association or it can be an object literal with the following properties

Event names should use camelCase notation, start with a lower-case letter and only use characters from the set [a-zA-Z0-9_$]. If an event in the literal is preceded by a JSDoc comment (doclet) and if the UI5 plugin and template are used for JSDoc3 generation, the doclet will be used as generic documentation of the event.

For each event 'Some' the following methods will be created by the "extend" method and will be added to the prototype of the subclass:

'specialSettings' : object
Special settings are an experimental feature and MUST NOT BE DEFINED in controls or applications outside of the sap.ui.core library. There's no generic or general way how to set or get the values for special settings. For the same reason, they cannot be bound against a model. If there's a way for consumers to define a value for a special setting, it must be documented in the class that introduces the setting.

Param Type DefaultValue Description
sClassName string

name of the class to be created

oClassInfo object

object literal with information about the class

FNMetaImpl function

constructor function for the metadata object. If not given, it defaults to sap.ui.base.ManagedObjectMetadata.

findAggregatedObjects

Searches and returns all aggregated objects that pass the given check function.

When the search is done recursively (bRecursive === true), it will be executed depth-first and ancestors will be added to the result array before their descendants.

If no check function is given, all aggregated objects will pass the check and be added to the result array.

When setting bIncludeBindingTemplates to true, binding templates will be included in the search.

Take care: this operation might be expensive.

Param Type DefaultValue Description
bRecursive boolean false

Whether the whole aggregation tree should be searched

fnCondition function(sap.ui.base.ManagedObject) : boolean

Objects for which this function returns a falsy value will not be added to the result array

bIncludeBindingTemplates boolean false

Whether binding templates should be included

fireFormatError

Fires event formatError to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

element sap.ui.base.ManagedObject

ManagedObject instance whose property should have received the model update.

property string

Name of the property for which the binding should have been updated.

type sap.ui.model.Type

Data type used in the binding (if any).

newValue any

New value (model representation) as propagated from the model.

oldValue any

Old value (external representation) as previously stored in the ManagedObject.

fireModelContextChange

Fires event modelContextChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireParseError

Fires event parseError to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

element sap.ui.base.ManagedObject

ManagedObject instance whose property initiated the model update.

property string

Name of the property for which the bound model property should have been been updated.

type sap.ui.model.Type

Data type used in the binding.

newValue any

New value (external representation) as parsed by the binding.

oldValue any

Old value (external representation) as previously stored in the ManagedObject.

message string

Localized message describing the parse error

fireValidationError

Fires event validationError to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

element sap.ui.base.ManagedObject

ManagedObject instance whose property initiated the model update.

property string

Name of the property for which the bound model property should have been been updated.

type sap.ui.model.Type

Data type used in the binding.

newValue any

New value (external representation) as parsed and validated by the binding.

oldValue any

Old value (external representation) as previously stored in the ManagedObject.

message string

Localized message describing the validation issues

fireValidationSuccess

Fires event validationSuccess to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

element sap.ui.base.ManagedObject

ManagedObject instance whose property initiated the model update.

property string

Name of the property for which the bound model property has been updated.

type sap.ui.model.Type

Data type used in the binding.

newValue any

New value (external representation) as propagated to the model.

Note: the model might modify (normalize) the value again and this modification will be stored in the ManagedObject. The 'newValue' parameter of this event contains the value before such a normalization.

oldValue any

Old value (external representation) as previously stored in the ManagedObject.

getAggregation

Returns the aggregated object(s) for the named aggregation of this ManagedObject.

If the aggregation does not contain any objects(s), the given oDefaultForCreation (or null) is set as new value of the aggregation and returned to the caller.

Note: the need to specify a default value and the fact that it is stored as new value of a so far empty aggregation is recognized as a shortcoming of this API but can no longer be changed for compatibility reasons.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically read the content of an aggregation. Use the concrete method getXYZ for aggregation 'XYZ' instead.

Param Type DefaultValue Description
sAggregationName string

Name of the aggregation

oDefaultForCreation sap.ui.base.ManagedObject Array

Object that is used in case the current aggregation is empty. If provided, it must be null for 0..1 aggregations or an empty array for 0..n aggregations. If not provided, null is used.

Note: When an empty array is given and used because the aggregation was not set before, then this array will be used for the aggregation from thereon. Sharing the same empty array between different calls to this method therefore is not possible and will result in inconsistencies.

getAssociation

Returns the content of the association with the given name.

For associations of cardinality 0..1, a single string with the ID of an associated object is returned (if any). For cardinality 0..n, an array with the IDs of the associated objects is returned.

If the association does not contain any objects(s), the given oDefaultForCreation is set as new value of the association and returned to the caller. The only supported values for oDefaultForCreation are null and undefined in the case of cardinality 0..1 and null, undefined or an empty array ([]) in case of cardinality 0..n. If the argument is omitted, null is used independently from the cardinality.

Note: the need to specify a default value and the fact that it is stored as new value of a so far empty association is recognized as a shortcoming of this API but can no longer be changed for compatibility reasons.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically retrieve the content of an association. Use the concrete method getXYZ for association 'XYZ' instead.

Param Type DefaultValue Description
sAssociationName string

the name of the association

oDefaultForCreation object

the object that is used in case the current aggregation is empty (only null or empty array allowed)

getBinding

Get the binding object for a specific aggregation/property

Param Type DefaultValue Description
sName string

the name of the property or aggregation

getBindingContext

Get the binding context of this object for the given model name.

If the object does not have a binding context set on itself and has no own model set, it will use the first binding context defined in its parent hierarchy.

Note: to be compatible with future versions of this API, you must not use the following model names:

Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

Note: A ManagedObject inherits binding contexts from the Core only when it is a descendant of a UIArea.

Param Type DefaultValue Description
sModelName string

the name of the model or undefined

getBindingInfo

Returns the binding info for the given property or aggregation.

The binding info contains information about path, binding object, format options, sorter, filter etc. for the property or aggregation. As the binding object is only created when the model becomes available, the binding property may be undefined.

Param Type DefaultValue Description
sName string

Name of the property or aggregation

getBindingPath

Get the binding path for a specific aggregation/property

Param Type DefaultValue Description
sName string

the name of the property or aggregation

getEventingParent

Returns the parent managed object as new eventing parent to enable control event bubbling or null if this object hasn't been added to a parent yet.

getId

Returns the object's ID.

There is no guarantee or check or requirement for the ID of a ManagedObject to be unique. Only some subclasses of ManagedObject introduce this as a requirement, e.g. Component or Element. All elements existing in the same window at the same time must have different IDs. A new element will fail during construction when the given ID is already used by another element. But there might be a component with the same ID as an element or another ManagedObject.

For the same reason, there is no general lookup for ManagedObjects via their ID. Only for subclasses that enforce unique IDs, there might be lookup mechanisms (e.g. sap.ui.getCore().byId() for elements).

getMetadata

Returns the metadata for the class that this object belongs to.

sap.ui.base.ManagedObject.getMetadata

Returns the metadata for the ManagedObject class.

getModel

Get the model to be used for data bindings with the given model name. If the object does not have a model set on itself, it will use the first model defined in its parent hierarchy.

The name can be omitted to reference the default model or it must be a non-empty string.

Note: to be compatible with future versions of this API, you must not use the following model names:

Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

Param Type DefaultValue Description
sModelName string

name of the model to be retrieved

getObjectBinding

Get the object binding object for a specific model.

Note: to be compatible with future versions of this API, you must not use the following model names:

Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

Param Type DefaultValue Description
sModelName string

Non-empty name of the model or undefined

getOriginInfo

Returns the origin info for the value of the given property.

The origin info might contain additional information for translatable texts. The bookkeeping of this information is not active by default and must be activated by configuration. Even then, it might not be present for all properties and their values depending on where the value came form.

Param Type DefaultValue Description
sPropertyName string

the name of the property

getOwnModels

Returns a map of all models assigned to this ManagedObject.

The default model is available on key undefined.

Note: Models propagated from the parent are not included.

getParent

Returns the parent managed object or null if this object hasn't been added to a parent yet.

The parent returned by this method is the technical parent used for data binding, invalidation, rendering etc. It might differ from the object on which the application originally added this object (the so called 'API parent'): some composite controls internally use hidden controls or containers to store their children. This method will return the innermost container that technically contains this object as a child.

Example:

Assume that a Dialog internally uses a (hidden) VerticalLayout to store its content:

  Dialog (API parent)
   \__ VerticalLayout (hidden composite part)
      \__ Text (API child)

If you add some content by calling the Dialog.prototype.addContent API, this will lead to the following observations:

  oDialog.addContent(oText);
  console.log(oText.getParent() === oDialog);  // false
  console.log(oText.getParent() instanceof VerticalLayout); // true
  console.log(oText.getParent().getParent() === oDialog); // true now, but might fail with later versions

Technically, from API perspective, oText is added as a child to Dialog. But internally, the Dialog adds the child to the hidden VerticalLayout container. If you now call the getParent method of the child, you will get the internal VerticalLayout object and not the Dialog API parent.

Note: The internal (hidden) structure of a composite control is not fixed and may be changed (see also our "Compatibility Rules"). Therefore, you should never rely on a specific structure or object being returned by getParent.

Note: There is no API to determine the original API parent.

getPropagationListeners

get propagation listeners

getProperty

Returns the value for the property with the given sPropertyName.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically retrieve the value of a property. Use the concrete method getXYZ for property 'XYZ' instead.

Param Type DefaultValue Description
sPropertyName string

the name of the property

hasModel

Check if any model is set to the ManagedObject or to one of its parents (including UIArea and Core).

Note: A ManagedObject inherits models from the Core only when it is a descendant of a UIArea.

indexOfAggregation

Searches for the provided ManagedObject in the named aggregation and returns its 0-based index if found, or -1 otherwise. Returns -2 if the given named aggregation is of cardinality 0..1 and doesn't reference the given object.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically determine the position of an object in an aggregation. Use the concrete method indexOfXYZ for aggregation 'XYZ' instead.

Param Type DefaultValue Description
sAggregationName string

the name of the aggregation

oObject sap.ui.base.ManagedObject

the ManagedObject whose index is looked for.

insertAggregation

Inserts managed object oObject to the aggregation named sAggregationName at position iIndex.

If the given object is not valid with regard to the aggregation (if it is not an instance of the type specified for that aggregation) or when the method is called for an aggregation of cardinality 0..1, then an Error is thrown (see #validateAggregation.

If the given index is out of range with respect to the current content of the aggregation, it is clipped to that range (0 for iIndex < 0, n for iIndex > n).

Please note that this method does not work as expected when an object is added that is already part of the aggregation. In order to change the index of an object inside an aggregation, first remove it, then insert it again.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically insert an object into an aggregation. Use the concrete method insertXYZ for aggregation 'XYZ' instead.

Param Type DefaultValue Description
sAggregationName string

the string identifying the aggregation the managed object oObject should be inserted into.

oObject sap.ui.base.ManagedObject

the ManagedObject to add; if empty, nothing is inserted.

iIndex int

the 0-based index the managed object should be inserted at; for a negative value iIndex, oObject is inserted at position 0; for a value greater than the current size of the aggregation, oObject is inserted at the last position

bSuppressInvalidate boolean

if true, this ManagedObject as well as the added child are not marked as changed

invalidate

Marks this object and its aggregated children as 'invalid'.

The term 'invalid' originally was introduced by controls where a change to the object's state made the rendered DOM invalid. Later, the concept of invalidation was moved up in the inheritance hierarchy to ManagedObject, but the term was kept for compatibility reasons.

Managed settings (properties, aggregations, associations) invalidate the corresponding object automatically. Changing the state via the standard mutators, therefore, does not require an explicit call to invalidate. The same applies to changes made via data binding, as it internally uses the standard mutators.

By default, a ManagedObject propagates any invalidation to its parent. Controls or UIAreas handle invalidation on their own by triggering a re-rendering.

isBound

Find out whether a property or aggregation is bound

Param Type DefaultValue Description
sName string

the name of the property or aggregation

isDestroyed

Returns whether this object is destroyed or not. A destroyed object cannot be used anymore.

isDestroyStarted

Checks if an object's destruction has been started. During the descruction of an object its ID is still registered, and child objects could be still aggregated. Creating another object with the same ID would lead to duplicate ID issues. To check if the destruction is finished, call isDestroyed.

isInvalidateSuppressed

Returns whether re-rendering is currently suppressed on this ManagedObject.

isPropertyInitial

Returns whether the given property value is initial and has not been explicitly set or bound. Even after setting the default value or setting null/undefined (which also causes the default value to be set), the property is no longer initial. A property can be reset to initial state by calling resetProperty(sPropertyName).

Param Type DefaultValue Description
sPropertyName string

the name of the property

isTreeBinding

This method is used internally and should only be overridden by a tree managed object which utilizes the tree binding. In this case and if the aggregation is a tree node the overridden method should then return true. If true is returned the tree binding will be used instead of the list binding.

Param Type DefaultValue Description
sName string

the aggregation to bind (e.g. nodes for a tree managed object)

onOwnerActivation

This lifecycle hook is called during activation of the owner component

onOwnerDeactivation

This lifecycle hook is called during deactivation of the owner component

propagateMessages

Generic method which is called, whenever messages for this object exist.

Param Type DefaultValue Description
sName string

The property name

aMessages array

The messages

refreshAggregation

Generic method which can be called, when an aggregation needs to be refreshed. This method does not make any change on the aggregation, but just calls the getContexts method of the binding to trigger fetching of new data.

Subclasses should call this method only in the implementation of a named refresh method and for no other purposes. The framework might change the conditions under which the method is called and the method implementation might rely on those conditions.

Param Type DefaultValue Description
sName string

name of the aggregation to refresh

sChangeReason sap.ui.model.ChangeReason

the change reason

removeAggregation

Removes an object from the aggregation named sAggregationName with cardinality 0..n.

The removed object is not destroyed nor is it marked as changed.

If the given object is found in the aggregation, it is removed, it's parent relationship is unset and this ManagedObject is marked as changed. The removed object is returned as result of this method. If the object could not be found, undefined is returned.

This method must only be called for aggregations of cardinality 0..n. The only way to remove objects from a 0..1 aggregation is to set a null value for them.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically remove an object from an aggregation. Use the concrete method removeXYZ for aggregation 'XYZ' instead.

Param Type DefaultValue Description
sAggregationName string

the string identifying the aggregation that the given object should be removed from

vObject int string sap.ui.base.ManagedObject

the position or ID of the ManagedObject that should be removed or that ManagedObject itself; if vObject is invalid, a negative value or a value greater or equal than the current size of the aggregation, nothing is removed.

bSuppressInvalidate boolean

if true, this ManagedObject is not marked as changed

removeAllAggregation

Removes all objects from the 0..n-aggregation named sAggregationName.

The removed objects are not destroyed nor are they marked as changed.

Additionally, it clears the parent relationship of all removed objects, marks this ManagedObject as changed and returns an array with the removed objects.

If the aggregation did not contain any objects, an empty array is returned and this ManagedObject is not marked as changed.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically remove all objects from an aggregation. Use the concrete method removeAllXYZ for aggregation 'XYZ' instead.

Param Type DefaultValue Description
sAggregationName string

Name of the aggregation to remove all objects from

bSuppressInvalidate boolean false

If true, this ManagedObject is not marked as changed

removeAllAssociation

Removes all the objects in the 0..n-association named sAssociationName and returns an array with their IDs. This ManagedObject is marked as changed, if the association contained any objects.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically remove all object from an association. Use the concrete method removeAllXYZ for association 'XYZ' instead.

Param Type DefaultValue Description
sAssociationName string

the name of the association

bSuppressInvalidate boolean

if true, this ManagedObject is not marked as changed

removeAssociation

Removes a ManagedObject from the association named sAssociationName.

If an object is removed, the ID of that object is returned and this ManagedObject is marked as changed. Otherwise null is returned.

If the same object was added multiple times to the same association, only a single occurrence of it will be removed by this method. If the object is not found or if the parameter can't be interpreted neither as a ManagedObject (or ID) nor as an index in the association, nothing will be removed. The same is true if an index is given and if that index is out of range for the association.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically remove an object from an association. Use the concrete method removeXYZ for association 'XYZ' instead.

Param Type DefaultValue Description
sAssociationName string

the string identifying the association the ManagedObject should be removed from.

vObject int string sap.ui.base.ManagedObject

the position or ID of the ManagedObject to remove or the ManagedObject itself; if vObject is invalid input, a negative value or a value greater or equal than the current size of the association, nothing is removed

bSuppressInvalidate boolean

if true, the managed object is not marked as changed

removePropagationListener

remove a propagation listener

Param Type DefaultValue Description
listener function

function

resetProperty

Resets the given property to the default value and also restores the "initial" state (like it has never been set).

As subclasses might have implemented side effects in the named setter setXYZ for property 'xyz', that setter is called with a value of null, which by convention restores the default value of the property. This is only done to notify subclasses, the internal state is anyhow reset.

When the property has not been modified so far, nothing will be done.

Param Type DefaultValue Description
sPropertyName string

Name of the property

sap.ui.base.ManagedObject.runWithPreprocessors

Activates the given ID and settings preprocessors, executes the given function and restores the previously active preprocessors.

When a preprocessor is not defined in oPreprocessors, then the currently active preprocessor is temporarily deactivated while fn is executed.

See the _fnIdPreprocessor and _fnSettingsPreprocessor members in this class for a detailed description of the preprocessors.

This method is intended for internal use in the sap/ui/base and sap/ui/core packages only.

Param Type DefaultValue Description
fn function

Function to execute

oPreprocessors object

Preprocessors to use while executing fn

id function

ID preprocessor that can transform the ID of a new ManagedObject

settings function

Settings preprocessor that can modify settings before they are applied

oThisArg Object

Value to use as this when executing fn

setAggregation

Sets a new object in the named 0..1 aggregation of this ManagedObject and marks this ManagedObject as changed.

If the given object is not valid with regard to the aggregation (if it is not an instance of the type specified for that aggregation) or when the method is called for an aggregation of cardinality 0..n, then an Error is thrown (see #validateAggregation.

If the new object is the same as the currently aggregated object, then the internal state is not modified and this ManagedObject is not marked as changed.

If the given object is different, the parent of a previously aggregated object is cleared (it must have been this ManagedObject before), the parent of the given object is set to this ManagedObject and #invalidate is called for this object.

Note that this method does neither return nor destroy the previously aggregated object. This behavior is inherited by named set methods (see below) in subclasses. To avoid memory leaks, applications therefore should first get the aggregated object, keep a reference to it or destroy it, depending on their needs, and only then set a new object.

Note that ManagedObject only implements a single level of change tracking: if a first call to setAggregation recognizes a change, 'invalidate' is called. If another call to setAggregation reverts that change, invalidate() will be called again, the new status is not recognized as being 'clean' again.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically set an object in an aggregation. Use the concrete method setXYZ for aggregation 'XYZ' or the generic #applySettings instead.

Param Type DefaultValue Description
sAggregationName string

name of an 0..1 aggregation

oObject object

the managed object that is set as aggregated object

bSuppressInvalidate boolean

if true, this ManagedObject is not marked as changed

setAssociation

Sets the associated object for the given managed association of cardinality '0..1' and marks this ManagedObject as changed.

The associated object can either be given by itself or by its id. If null or undefined is given, the association is cleared.

Note: This method is a low-level API as described in the class documentation. Applications or frameworks must not use this method to generically set an object in an association. Use the concrete method setXYZ for association 'XYZ' or the generic #applySettings instead.

Param Type DefaultValue Description
sAssociationName string

name of the association

sId string sap.ui.base.ManagedObject

the ID of the managed object that is set as an association, or the managed object itself or null

bSuppressInvalidate boolean

if true, the managed objects invalidate method is not called

setBindingContext

Set the binding context for this ManagedObject for the model with the given name.

Note: to be compatible with future versions of this API, you must not use the following model names:

Omitting the model name (or using the value undefined) is explicitly allowed and refers to the default model.

A value of null for oContext hides the parent context. The parent context will no longer be propagated to aggregated child controls. A value of undefined removes a currently active context or a null context and the parent context gets visible and propagated again.

Note: A ManagedObject inherits binding contexts from the Core only when it is a descendant of a UIArea.

Param Type DefaultValue Description
oContext sap.ui.model.Context

the new binding context for this object

sModelName string

the name of the model to set the context for or undefined

setModel

Sets or unsets a model for the given model name for this ManagedObject.

The sName must either be undefined (or omitted) or a non-empty string. When the name is omitted, the default model is set/unset. To be compatible with future versions of this API, you must not use the following model names:

When oModel is null or undefined, a previously set model with that name is removed from this ManagedObject. If an ancestor (parent, UIArea or Core) has a model with that name, this ManagedObject will immediately inherit that model from its ancestor.

All local bindings that depend on the given model name are updated (created if the model references became complete now; updated, if any model reference has changed; removed if the model references became incomplete now).

Any change (new model, removed model, inherited model) is also applied to all aggregated descendants as long as a descendant doesn't have its own model set for the given name.

Note: By design, it is not possible to hide an inherited model by setting a null or undefined model. Applications can set an empty model to achieve the same.

Note: A ManagedObject inherits models from the Core only when it is a descendant of a UIArea.

Param Type DefaultValue Description
oModel sap.ui.model.Model null undefined

Model to be set or null or undefined

sName string

the name of the model or undefined

setProperty

Sets the given value for the given property after validating and normalizing it, marks this object as changed.

If the value is not valid with regard to the declared data type of the property, an Error is thrown. In case null or undefined is passed, the default value for this property is used (see #validateProperty). To fully reset the property to initial state, use #resetProperty instead. If the validated and normalized oValue equals the current value of the property, the internal state of this object is not changed (apart from the result of #isPropertyInitial). If the value changes, it is stored internally and the #invalidate method is called on this object. In the case of TwoWay databinding, the bound model is informed about the property change.

Note that ManagedObject only implements a single level of change tracking: if a first call to setProperty recognizes a change, 'invalidate' is called. If another call to setProperty reverts that change, invalidate() will be called again, the new status is not recognized as being 'clean' again.

Note: This method is a low level API as described in the class documentation. Applications or frameworks must not use this method to generically set a property. Use the concrete method setXYZ for property 'XYZ' or the generic #applySettings instead.

Param Type DefaultValue Description
sPropertyName string

name of the property to set

oValue any

value to set the property to

bSuppressInvalidate boolean

if true, the managed object is not marked as changed

toString

Returns a simple string representation of this managed object.

Mainly useful for tracing purposes.

unbindAggregation

Unbind the aggregation from the model.

After unbinding, the current content of the aggregation is destroyed by default. When the bSuppressReset parameter is set, it is however retained.

Param Type DefaultValue Description
sName string

Name of the aggregation

bSuppressReset boolean

Indicates whether destroying the content of the aggregation is skipped

unbindContext

Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.

Since 1.11.1 please use {@link #unbindObject} instead.
Param Type DefaultValue Description
sModelName string

name of the model to remove the context for.

unbindObject

Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.

Param Type DefaultValue Description
sModelName string

Name of the model to remove the context for.

unbindProperty

Unbind the property from the model

Param Type DefaultValue Description
sName string

the name of the property

bSuppressReset boolean

whether the reset to the default value when unbinding should be suppressed

updateAggregation

Generic method which is called whenever an aggregation binding has changed.

Depending on the type of the list binding and on additional configuration, this method either destroys all elements in the aggregation sName and recreates them anew or tries to reuse as many existing objects as possible. It is up to the method which strategy it uses.

In case a managed object needs special handling for an aggregation binding, it can create a named update method (e.g. updateRows for an aggregation rows) which then will be called by the framework instead of this generic method. THe method will be called with two arguments sChangeReason and oEventInfo.

Subclasses should call this method only in the implementation of such a named update method and for no other purposes. The framework might change the conditions under which the method is called and the method implementation might rely on those conditions.

Param Type DefaultValue Description
sName string

Name of the aggregation to update

sChangeReason sap.ui.model.ChangeReason

One of the predefined reasons for the change event

oEventInfo object

Additional information about the change event

detailedReason string

A non-standardized string that further classifies the change event. Model implementations should document any value that they might provide as detailed reason, and describe under what circumstances each value will be used.

validateAggregation

Checks whether the given value is of the proper type for the given aggregation name.

This method is already called by #setAggregation, #addAggregation and #insertAggregation. In many cases, subclasses of ManagedObject don't need to call it again in their mutator methods.

Param Type DefaultValue Description
sAggregationName string

the name of the aggregation

oObject sap.ui.base.ManagedObject any

the aggregated object or a primitive value

bMultiple boolean

whether the caller assumes the aggregation to have cardinality 0..n

validateProperty

Checks whether the given value is of the proper type for the given property name.

In case null or undefined is passed, the default value for this property is used as value. If no default value is defined for the property, the default value of the type of the property is used.

If the property has a data type that is an instance of sap.ui.base.DataType and if a normalize function is defined for that type, that function will be called with the resulting value as only argument. The result of the function call is then used instead of the raw value.

This method is called by #setProperty. In many cases, subclasses of ManagedObject don't need to call it themselves.

Param Type DefaultValue Description
sPropertyName string

Name of the property

oValue any

Value to be set