Class sap.ui2.srvc.Bag

Defined in: bag.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	sap.ui2.srvc.Bag(oFactory, oAlterEgo, oParentBag, fnChangeListener) Constructs a new representation (wrapper) of the bag with the given bag description as loaded from the given factory's page building service.

Method Summary
Method Attributes	Method Name and Description
	getId() Returns this bag's ID.
	getProperty(sPropertyName, sDefaultValue) Returns the property value for the given property name.
	getPropertyNames() Returns an array containing the names of the (non-translatable) properties contained in this bag.
	getText(sTextName) Returns the translatable text for the given text property name.
	getTextNames() Returns an array containing the names of the translatable text properties contained in this bag.
	reset(fnSuccess, fnError) Discards all modified properties, deletes this bag with all its properties and reloads the bag via the factory given in the constructor.
	resetProperty(sPropertyName) Deletes the property with the given name, no matter if it is translatable or not.
	save(fnSuccess, fnError) Saves this bag with all modified properties.
	setProperty(sPropertyName, sValue) Sets the value for the given property name.
	setText(sTextName, sText) Sets the translatable text for the given text property name.
	toString(bVerbose) Returns this bag's string representation.

Class Detail

sap.ui2.srvc.Bag(oFactory, oAlterEgo, oParentBag, fnChangeListener)

Constructs a new representation (wrapper) of the bag with the given bag description as loaded from the given factory's page building service. A property bag can be associated with a page (see sap.ui2.srvc.Page#getBag), a CHIP instance (see sap.ui2.srvc.ChipInstance#getBag) or a CHIP (see sap.ui2.srvc.Chip#getBag). Such bags take arbitrary name/value pairs consisting of strings.

Parameters:
{sap.ui2.srvc.Factory} oFactory: the factory
{object} oAlterEgo: the bag data including its (optional) properties as loaded via the page building service
{object} oParentBag Optional: a bag which is asked for properties not found in this bag
{function(sap.ui2.srvc.Bag)} fnChangeListener Optional: (since 1.21) a listener to be called (with this bag as an argument) each time this bag changes due to save or reset; the listener is not called in case a backend request fails completely

Since:: 1.3.0

Method Detail

{string} getId()

Returns this bag's ID.

Since:: 1.3.0

Returns:: {string} this bag's ID

{string} getProperty(sPropertyName, sDefaultValue)

Returns the property value for the given property name. If no such property exists, the given default value is returned. As long as a #reset() is running, "old" values are returned.

Parameters:
{string} sPropertyName: the property name
{string} sDefaultValue Optional: default value used if there is no property with given name

Since:: 1.3.0

Throws:
: Error if sPropertyName is a translatable text property name.

Returns:: {string} the property value

{string[]} getPropertyNames()

Returns an array containing the names of the (non-translatable) properties contained in this bag. As long as a #reset() is running, the "old" property names are returned. For an array of translatable text property names see #getTextNames. If #resetProperty() has been called on a not persisted property its name is not contained in the array; for a persisted property it is contained in the array until #save() is called on this bag.

Since:: 1.3.0

Returns:: {string[]} array of (non-translatable) property names

See:: #getTextNames

{string} getText(sTextName)

Returns the translatable text for the given text property name. If no such text property exists, sTextName is returned again. As long as a #reset() is running, "old" texts are returned.

Parameters:
{string} sTextName: the text property name

Since:: 1.17.1

Throws:
: Error if sTextName is an ordinary (non-translatable) property name.

Returns:: {string} the translatable text

{string[]} getTextNames()

Returns an array containing the names of the translatable text properties contained in this bag. As long as a #reset() is running, the "old" property names are returned. For an array of non-translatable property names see #getPropertyNames.

Since:: 1.17.1

Returns:: {string[]} array of translatable text property names

See:: #getPropertyNames

reset(fnSuccess, fnError)

Discards all modified properties, deletes this bag with all its properties and reloads the bag via the factory given in the constructor. If the factory's page building service offers different layers (like sap.ui2.srvc.PageBuildingService, calling them scopes), the values from a lower layer will become visible.

This is an asynchronous operation. If the bag is reset successfully, the success handler is called. If there is an error while resetting the bag, all old values are kept and the error handler is called.

