Class sap.ui2.srvc.ChipInstance

Defined in: chipinstance.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	sap.ui2.srvc.ChipInstance(oFactory, oAlterEgo, oChip, oPage) Constructs a new representation (wrapper) of the CHIP instance with the given CHIP instance data as loaded from the page building service.

Method Summary
Method Attributes	Method Name and Description
	attachFullscreen(fnEventHandler) Attaches the given event handler to the "fullscreen" event which is fired whenever fullscreen mode is toggled.
	attachRefresh(fnEventHandler) Attaches the given event handler to the "refresh" event which is fired whenever the user requests a refresh of this CHIP instance's content.
	attachTitleChange(fnNewTitleChange) Attaches the listener that is notified when setTitle is called.
	detachAll() Detaches all event handlers from all events.
	exit() Releases all resources associated with this CHIP instance.
	getApi() Returns this CHIP instance's specific API instance.
	getBag(sBagId) Returns the property bag with given ID attached to this CHIP instance.
	getBagIds() Returns an array of bag IDs attached to this CHIP instance.
	getChip() Returns this instance's CHIP.
	getConfigurationParameter(sKey) Retrieves a parameter value from the CHIP instance configuration, the CHIP configuration or the CHIP definition.
	getContract(sName) Returns the contract interface (to be used by a page builder) for the given contract name.
	getFullscreen() Tells whether the fullscreen mode is currently turned on.
	getId() Returns this CHIP instance's ID, as defined within the page building service.
	getImplementationAsSapui5() Returns this CHIP instance's implementation of type SAPUI5 as a control.
	getLayoutData() Returns this CHIP instance's layout data as defined by the page building service.
	getOriginalId() If this CHIP instance is a reference, this method returns the ID of the original CHIP instance.
	getOriginalPageId() If this CHIP instance is a reference, this method returns the page ID of the original CHIP instance's page.
	getPage() Returns this CHIP instance's page if it has been passed explicitly to our constructor or the corresponding factory method, or if this CHIP instance has been created by its page.
	getTitle() Returns this instance's title.
	isBrokenReference() Tells whether this CHIP instance is a broken reference, which means the original has been deleted.
	isOutdated() Tells whether this CHIP instance is marked as outdated.
	isReadOnly() Tells whether this CHIP instance is readOnly.
	isReference() Tells whether this CHIP instance is a reference, pointing to its original CHIP instance.
	isStub() Tells whether this CHIP instance is still only a stub and needs to be loaded.
	load(fnSuccess, fnFailure) Completes the construction of a CHIP instance and makes it ready for full use within a page builder: loads CHIP definition XML, creates CHIP API.
	refresh() Calls refresh handler if registered.
	remove(fnSuccess, fnFailure) Removes this CHIP instance from its page.
	setFullscreen(bOn) Turns the fullscreen mode on as indicated.
	setLayoutData(sLayoutData, fnSuccess, fnFailure) Determines this CHIP instance's layout data (encoded as a string, for example in JSON) and persists it.
	setTitle(sNewTitle, bDoPersist, fnSuccess, fnFailure) Changes this instance's title and persists it if requested.
	toString(bVerbose) Returns this CHIP instance's string representation.
	updateConfiguration(mConfigurationUpdates, fnSuccess, fnFailure) Updates the configuration.

Class Detail

sap.ui2.srvc.ChipInstance(oFactory, oAlterEgo, oChip, oPage)

Constructs a new representation (wrapper) of the CHIP instance with the given CHIP instance data as loaded from the page building service. A CHIP instance is a usage of a CHIP in a page

Initially a stub is created, which can later load its properties and related objects asynchronously.

A CHIP instance is a mutable object and (page building service related) changes can be persisted by the page building service.

Parameters:
{sap.ui2.srvc.Factory} oFactory: the factory
{object} oAlterEgo: the CHIP instance data as loaded via the page building service, including embedded CHIP instance property bags
{sap.ui2.srvc.Chip} oChip: the CHIP (which might still be a stub)
{sap.ui2.srvc.Page} oPage Optional: (since 1.9.0) the page to which this CHIP instance belongs

Since:: 1.2.0

See:: sap.ui2.srvc.PageBuildingService

Method Detail

attachFullscreen(fnEventHandler)

Attaches the given event handler to the "fullscreen" event which is fired whenever fullscreen mode is toggled. There can be multiple handlers at any time. Use Function.prototype.bind() to determine the event handler's this or some of its arguments. Note: Without such an event handler, the CHIP will simply continue to display the same content, no matter whether fullscreen mode is on or off.

Parameters:
{function} fnEventHandler: the event handler for the "fullscreen" event

Since:: 1.2.0

attachRefresh(fnEventHandler)

Attaches the given event handler to the "refresh" event which is fired whenever the user requests a refresh of this CHIP instance's content. Use Function.prototype.bind() to determine the event handler's this or some of its arguments. Note: Without such an event handler, the CHIP will be recreated to enforce a refresh!

