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:
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.
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.
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.
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).
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.
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:
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);
metadataContexts : object
an array of single binding contexts keyed by the corresponding model or context name. The purpose of the metadataContexts
special setting is to deduce as much information as possible from the binding context of the control in order to be able to predefine certain standard properties like e.g. visible, enabled, tooltip,...The structure is an array of single contexts, where a single context is a map containing the following keys:
path: string (mandatory)
The path to the corresponding model property or object, e.g. '/Customers/Name'. A path can also be relative, e.g. 'Name'model: string (optional)
The name of the model, in case there is no name then the undefined model is takenname: string (optional)
A name for the context to used in templating phasekind: string (optional)
The kind of the adapter, either field
for single properties or object
for structured contexts. adapter: string (optional)
The path to an interpretion class that dilivers control relevant data depending on the context, e.g. enabled, visible. If not supplied the OData meta data is interpreted.metadataContexts
is as follows: {SINGLE_CONTEXT1},...,{SINGLE_CONTEXTn}
or for simplicity in case there is only one context {SINGLE_CONTEXT}
.Examples for such metadataContexts are:
{/Customers/Name}
a single part with an absolute path to the property Name of the Customers entity set in the default model{path: 'Customers/Name', model:'json'}
a single part with an absolute path to the property Name of the Customers entity set in a named model{parts: [{path: 'Customers/Name'},{path: 'editable', model: 'viewModel'}]}
a combination of single binding contexts, one context from the default model and one from the viewModelnew 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? | 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, |
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. |
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. |
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 |
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 |
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 |
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. |
Method | Description |
---|---|
_onContextualSettingsChanged |
Hook method to let descendants of ManagedObject know when propagated contextual settings have changed |
addAggregation |
Adds some entity 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 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 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 |
attachFormatError |
Attaches event handler When called, the context of the event handler (its 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 When called, the context of the event handler (its Fired when models or contexts are changed on this object (either by calling setModel/setBindingContext or due to propagation) |
attachParseError |
Attaches event handler When called, the context of the event handler (its 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 When called, the context of the event handler (its 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 When called, the context of the event handler (its 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 Also see List Binding (Aggregation Binding) in the documentation. For more information on the |
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 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 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 Composite Binding 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 Static Binding Also see StaticBinding in the documentation. Formatter Functions When the formatter for a property binding (simple or composite) is called, the managed object will be given as 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 The
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 ( Custom controls however can override Applications must never provide the second parameter |
sap.ui.base.ManagedObject.create |
Creates a new ManagedObject from the given data. If |
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 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 The passed function and listener object must match the ones used for event registration. |
detachModelContextChange |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachParseError |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachValidationError |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachValidationSuccess |
Detaches event handler 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
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 'properties' : object
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:
'defaultProperty' : string 'aggregations' : object
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:
'defaultAggregation' : string <!-- assuming the defaultAggregation for Dialog is 'content' --> <Dialog> <Text/> <Button/> </Dialog> 'associations' : object
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:
'events' : object
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 |
findAggregatedObjects |
Searches and returns all aggregated objects that pass the given check function. When the search is done recursively ( If no check function is given, all aggregated objects will pass the check and be added to the result array. When setting 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 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 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:
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 |
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 |
getId |
Returns the object's ID. There is no guarantee or check or requirement for the ID of a For the same reason, there is no general lookup for |
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:
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:
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 Note: Models propagated from the parent are not included. |
getParent |
Returns the parent managed object or 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 (API parent) \__ VerticalLayout (hidden composite part) \__ Text (API child) If you add some content by calling the 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, 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 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 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 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 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 By default, a |
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 |
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 |
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 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 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, 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 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 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 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 If an object is removed, the ID of that object is returned and this 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 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 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 See the 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 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:
undefined ) is explicitly allowed and refers to the default model.A value of 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
When 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 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 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 |
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 In case a managed object needs special handling for an aggregation binding, it can create a named update method (e.g. 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 If the property has a data type that is an instance of sap.ui.base.DataType and if a This method is called by #setProperty. In many cases, subclasses of ManagedObject don't need to call it themselves. |
Hook method to let descendants of ManagedObject know when propagated contextual settings have changed
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 | 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 |
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 |
|
bSuppressInvalidate | boolean |
if true, this managed object as well as the newly associated object are not marked as changed |
Adds a listener function that will be called during each propagation step on every control
Param | Type | DefaultValue | Description |
---|---|---|---|
listener | function |
function |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPath | string |
the binding path |
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 ManagedObject
s. 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 | string |
Name of the model to bind against; when |
|
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 |
|
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 |
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 |
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:
cloneChildren
specifies whether associations/aggregations will be clonedcloneBindings
specifies if bindings will be clonedoOptions
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:
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
)cloneBindings
is false
, also the ones that are bound will be cloned; they are all cloned recursively using the same sIdSuffix
setModel()
; used by reference.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()
.
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 |
cloneChildren | boolean | false |
Whether associations and aggregations will be cloned |
cloneBindings | boolean | false |
Whether bindings will be cloned |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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, MiscdefaultValue: 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
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.
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:
'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: string
A 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: string
The 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: string
The 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]: boolean
Whether 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
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.
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:
undefined
[]
'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 associationmultiple: 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.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:
undefined
[]
'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 sourceparameters: object
an object literal that describes the parameters of this 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 |
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 |
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. |
Fires event modelContextChange to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
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 |
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 |
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. |
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. |
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) |
Get the binding object for a specific aggregation/property
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
the name of the property or aggregation |
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
""
"null"
or "undefined"
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 |
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 |
Get the binding path for a specific aggregation/property
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
the name of the property or aggregation |
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 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 ManagedObject
s via their ID. Only for subclasses that enforce unique IDs, there might be lookup mechanisms (e.g. sap.ui.getCore().byId() for elements).
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
""
"null"
or "undefined"
undefined
) is explicitly allowed and refers to the default model.
Param | Type | DefaultValue | Description |
---|---|---|---|
sModelName | string |
name of the model to be retrieved |
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
""
"null"
or "undefined"
undefined
) is explicitly allowed and refers to the default model.
Param | Type | DefaultValue | Description |
---|---|---|---|
sModelName | string |
Non-empty name of the model or |
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 |
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.
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.
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 |
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.
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. |
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 | sap.ui.base.ManagedObject |
the ManagedObject to add; if empty, nothing is inserted. |
|
iIndex | int |
the |
|
bSuppressInvalidate | boolean |
if true, this ManagedObject as well as the added child are not marked as changed |
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.
Find out whether a property or aggregation is bound
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
the name of the property or aggregation |
Returns whether this object is destroyed or not. A destroyed object cannot be used anymore.
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
.
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 |
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) |
Generic method which is called, whenever messages for this object exist.
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
The property name |
|
aMessages | array |
The messages |
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 |
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 |
|
bSuppressInvalidate | boolean |
if true, this ManagedObject is not marked as changed |
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 |
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 |
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 |
|
vObject | int string sap.ui.base.ManagedObject |
the position or ID of the |
|
bSuppressInvalidate | boolean |
if |
remove a propagation listener
Param | Type | DefaultValue | Description |
---|---|---|---|
listener | function |
function |
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 |
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 |
|
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 |
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 |
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 |
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
""
"null"
or "undefined"
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 |
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
""
"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.
Param | Type | DefaultValue | Description |
---|---|---|---|
oModel | sap.ui.model.Model null undefined |
Model to be set or |
|
sName | string |
the name of the model or |
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 |
Returns a simple string representation of this managed object.
Mainly useful for tracing purposes.
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 |
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. |
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. |
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 |
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. |
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 |
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 |