Parameters:
{function ()} fnSuccess: no-args success handler
{function (string|[object])} fnError Optional: error handler taking an error message and, since version 1.28.6, an optional object containing the complete error information as delivered by the ODataService. See fnFailure parameter of sap.ui2.srvc.ODataWrapper#onError for more details. If fnError is not given, the default error handler from the factory's page building service is called.

Since:: 1.3.0

Throws:
: Error when called while #save() or a previous reset() is running.

{sap.ui2.srvc.Bag} resetProperty(sPropertyName)

Deletes the property with the given name, no matter if it is translatable or not. If no such property exists, nothing happens.

Otherwise, the property value is considered to be undefined until a #save operation has succeeded. Note how this undefined value is treated differently by #getProperty and #getText!

BEWARE: This transient undefined value can be wrong due to a number of reasons, including different layers of storage (like sap.ui2.srvc.PageBuildingService, calling them scopes) or parent bags (in case of catalog pages), which cannot be taken properly into account until the next time a #save operation succeeds!

After a successful #save operation, a deleted property may reappear from a lower layer of storage or from a parent bag. If you need to overwrite such values, use #setProperty instead!

If resetProperty() is called during a running #save, the property will not be saved immediately. It will only be saved with the next call to #save.

Parameters:
{string} sPropertyName: the property name (which has to be a string)

Since:: 1.17.1

Throws:
: Error when called while #reset is running.

Returns:: {sap.ui2.srvc.Bag} this bag

save(fnSuccess, fnError)

Saves this bag with all modified properties. This is an asynchronous operation. If all modified properties have been saved, the success handler is called. If one or more properties cannot be saved, the error handler is called. This error handler reports which properties could not be saved and the corresponding error messages. The properties remain valid and the bag tries to save them again with the next call to save().

If save() is called when there is no modified property, the function calls the success handler asynchronously without any further activity.

Parameters:
{function ()} fnSuccess: no-args success handler. Errors thrown in this function will be reported to the page building service's default error handler (not to fnError since the signature does not fit)
{function (map|map)} fnError: error handler taking two maps, each mapping individual property names to error message and complete error information respectively. Since version 1.28.6, the second parameter is always returned, but a property name in that object may map to undefined values in case an error object containing the complete error information is not available.
For more details about the structure of the error information object see sap.ui2.srvc.ODataWrapper#onError

Since:: 1.3.0

Throws:
: Error when called while #reset() or a previous save() is running.

{sap.ui2.srvc.Bag} setProperty(sPropertyName, sValue)

Sets the value for the given property name. If no such property exists yet, it will be created. If setProperty() is called during a running #save(), the property will not be saved immediately. It will only be saved with the next call to #save().

Parameters:
{string} sPropertyName: the property name (which has to be a string)
{string} sValue: the value (which has to be a string)

Since:: 1.3.0

Throws:
: Error when called while #reset() is running.
: Error when called with a property name which is not of type string or the empty string

Returns:: {sap.ui2.srvc.Bag} this bag

{sap.ui2.srvc.Bag} setText(sTextName, sText)

Sets the translatable text for the given text property name. If no such text property exists yet, it will be created as a translatable text property. Ordinary properties and translatable text properties share a common namespace! Once a property has been created, it is either translatable or not and this cannot be changed by the corresponding setters. You can only call reset() and start all over.

Note: You can create or modify translatable text properties only if the session language is the same as the page's original language (see sap.ui2.srvc.Page#getOriginalLanguage). Also note that handling of translatable texts depends on the layer used. In some layers the original language is important; in others it does not matter. In the latter case the empty string ("") is returned, which indicates that the user is allowed to edit the translatable texts in any language.

If setText() is called during a running #save(), the text property will not be saved immediately. It will only be saved with the next call to #save().

Parameters:
{string} sTextName: the text property name (must not be empty)
{string} sText: the translatable text (may be empty)

Since:: 1.17.1

Throws:
: Error when called while #reset() is running or if an ordinary (non-translatable) property with the same name already exists.

Returns:: {sap.ui2.srvc.Bag} this bag

See:: sap.ui2.srvc.Page#getOriginalLanguage; chip.bag.getOriginalLanguage

{string} toString(bVerbose)

Returns this bag's string representation.

Parameters:
{boolean} bVerbose Optional, Default: false: whether to show all properties

Since:: 1.3.0

Returns:: {string} this bag's string representation

Classes

Class sap.ui2.srvc.Bag