Parameters:
{function} fnEventHandler Optional: the event handler for the "refresh" event

Since:: 1.2.0

attachTitleChange(fnNewTitleChange)

Attaches the listener that is notified when setTitle is called. The caller may be the page builder as well as the CHIP.

Parameters:
{function (sap.ui2.srvc.ChipInstance)} fnNewTitleChange: the listener function, it will be called with the instance as parameter; may be null to remove the listener

Since:: 1.2.0

detachAll()

Detaches all event handlers from all events.

Since:: 1.2.0

exit()

Releases all resources associated with this CHIP instance. Call this method just before you stop using it.

Since:: 1.2.0

{object} getApi()

Returns this CHIP instance's specific API instance.

Since:: 1.2.0

Returns:: {object} this CHIP instance's specific API instance

{sap.ui2.srvc.Bag} getBag(sBagId)

Returns the property bag with given ID attached to this CHIP instance.

If there is no bag with that ID an empty bag is returned.

Parameters:
{string} sBagId: the bag ID

Since:: 1.5.0

Returns:: {sap.ui2.srvc.Bag} the CHIP instance's bag for given ID

{string[]} getBagIds()

Returns an array of bag IDs attached to this CHIP instance.

Since:: 1.5.0

Returns:: {string[]} array of bag IDs

{sap.ui2.srvc.Chip} getChip()

Returns this instance's CHIP.

Since:: 1.2.0

Returns:: {sap.ui2.srvc.Chip} this instance's CHIP

{string} getConfigurationParameter(sKey)

Retrieves a parameter value from the CHIP instance configuration, the CHIP configuration or the CHIP definition.

Parameters:
{string} sKey: the key

Since:: 1.2.0

Returns:: {string} the configuration parameter value or undefined if unknown

{object} getContract(sName)

Returns the contract interface (to be used by a page builder) for the given contract name. Can only be called if the CHIP instance is not a stub anymore. Note that a separate contract interface is optional and need not be available for each and every contract!

Parameters:
{string} sName: the name of a contract, e.g. "url"

Since:: 1.11.0

Returns:: {object} an optional contract interface to be used by a page builder; may be undefined

See:: #isStub()

{boolean} getFullscreen()

Tells whether the fullscreen mode is currently turned on.

Since:: 1.2.0

Returns:: {boolean} whether fullscreen mode is turned on

{string} getId()

Returns this CHIP instance's ID, as defined within the page building service.

Since:: 1.2.0

Returns:: {string} this CHIP instance's ID

{sap.ui.core.Control} getImplementationAsSapui5()

Returns this CHIP instance's implementation of type SAPUI5 as a control. This control represents the root of this CHIP instance's UI from a page builder point of view. Can only be called if the CHIP instance is not a stub anymore.

Since:: 1.2.0

Returns:: {sap.ui.core.Control} this CHIP instance's SAPUI5 implementation as a control

See:: #isStub()

{string} getLayoutData()

Returns this CHIP instance's layout data as defined by the page building service.

Since:: 1.2.0

Returns:: {string} this CHIP instance's layout data

{string} getOriginalId()

If this CHIP instance is a reference, this method returns the ID of the original CHIP instance. If not undefined is returned.

Since:: 1.34.0

Returns:: {string} The original CHIP instance ID or undefined

See:: #isReference(); #getOriginalPageId()

{string} getOriginalPageId()

If this CHIP instance is a reference, this method returns the page ID of the original CHIP instance's page. If not undefined is returned.

Since:: 1.34.0

Returns:: {string} Page ID of the original CHIP instance's page or undefined

See:: #isReference(); #getOriginalId()

{sap.ui2.srvc.Page} getPage()

Returns this CHIP instance's page if it has been passed explicitly to our constructor or the corresponding factory method, or if this CHIP instance has been created by its page.

Since:: 1.9.0

Returns:: {sap.ui2.srvc.Page} this CHIP instance's page, which might be unknown (undefined)

See:: sap.ui2.srvc.ChipInstance; sap.ui2.srvc.Factory#createChipInstance; sap.ui2.srvc.Page#addChipInstance; sap.ui2.srvc.Page#load; sap.ui2.srvc.Page#removeChipInstance

{string} getTitle()

Returns this instance's title.

Since:: 1.2.0

Returns:: {string} this instance's title

{boolean} isBrokenReference()

Tells whether this CHIP instance is a broken reference, which means the original has been deleted.

Since:: 1.36.1

Returns:: {boolean} whether this CHIP instance is a broken reference

See:: #isReference()

{boolean} isOutdated()

Tells whether this CHIP instance is marked as outdated.

Since:: 1.9.1

Returns:: {boolean} whether this CHIP instance is marked as outdated

{boolean} isReadOnly()

