Class sap.ui.base.ManagedObjectModule: sap/ui/base/ManagedObject

extends EventProvider
known direct subclasses: Action, Component, ContentResource, Element, ExportColumn, ExportRow, ExportType, Fragment, LayerProxy, Matcher, MockServer, MockServer, NavigationPopoverHandler, NodeProxy, Popup, SvgDef, TablePersoController, TablePersoController, TablePersoDialog, TablePersoProvider, Template, UIArea, ViewStateManager

Base Class that introduces some basic concepts like state management or databinding.

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, 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 it 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 it 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 a managed events, 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.

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 reflect 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.

Experimental API:Since 1.11.2. ManagedObject as such is public and usable. Only the support for the optional parameter oScope in the constructor is still experimental and might change in future versions. Applications should not rely on it.

Constructor Summary
new sap.ui.base.ManagedObject(sId?, mSettings?, oScope?)Constructs and initializes a managed object with the given sId and settings.
Event Summary
formatError(oControlEvent)Fired when a new value for a bound property should have been propagated from the model, but formatting the value failed with an exception.
modelContextChange(oControlEvent)Fired when models or contexts are changed on this object (either by calling setModel/setBindingContext or due to propagation)
parseError(oControlEvent)Fired when a new value for a bound property should have been propagated to the model, but parsing the value failed with an exception.
validationError(oControlEvent)Fired when a new value for a bound property should have been propagated to the model, but validating the value failed with an exception.
validationSuccess(oControlEvent)Fired after a new value for a bound property has been propagated to the model.
Method Summary
sap.ui.base.ManagedObject.create(vData, oKeyInfo, oScope?)Creates a new ManagedObject from the given data.
sap.ui.base.ManagedObject.extend(sClassName, oClassInfo?, FNMetaImpl?)Defines a new subclass of ManagedObject with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.base.ManagedObject.getMetadata()Returns the metadata for the ManagedObject class.
addAggregation(sAggregationName, oObject, bSuppressInvalidate?)Adds some entity oObject to the aggregation identified by sAggregationName.
addAssociation(sAssociationName, sId, bSuppressInvalidate?)Adds some object with the ID sId to the association identified by sAssociationName and marks this ManagedObject as changed.
applySettings(mSettings, oScope?)Sets all the properties, aggregations, associations and event handlers as given in the object literal mSettings.
attachFormatError(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the formatError event of this sap.ui.base.ManagedObject.
attachModelContextChange(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the modelContextChange event of this sap.ui.base.ManagedObject.
attachParseError(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the parseError event of this sap.ui.base.ManagedObject.
attachValidationError(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the validationError event of this sap.ui.base.ManagedObject.
attachValidationSuccess(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the validationSuccess event of this sap.ui.base.ManagedObject.
bindAggregation(sName, oBindingInfo)Bind an aggregation to the model.
bindObject(vPath, mParameters?)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.
bindProperty(sName, oBindingInfo)Bind a property to the model.
clone(sIdSuffix?, aLocalIds?, oOptions?)Clones a tree of objects starting with the object on which clone is called first (root object).
destroy(bSuppressInvalidate?)Cleans up the resources associated with this object and all its aggregated children.
destroyAggregation(sAggregationName, bSuppressInvalidate?)Destroys (all) the managed object(s) in the aggregation named sAggregationName and empties the aggregation.
detachFormatError(fnFunction, oListener)Detaches event handler fnFunction from the formatError event of this sap.ui.base.ManagedObject.
detachModelContextChange(fnFunction, oListener)Detaches event handler fnFunction from the modelContextChange event of this sap.ui.base.ManagedObject.
detachParseError(fnFunction, oListener)Detaches event handler fnFunction from the parseError event of this sap.ui.base.ManagedObject.
detachValidationError(fnFunction, oListener)Detaches event handler fnFunction from the validationError event of this sap.ui.base.ManagedObject.
detachValidationSuccess(fnFunction, oListener)Detaches event handler fnFunction from the validationSuccess event of this sap.ui.base.ManagedObject.
findAggregatedObjects(bRecursive, fnCondition)Searches and returns an array of child elements and controls which are referenced within an aggregation or aggregations of child elements/controls.
fireFormatError(mArguments?)Fires event formatError to attached listeners.
fireModelContextChange(mArguments?)Fires event modelContextChange to attached listeners.
fireParseError(mArguments?)Fires event parseError to attached listeners.
fireValidationError(mArguments?)Fires event validationError to attached listeners.
fireValidationSuccess(mArguments?)Fires event validationSuccess to attached listeners.
getAggregation(sAggregationName, oDefaultForCreation)Returns the aggregated object(s) for the named aggregation of this ManagedObject.
getAssociation(sAssociationName, oDefaultForCreation)Returns the content of the association wit hthe given name.
getBinding(sName)Get the binding object for a specific aggregation/property
getBindingContext(sModelName?)Get the binding context of this object for the given model name.
getBindingInfo(sName)Returns the binding infos for the given property or aggregation.
getBindingPath(sName)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.
getMetadata()Returns the metadata for the class that this object belongs to.
getModel(sName?)Get the model to be used for data bindings with the given model name.
getObjectBinding(sModelName)Get the object binding object for a specific model
getOriginInfo(sPropertyName)Returns the origin info for the value of the given property.
getParent()Returns the parent managed object or null if this object hasn't been added to a parent yet.
getProperty(sPropertyName)Returns the value for the property with the given sPropertyName.
hasModel()Check if any model is set to the ManagedObject or to one of its parents (including UIArea and Core).
indexOfAggregation(sAggregationName, oObject)Searches for the provided ManagedObject in the named aggregation and returns its 0-based index if found, or -1 otherwise.
insertAggregation(sAggregationName, oObject, iIndex, bSuppressInvalidate?)Inserts managed object oObject to the aggregation named sAggregationName at position iIndex.
invalidate()This triggers rerendering of itself and its children.
isBound(sName)Find out whether a property or aggregation is bound
isInvalidateSuppressed()Returns whether rerendering is currently suppressed on this ManagedObject
isTreeBinding(sName)This method is used internally and should only be overridden by a tree managed object which utilizes the tree binding.
propagateMessages(sName, aMessages)Generic method which is called, whenever messages for this object exists.
removeAggregation(sAggregationName, vObject, bSuppressInvalidate?)Removes an object from the aggregation named sAggregationName with cardinality 0.
removeAllAggregation(sAggregationName, bSuppressInvalidate?)Removes all objects from the 0.
removeAllAssociation(sAssociationName, bSuppressInvalidate?)Removes all the objects in the 0.
removeAssociation(sAssociationName, vObject, bSuppressInvalidate?)Removes a ManagedObject from the association named sAssociationName.
setAggregation(sAggregationName, oObject, bSuppressInvalidate?)Sets a new object in the named 0.
setAssociation(sAssociationName, sId, bSuppressInvalidate?)Sets the associatied object for the given managed association of cardinality '0.
setBindingContext(oContext, sModelName?)Set the binding context for this ManagedObject for the model with the given name.
setModel(oModel, sName?)Sets or unsets a model for the given model name for this ManagedObject.
setProperty(sPropertyName, oValue, bSuppressInvalidate?)Sets the given value for the given property after validating and normalizing it, marks this object as changed.
toString()Returns a simple string representation of this managed object.
unbindAggregation(sName, bSuppressReset)Unbind the aggregation from the model
unbindObject(sModelName?)Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.
unbindProperty(sName, bSuppressReset)Unbind the property from the model
validateAggregation(sAggregationName, oObject, bMultiple)Checks whether the given value is of the proper type for the given aggregation name.
validateProperty(sPropertyName, oValue)Checks whether the given value is of the proper type for the given property name.
bindContext(sPath)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.
unbindContext(sModelName?)Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.
Methods borrowed from class sap.ui.base.EventProvider
attachEvent, attachEventOnce, detachEvent, fireEvent, hasListeners
Methods borrowed from class sap.ui.base.Object
getInterface
Constructor Detail
new sap.ui.base.ManagedObject(sId?, mSettings?, oScope?)
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.

If a key name is ambiguous for a specific managed object class (e.g. a property has the same name as an event), then this method prefers property, aggregation, association and event in that order. To resolve such ambiguities, the keys can be prefixed with aggregation:, association: or event: (such keys containing a colon (':') must be quoted to be valid Javascript).

The possible values for a setting depend on its kind:

  • for simple properties, the value has to match the documented type of the property (no type conversion occurs)
  • for 0..1 aggregations, the value has to be an instance of the aggregated type
  • for 0..n aggregations, the value has to be an array of instances of the aggregated type or a single instance
  • for 0..1 associations, an instance of the associated type or an id (string) is accepted
  • for 0..n associations, an array of instances of the associated type or of Ids is accepted
  • for events either a function (event handler) is accepted or an array of length 2 where the first element is a function and the 2nd element is an object to invoke the method on.

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

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

  • id : sap.ui.core.ID an ID for the new instance. Some subclasses (Element, Component) require the id to be unique in a specific scope (e.g. an Element Id must be unique across all Elements, a Component id must be unique across all Components).
  • models : object a map of sap.ui.model.Model instances keyed by their model name (alias). Each entry with key k in this object has the same effect as a call this.setModel(models[k], k);.
  • bindingContexts : object a map of sap.ui.model.Context instances keyed by their model name. Each entry with key k in this object has the same effect as a call this.setBindingContext(bindingContexts[k], k);
  • objectBindings : object a map of binding paths keyed by the corresponding model name. Each entry with key k in this object has the same effect as a call this.bindObject(objectBindings[k], k);

The supported settings are:

  • Events
    • validationSuccess : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • validationError : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • parseError : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • formatError : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • modelContextChange : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
Parameters:
{string}sId? 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!
{object}mSettings? Optional map/JSON-object with initial property values, aggregated objects etc. for the new object
{object}oScope? 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.
Event Detail
formatError(oControlEvent)
Fired when a new value for a bound property should have been propagated from the model, but formatting the value failed with an exception.
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{sap.ui.base.ManagedObject}oControlEvent.getParameters.element ManagedObject instance whose property should have received the model update.
{string}oControlEvent.getParameters.property Name of the property for which the binding should have been updated.
{sap.ui.model.Type}oControlEvent.getParameters.type Data type used in the binding (if any).
{any}oControlEvent.getParameters.newValue New value (model representation) as propagated from the model.
{any}oControlEvent.getParameters.oldValue Old value (external representation) as previously stored in the ManagedObject.
modelContextChange(oControlEvent)
Fired when models or contexts are changed on this object (either by calling setModel/setBindingContext or due to propagation)
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
parseError(oControlEvent)
Fired when a new value for a bound property should have been propagated to the model, but parsing the value failed with an exception.
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{sap.ui.base.ManagedObject}oControlEvent.getParameters.element ManagedObject instance whose property initiated the model update.
{string}oControlEvent.getParameters.property Name of the property for which the bound model property should have been been updated.
{sap.ui.model.Type}oControlEvent.getParameters.type Data type used in the binding.
{any}oControlEvent.getParameters.newValue New value (external representation) as parsed by the binding.
{any}oControlEvent.getParameters.oldValue Old value (external representation) as previously stored in the ManagedObject.
{string}oControlEvent.getParameters.message Localized message describing the parse error
validationError(oControlEvent)
Fired when a new value for a bound property should have been propagated to the model, but validating the value failed with an exception.
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{sap.ui.base.ManagedObject}oControlEvent.getParameters.element ManagedObject instance whose property initiated the model update.
{string}oControlEvent.getParameters.property Name of the property for which the bound model property should have been been updated.
{sap.ui.model.Type}oControlEvent.getParameters.type Data type used in the binding.
{any}oControlEvent.getParameters.newValue New value (external representation) as parsed and validated by the binding.
{any}oControlEvent.getParameters.oldValue Old value (external representation) as previously stored in the ManagedObject.
{string}oControlEvent.getParameters.message Localized message describing the validation issues
validationSuccess(oControlEvent)
Fired after a new value for a bound property has been propagated to the model. Only fired, when the binding uses a data type.
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{sap.ui.base.ManagedObject}oControlEvent.getParameters.element ManagedObject instance whose property initiated the model update.
{string}oControlEvent.getParameters.property Name of the property for which the bound model property has been updated.
{sap.ui.model.Type}oControlEvent.getParameters.type Data type used in the binding.
{any}oControlEvent.getParameters.newValue 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.

{any}oControlEvent.getParameters.oldValue Old value (external representation) as previously stored in the ManagedObject.
Method Detail
sap.ui.base.ManagedObject.create(vData, oKeyInfo, oScope?)
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 "Type" entry in the vData or by a type information in the oKeyInfo object

Parameters:
{sap.ui.base.ManagedObject|object}vData the data to create the object from
{object}oKeyInfo
{object}oScope? Scope object to resolve types and formatters in bindings
sap.ui.base.ManagedObject.extend(sClassName, oClassInfo?, FNMetaImpl?): function
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
  • 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 : {
      width: 'sap.ui.core.CSSSize',
      height: { type: 'sap.ui.core.CSSSize', defaultValue: '100%' }
    },
    aggregations : {
      header : { type: 'sap.mylib.FancyHeader', multiple : false }
      items : 'sap.ui.core.Control'
    },
    defaultAggregation : 'items',
    associations : {
      initiallyFocused : { type: 'sap.ui.core.Control' }
    },
    events: {
      beforeOpen : {
        parameters : {
          opener : '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' 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.
  • group: ...
  • 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.
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

'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 (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)
  • 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.
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
  • removeItem(v) - removes an object from the aggregation 'items'. Internally calls removeAggregation
  • removeItems() - removes all object 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 private or 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.
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

'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 lowercase 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 USED by controls or applications outside of the sap.ui.core project.

Experimental API:Since 1.27.0 Support for 'specialSettings' is experimental and might be modified or removed in future versions. They must not be used in any way outside of the sap.ui.core library. Code outside sap.ui.core must not declare special settings nor must it try to retrieve / evaluate metadata for such settings.

Parameters:
{string}sClassName name of the class to be created
{object}oClassInfo? object literal with informations about the class
{function}FNMetaImpl? constructor function for the metadata object. If not given, it defaults to sap.ui.core.ManagedObjectMetadata.
Experimental:
Since 1.27.0 Support for 'specialSettings' is experimental and might be modified or removed in future versions. They must not be used in any way outside of the sap.ui.core library. Code outside sap.ui.core must not declare special settings nor must it try to retrieve / evaluate metadata for such settings.
Returns:
{function} the created class / constructor function
sap.ui.base.ManagedObject.getMetadata(): sap.ui.base.ManagedObjectMetadata
Returns the metadata for the ManagedObject class.
Returns:
{sap.ui.base.ManagedObjectMetadata} Metadata for the ManagedObject class.
addAggregation(sAggregationName, oObject, bSuppressInvalidate?): sap.ui.base.ManagedObject
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.

Parameters:
{string}sAggregationName the string identifying the aggregation that oObject should be added to.
{sap.ui.base.ManagedObject}oObject the object to add; if empty, nothing is added
{boolean}bSuppressInvalidate? if true, this ManagedObject as well as the added child are not marked as changed
Returns:
{sap.ui.base.ManagedObject} Returns this to allow method chaining
addAssociation(sAssociationName, sId, bSuppressInvalidate?): sap.ui.base.ManagedObject
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.

Parameters:
{string}sAssociationName the string identifying the association the object should be added to.
{string|sap.ui.base.ManagedObject}sId 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
{boolean}bSuppressInvalidate? if true, this managed object as well as the newly associated object are not marked as changed
Returns:
{sap.ui.base.ManagedObject} Returns this to allow method chaining
applySettings(mSettings, oScope?): sap.ui.base.ManagedObject
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.

Experimental API:Since 1.11.2 support for the scope object for resolving string based type and formatter references in bindings is still experimental

Parameters:
{object}mSettings the settings to apply to this managed object
{object}oScope? Scope object to resolve types and formatters
Experimental:
Since 1.11.2 support for the scope object for resolving string based type and formatter references in bindings is still experimental
Returns:
{sap.ui.base.ManagedObject} Returns this to allow method chaining
attachFormatError(oData?, fnFunction, oListener?): sap.ui.base.ManagedObject
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.

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
attachModelContextChange(oData?, fnFunction, oListener?): sap.ui.base.ManagedObject
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)

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
attachParseError(oData?, fnFunction, oListener?): sap.ui.base.ManagedObject
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.

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
attachValidationError(oData?, fnFunction, oListener?): sap.ui.base.ManagedObject
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.

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
attachValidationSuccess(oData?, fnFunction, oListener?): sap.ui.base.ManagedObject
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.

Parameters:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.ui.base.ManagedObject itself
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
bindAggregation(sName, oBindingInfo): sap.ui.base.ManagedObject
Bind an aggregation to the model.

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 managed object may flag aggregations in the metamodel with bindable="bindable" to get typed bindSomething methods for those aggregations.

Parameters:
{string}sName the aggregation to bind
{object}oBindingInfo the binding info
{string}oBindingInfo.path the binding path
{sap.ui.base.ManagedObject}oBindingInfo.template the template to clone for each item in the aggregation
{boolean}oBindingInfo.templateShareable?, Default: true option to enable that the template will be shared which means that it won't be destroyed or cloned automatically
{function}oBindingInfo.factory the factory function
{number}oBindingInfo.startIndex the first entry of the list to be created
{number}oBindingInfo.length the amount of entries to be created (may exceed the sizelimit of the model)
{sap.ui.model.Sorter|sap.ui.model.Sorter[]}oBindingInfo.sorter? the initial sort order (optional)
{sap.ui.model.Filter[]}oBindingInfo.filters? the predefined filters for this aggregation (optional)
{string|function}oBindingInfo.key the name of the key property or a function getting the context as only parameter to calculate a key for entries. This can be used to improve udpate behaviour in models, where a key is not already available.
{object}oBindingInfo.parameters? a map of parameters which is passed to the binding. The supported parameters are listed in the corresponding model-specific implementation of sap.ui.model.ListBinding or sap.ui.model.TreeBinding.
{function}oBindingInfo.groupHeaderFactory? a factory function to generate custom group visualization (optional)
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself
bindObject(vPath, mParameters?): sap.ui.base.ManagedObject
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. If a relative binding path is used, this will be applied whenever the parent context changes.
Parameters:
{string|object}vPath the binding path or an object with more detailed binding options
{string}vPath.path the binding path
{object}vPath.parameters? map of additional parameters for this binding
{string}vPath.model? name of the model
{object}vPath.events? map of event listeners for the binding events
{object}mParameters? map of additional parameters for this binding (only taken into account when vPath is a string in that case the properties described for vPath above are valid here). The supported parameters are listed in the corresponding model-specific implementation of sap.ui.model.ContextBinding.
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself
bindProperty(sName, oBindingInfo): sap.ui.base.ManagedObject
Bind a property to the model. The Setter for the given property will be called with the value retrieved from the data model. This is a generic method which can be used to bind any property to the model. A managed object may flag properties in the metamodel with bindable="bindable" to get typed bind methods for a property. A composite property binding which may have multiple paths (also known as Calculated Fields) can be declared using the parts parameter. Note a composite binding is read only (One Way).
Parameters:
{string}sName the name of the property
{object}oBindingInfo the binding information
{string}oBindingInfo.path the binding path
{string}oBindingInfo.model? the model identifier
{function}oBindingInfo.formatter? the formatter function
{boolean}oBindingInfo.useRawValues? determines if the parameters in the formatter functions should be passed as raw values or not. In this case the specified type for the binding is not used and the values are not formatted. Note: use this flag only when using multiple bindings. If you use only one binding and want raw values then simply don't specify a type for that binding.
{sap.ui.model.Type|string}oBindingInfo.type? the sap.ui.model.Type object or class name
{object}oBindingInfo.formatOptions? the format options to be used
{object}oBindingInfo.constraints? the constraints for this value
{sap.ui.model.BindingMode}oBindingInfo.mode?, Default: Default the binding mode to be used for this property binding (e.g. one way)
{object}oBindingInfo.parameters? a map of parameters which is passed to the binding. The supported parameters are listed in the corresponding model-specific implementation of sap.ui.model.PropertyBinding.
{object}oBindingInfo.parts? object for definding a read only composite binding which may have multiple binding paths also in different models. 
  oTxt.bindValue({
    parts: [
      {path: "/firstName", type: new sap.ui.model.type.String()},
      {path: "myModel2>/lastName"}
    ]
  });
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself
clone(sIdSuffix?, aLocalIds?, oOptions?): sap.ui.base.ManagedObject
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 wether associations/aggregations will be cloned
  • The boolean value cloneBindings specifies if bindings will be 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 cloneBinding is false even these properties will be cloned; the values are used by reference, they are not cloned
  • all aggregated objects that are not bound. If cloneBinding is false even 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 to 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 infos (path, model name) are 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-existance also serves as an indicator for the root object). Specifying it will break the implementation of clone().

Parameters:
{string}sIdSuffix? a suffix to be appended to the cloned object id
{string[]}aLocalIds? an array of local IDs within the cloned hierarchy (internally used)
{Object}oOptions? configuration object
Returns:
{sap.ui.base.ManagedObject} reference to the newly created clone
destroy(bSuppressInvalidate?)
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 in!

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

Parameters:
{boolean}bSuppressInvalidate? if true, this ManagedObject is not marked as changed
destroyAggregation(sAggregationName, bSuppressInvalidate?): sap.ui.base.ManagedObject
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.

Parameters:
{string}sAggregationName the name of the aggregation
{boolean}bSuppressInvalidate? if true, this ManagedObject is not marked as changed
Returns:
{sap.ui.base.ManagedObject} Returns this to allow method chaining
detachFormatError(fnFunction, oListener): sap.ui.base.ManagedObject
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.

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
detachModelContextChange(fnFunction, oListener): sap.ui.base.ManagedObject
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.

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
detachParseError(fnFunction, oListener): sap.ui.base.ManagedObject
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.

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
detachValidationError(fnFunction, oListener): sap.ui.base.ManagedObject
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.

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
detachValidationSuccess(fnFunction, oListener): sap.ui.base.ManagedObject
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.

Parameters:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
findAggregatedObjects(bRecursive, fnCondition): sap.ui.base.ManagedObject[]
Searches and returns an array of child elements and controls which are referenced within an aggregation or aggregations of child elements/controls. This can be either done recursive or not. Optionally a condition function can be passed that returns true if the object should be added to the array.
Take care: this operation might be expensive.
Parameters:
{boolean}bRecursive true, if all nested children should be returned.
{boolean}fnCondition if given, the object is passed as a parameter to the.
Returns:
{sap.ui.base.ManagedObject[]} array of child elements and controls
fireFormatError(mArguments?): sap.ui.base.ManagedObject
Fires event formatError to attached listeners.

Expects the following event parameters:

  • element of type sap.ui.base.ManagedObjectManagedObject instance whose property should have received the model update.
  • property of type stringName of the property for which the binding should have been updated.
  • type of type sap.ui.model.TypeData type used in the binding (if any).
  • newValue of type anyNew value (model representation) as propagated from the model.
  • oldValue of type anyOld value (external representation) as previously stored in the ManagedObject.
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
fireModelContextChange(mArguments?): sap.ui.base.ManagedObject
Fires event modelContextChange to attached listeners.
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
fireParseError(mArguments?): sap.ui.base.ManagedObject
Fires event parseError to attached listeners.

Expects the following event parameters:

  • element of type sap.ui.base.ManagedObjectManagedObject instance whose property initiated the model update.
  • property of type stringName of the property for which the bound model property should have been been updated.
  • type of type sap.ui.model.TypeData type used in the binding.
  • newValue of type anyNew value (external representation) as parsed by the binding.
  • oldValue of type anyOld value (external representation) as previously stored in the ManagedObject.
  • message of type stringLocalized message describing the parse error
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
fireValidationError(mArguments?): sap.ui.base.ManagedObject
Fires event validationError to attached listeners.

Expects the following event parameters:

  • element of type sap.ui.base.ManagedObjectManagedObject instance whose property initiated the model update.
  • property of type stringName of the property for which the bound model property should have been been updated.
  • type of type sap.ui.model.TypeData type used in the binding.
  • newValue of type anyNew value (external representation) as parsed and validated by the binding.
  • oldValue of type anyOld value (external representation) as previously stored in the ManagedObject.
  • message of type stringLocalized message describing the validation issues
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
fireValidationSuccess(mArguments?): sap.ui.base.ManagedObject
Fires event validationSuccess to attached listeners.

Expects the following event parameters:

  • element of type sap.ui.base.ManagedObjectManagedObject instance whose property initiated the model update.
  • property of type stringName of the property for which the bound model property has been updated.
  • type of type sap.ui.model.TypeData type used in the binding.
  • newValue of type anyNew 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 of type anyOld value (external representation) as previously stored in the ManagedObject.
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.ui.base.ManagedObject} Reference to this in order to allow method chaining
getAggregation(sAggregationName, oDefaultForCreation)
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.

Parameters:
{string}sAggregationName the name of the aggregation
{sap.ui.base.ManagedObject|Array}oDefaultForCreation the object that is used in case the current aggregation is empty
getAssociation(sAssociationName, oDefaultForCreation): string|string[]
Returns the content of the association wit hthe 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.

Parameters:
{string}sAssociationName the name of the association
{object}oDefaultForCreation the object that is used in case the current aggregation is empty (only null or empty array allowed)
Returns:
{string|string[]} the ID of the associated managed object or an array of such IDs; may be null if the association has not been populated
getBinding(sName): sap.ui.model.Binding
Get the binding object for a specific aggregation/property
Parameters:
{string}sName the name of the property or aggregation
Returns:
{sap.ui.model.Binding} the binding for the given name
getBindingContext(sModelName?): sap.ui.model.Context
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, applications must not use the value null, the empty string "" or the string literals "null" or "undefined" as model name.

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

Parameters:
{string}sModelName? the name of the model or undefined
Returns:
{sap.ui.model.Context} oContext The binding context of this object
getBindingInfo(sName): object
Returns the binding infos 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.
Parameters:
{string}sName the name of the property or aggregation
Returns:
{object} the binding info object, containing at least a path property and, dependant of the binding type, additional properties
getBindingPath(sName): string
Get the binding path for a specific aggregation/property
Parameters:
{string}sName the name of the property or aggregation
Returns:
{string} the binding path for the given name
getEventingParent(): sap.ui.base.EventProvider
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.
Returns:
{sap.ui.base.EventProvider} the parent event provider
getId(): string
Returns the object's Id.
Returns:
{string} the objects's Id.
getMetadata(): sap.ui.base.ManagedObjectMetadata
Returns the metadata for the class that this object belongs to.
Returns:
{sap.ui.base.ManagedObjectMetadata} Metadata for the class of the object
getModel(sName?): sap.ui.model.Model
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, applications must not use the value null, the empty string "" or the string literals "null" or "undefined" as model name.

Parameters:
{string|undefined}sName? name of the model to be retrieved
Returns:
{sap.ui.model.Model} oModel
getObjectBinding(sModelName): sap.ui.model.Binding
Get the object binding object for a specific model
Parameters:
{string}sModelName the name of the model
Returns:
{sap.ui.model.Binding} the element binding for the given model name
getOriginInfo(sPropertyName): object
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.

Parameters:
{string}sPropertyName the name of the property
Returns:
{object} a map of properties describing the origin of this property value or null
getParent(): sap.ui.base.ManagedObject
Returns the parent managed object or null if this object hasn't been added to a parent yet.
Returns:
{sap.ui.base.ManagedObject} The parent managed object or null
getProperty(sPropertyName): any
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.

Parameters:
{string}sPropertyName the name of the property
Returns:
{any} the value of the property
hasModel(): boolean
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 an UIArea.

Returns:
{boolean} whether a model reference exists or not
indexOfAggregation(sAggregationName, oObject): int
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.

Parameters:
{string}sAggregationName the name of the aggregation
{sap.ui.base.ManagedObject}oObject the ManagedObject whose index is looked for.
Returns:
{int} the index of the provided managed object in the aggregation.
insertAggregation(sAggregationName, oObject, iIndex, bSuppressInvalidate?): sap.ui.base.ManagedObject
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.

Parameters:
{string}sAggregationName the string identifying the aggregation the managed object oObject should be inserted into.
{sap.ui.base.ManagedObject}oObject the ManagedObject to add; if empty, nothing is inserted.
{int}iIndex 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
{boolean}bSuppressInvalidate? if true, this ManagedObject as well as the added child are not marked as changed
Returns:
{sap.ui.base.ManagedObject} Returns this to allow method chaining
invalidate()
This triggers rerendering of itself and its children.
As sap.ui.base.ManagedObject "bubbles up" the invalidate, changes to child-Elements will also result in rerendering of the whole sub tree.
isBound(sName): boolean
Find out whether a property or aggregation is bound
Parameters:
{string}sName the name of the property or aggregation
Returns:
{boolean} whether a binding exists for the given name
isInvalidateSuppressed()
Returns whether rerendering is currently suppressed on this ManagedObject
isTreeBinding(sName): boolean
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.
Parameters:
{string}sName the aggregation to bind (e.g. nodes for a tree managed object)
Returns:
{boolean} whether tree binding should be used or list binding. Default is false. Override method to change this behavior.
propagateMessages(sName, aMessages)
Generic method which is called, whenever messages for this object exists.
Parameters:
{string}sName The property name
{array}aMessages The messages
Since:
1.28
removeAggregation(sAggregationName, vObject, bSuppressInvalidate?): sap.ui.base.ManagedObject
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 aggreation, 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.

Parameters:
{string}sAggregationName the string identifying the aggregation that the given object should be removed from
{int|string|sap.ui.base.ManagedObject}vObject 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.
{boolean}bSuppressInvalidate? if true, this ManagedObject is not marked as changed
Returns:
{sap.ui.base.ManagedObject} the removed object or null
removeAllAggregation(sAggregationName, bSuppressInvalidate?)
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.

Parameters:
{string}sAggregationName the name of the aggregation
{boolean}bSuppressInvalidate? if true, this ManagedObject is not marked as changed
removeAllAssociation(sAssociationName, bSuppressInvalidate?)
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.

Parameters:
{string}sAssociationName the name of the association
{boolean}bSuppressInvalidate? if true, this ManagedObject is not marked as changed
removeAssociation(sAssociationName, vObject, bSuppressInvalidate?)
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 undefined is returned.

If the same object was added multiple times to the same association, only a single occurence 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 assocation, 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.

Parameters:
{string}sAssociationName the string identifying the association the ManagedObject should be removed from.
{int|string|sap.ui.base.ManagedObject}vObject 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
{boolean}bSuppressInvalidate? if true, the managed object is not marked as changed
setAggregation(sAggregationName, oObject, bSuppressInvalidate?): sap.ui.base.ManagedObject
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.

Parameters:
{string}sAggregationName name of an 0..1 aggregation
{object}oObject the managed object that is set as aggregated object
{boolean}bSuppressInvalidate? if true, this ManagedObject is not marked as changed
Exceptions:
{Error}
Returns:
{sap.ui.base.ManagedObject} Returns this to allow method chaining
setAssociation(sAssociationName, sId, bSuppressInvalidate?): sap.ui.base.ManagedObject
Sets the associatied 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.

Parameters:
{string}sAssociationName name of the association
{string|sap.ui.base.ManagedObject}sId the ID of the managed object that is set as an association, or the managed object itself or null
{boolean}bSuppressInvalidate? if true, the managed objects invalidate method is not called
Returns:
{sap.ui.base.ManagedObject} Returns this to allow method chaining
setBindingContext(oContext, sModelName?): sap.ui.base.ManagedObject
Set the binding context for this ManagedObject for the model with the given name.

Note: to be compatible with future versions of this API, applications must not use the value null, the empty string "" or the string literals "null" or "undefined" as model name.

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

Parameters:
{Object}oContext the new binding context for this object
{string}sModelName? the name of the model to set the context for or undefined
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself
setModel(oModel, sName?): sap.ui.base.ManagedObject
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.

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: to be compatible with future versions of this API, applications must not use the value null, the empty string "" or the string literals "null" or "undefined" as model 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 an UIArea.

Parameters:
{sap.ui.model.Model}oModel the model to be set or null or undefined
{string}sName? the name of the model or undefined
Returns:
{sap.ui.base.ManagedObject}this to allow method chaining
setProperty(sPropertyName, oValue, bSuppressInvalidate?): sap.ui.base.ManagedObject
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. If the validated and normalized oValue equals the current value of the property, the internal state of this object is not changed. 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.

Parameters:
{string}sPropertyName name of the property to set
{any}oValue value to set the property to
{boolean}bSuppressInvalidate? if true, the managed object is not marked as changed
Returns:
{sap.ui.base.ManagedObject} Returns this to allow method chaining
toString(): string
Returns a simple string representation of this managed object.

Mainly useful for tracing purposes.

Returns:
{string} a string description of this managed object
unbindAggregation(sName, bSuppressReset): sap.ui.base.ManagedObject
Unbind the aggregation from the model
Parameters:
{string}sName the name of the aggregation
{boolean}bSuppressReset whether the reset to empty aggregation when unbinding should be suppressed
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself
unbindObject(sModelName?): sap.ui.base.ManagedObject
Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.
Parameters:
{string}sModelName? name of the model to remove the context for.
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself
unbindProperty(sName, bSuppressReset): sap.ui.base.ManagedObject
Unbind the property from the model
Parameters:
{string}sName the name of the property
{boolean}bSuppressReset whether the reset to the default value when unbinding should be suppressed
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself
validateAggregation(sAggregationName, oObject, bMultiple): sap.ui.base.ManagedObject|any
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.

Parameters:
{string}sAggregationName the name of the aggregation
{sap.ui.base.ManagedObject|any}oObject the aggregated object or a primitive value
{boolean}bMultiple whether the caller assumes the aggregation to have cardinality 0..n
Exceptions:
Error if no aggregation with the given name is found or the given value does not fit to the aggregation type
Returns:
{sap.ui.base.ManagedObject|any} the passed object
validateProperty(sPropertyName, oValue): any
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.

Parameters:
{string}sPropertyName the name of the property
{any}oValue the value
Exceptions:
Error if no property with the given name is found or the given value does not fit to the property type
Returns:
{any} the normalized value for the passed value or for the default value if null or undefined was passed
bindContext(sPath): sap.ui.base.ManagedObject
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.
Parameters:
{string}sPath the binding path
Deprecated:
Since 1.11.1, please use bindElement instead.
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself
unbindContext(sModelName?): sap.ui.base.ManagedObject
Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again.
Parameters:
{string}sModelName? name of the model to remove the context for.
Deprecated:
Since 1.11.1, please use unbindElement instead.
Returns:
{sap.ui.base.ManagedObject} reference to the instance itself