Tells whether this CHIP instance is readOnly.

Since:: 1.32.0

Throws:
: Error if the CHIP instance is still a stub

Returns:: {boolean} whether this CHIP instance is readOnly

{boolean} isReference()

Tells whether this CHIP instance is a reference, pointing to its original CHIP instance.

Since:: 1.19.1

Returns:: {boolean} whether this CHIP instance is a reference

See:: #getOriginalId(); #getOriginalPageId(); #isBrokenReference()

{boolean} isStub()

Tells whether this CHIP instance is still only a stub and needs to be loaded.

Since:: 1.2.0

Returns:: {boolean} whether this CHIP instance is still only a stub

See:: #load()

load(fnSuccess, fnFailure)

Completes the construction of a CHIP instance and makes it ready for full use within a page builder: loads CHIP definition XML, creates CHIP API.

Parameters:
{function ()} fnSuccess: no-args success handler
{function (string|[object])} fnFailure 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. Default: see sap.ui2.srvc.ODataService#getDefaultErrorHandler

Since:: 1.2.0

{boolean} refresh()

Calls refresh handler if registered. Returns true if refresh handler has been called successfully.

Since:: 1.2.0

Returns:: {boolean} true if refresh handler has been called successfully

remove(fnSuccess, fnFailure)

Removes this CHIP instance from its page. This deletes the page CHIP instance within the page building service! Since 1.9.0 it also removes it from the page to which this CHIP instance belongs, as long as that page is known.

Note: Does not affect the page's layout.

Note (since 1.9.0): Call either sap.ui2.srvc.ChipInstance#remove or sap.ui2.srvc.Page#removeChipInstance, the result will be the same!

Parameters:
{function ()} fnSuccess Optional: no-args success handler
{function (string|[object])} fnFailure 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 not given sap.ui2.srvc.ODataService#getDefaultErrorHandler is used

Since:: 1.2.0

See:: #getPage; sap.ui2.srvc.Page#removeChipInstance

setFullscreen(bOn)

Turns the fullscreen mode on as indicated. Calls the attached listener in case the mode has changed.

Parameters:
{boolean} bOn: whether fullscreen mode is turned on

Since:: 1.2.0

setLayoutData(sLayoutData, fnSuccess, fnFailure)

Determines this CHIP instance's layout data (encoded as a string, for example in JSON) and persists it.

Parameters:
{string} sLayoutData: the new layout data
{function ()} fnSuccess Optional: no-args success handler
{function (string|[object])} fnFailure 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. Default: see sap.ui2.srvc.ODataService#getDefaultErrorHandler

Since:: 1.2.0

setTitle(sNewTitle, bDoPersist, fnSuccess, fnFailure)

Changes this instance's title and persists it if requested. The title change listener (see #attachTitleChange) is called. This method is not reentrant.

Parameters:
{string} sNewTitle: the new title
{boolean} bDoPersist Optional, Default: false: whether the change shall be persisted
{function ()} fnSuccess Optional: no-args success handler
{function (string|[object])} fnFailure 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. Default: see sap.ui2.srvc.ODataService#getDefaultErrorHandler

Since:: 1.2.0

See:: #getPage(); sap.ui2.srvc.Page#getOriginalLanguage()

{string} toString(bVerbose)

Returns this CHIP instance's string representation.

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

Since:: 1.2.0

Returns:: {string} this CHIP instance's string representation

updateConfiguration(mConfigurationUpdates, fnSuccess, fnFailure)

Updates the configuration. All parameters that actually were defined in the CHIP definition XML are accepted. All others will raise a warning to the log.

The configuration is maintained as JSON string in a single property. This has the following consequences regarding the scopes:

If the CHIP instance has never been persisted in the current scope, the configuration is inherited from lower scopes. If there are no changes either, the properties have their default values from the CHIP definition.
When persisting the CHIP instance in a given scope for the first time (may it be due to configuration changes or title changes...), the configuration changes are merged with inherited changes from lower scopes and persisted in the current scope. Subsequent changes in lower scopes will then remain invisible.
A property for which never an update was supplied has the default value from the CHIP definition. This also applies if you delete the update again by setting it to undefined.

Example:
The CHIP has two properties: a with default value "foo" and b with default value "bar". The administrator changes a to "baz" in scope CUST. Later a user changes b in PERS. Then the administrator decides to change a back to "foo", but our user will never see this again, because the system persisted both a and b in PERS.

Parameters:
{map} mConfigurationUpdates: The configuration updates. The values must be strings. You can however set a value to undefined. This removes it from the list of updated property and effectively resets it to the default value.
{function ()} fnSuccess Optional: no-args success handler
{function (string|[object])} fnFailure 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. Default: see sap.ui2.srvc.ODataService#getDefaultErrorHandler

Since:: 1.7.0

Classes

Class sap.ui2.srvc.ChipInstance