Class sap.ui2.srvc.Page

Defined in: page.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	sap.ui2.srvc.Page(oFactory, vPageData) Constructs a new representation (wrapper) of the page with the given ID or the given page data to be loaded from the given factory's page building service.

Method Summary
Method Attributes	Method Name and Description
	addChipInstance(vTemplate, fnSuccess, fnFailure, bPartially) Adds a new instance for the given CHIP to this page and loads that CHIP instance completely unless requested otherwise.
	addChipInstanceReference(oOriginal, fnSuccess, fnFailure) Adds a new CHIP instance to this page which refers to the given original CHIP instance and loads the reference completely if and only if the original is not a stub anymore.
	exit() Releases all resources associated with this page.
	getAllCatalogs() Returns this page's collection of all catalogs, which might still be a stub.
	getBag(sBagId) Returns the property bag with given ID attached to this page.
	getBagIds() Returns an array of bag IDs attached to this page.
	getCatalog() Returns this page's catalog, which might still be a stub.
	getChipInstances() Returns this page's CHIP instances.
	getId() Returns this page's ID.
	getLayout() Returns the layout for this page.
	getOriginalLanguage() Returns this page's original language (in which the page has been created) as BCP-47.
	getScope() Returns this page's scope.
	getTitle() Returns this page's title.
	isCatalogPage() Tells whether this page is a catalog page (see sap.ui2.srvc.Catalog#getCatalogPage and sap.ui2.srvc.Factory#createNewPageBasedCatalog).
	isOutdated() Tells whether this page is marked as outdated.
	isPersonalizationLocked() Tells whether this page can be altered on Personalization scope or not.
	isPersonalized() Tells whether this page was originally read from 'PERSONALIZATION' scope or was modified in a way that had copied the page to that scope.
	isReadOnly() Tells whether this page is read-only.
	isStub() Tells whether this page is still only a stub and does not yet know its properties or related objects, for example layout, title, catalog, or CHIP instances.
	load(fnSuccess, fnFailure, bPartially) Loads the current page including its layout, title, (stub) catalog, and CHIP instances (see `bPartially` parameter).
	loadBag(sBagId) Asynchronously get the property bag with given ID attached to this page.
	remove(fnSuccess, fnFailure) Removes (in other words, deletes) this page from the page building service.
	removeChipInstance(oChipInstance, fnSuccess, fnFailure) Removes the given page CHIP instance from this page's collection of CHIP instances, calls the instance's `remove()` method and returns `true`.
	setLayout(sLayout, fnSuccess, fnFailure) Sets the layout (encoded as a string, for example in JSON) for this page and persists it.
	setPersonalizationLocked(bIsPersLocked, fnSuccess, fnFailure) Determines and persists the locking status of a page which determines if a page can be altered on Personalization scope or not.
	setTitle(sTitle, fnSuccess, fnFailure) Sets the title for this page and persists it.
	toString(bVerbose) Returns this page's string representation.

Class Detail

sap.ui2.srvc.Page(oFactory, vPageData)

Constructs a new representation (wrapper) of the page with the given ID or the given page data to be loaded from the given factory's page building service. Associated CHIP instances (see sap.ui2.srvc.ChipInstance), catalogs (see sap.ui2.srvc.Catalog and sap.ui2.srvc.AllCatalogs), and bags (see sap.ui2.srvc.Bag) are also constructed.

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

A page is a mutable object and changes can be persisted by the page building service.

Parameters:
{sap.ui2.srvc.Factory} oFactory: the factory
{string|object} vPageData: the page's ID or its page data as loaded via page building service

Since:: 1.2.0

See:: sap.ui2.srvc.PageBuildingService

Method Detail

addChipInstance(vTemplate, fnSuccess, fnFailure, bPartially)

Adds a new instance for the given CHIP to this page and loads that CHIP instance completely unless requested otherwise. Can only be called if the page is not a stub anymore.

Note: Does not affect this page's layout.

Parameters:
{sap.ui2.srvc.Chip|sap.ui2.srvc.ChipInstance} vTemplate: the CHIP (or stub) which is to be used; (since 1.11.0) alternatively a CHIP instance, in this case a new CHIP instance is created referring to the same CHIP and having the same title and configuration. The layout data will not be copied. It is up to the caller to update that value. No bags will be copied!
{function (sap.ui2.srvc.ChipInstance)} fnSuccess: success handler, taking the newly created CHIP instance which knows its page
{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
{boolean} bPartially Optional, Default: false: whether to create the new CHIP instance as a stub only

Since:: 1.2.0

Throws:
: Error if the page is still a stub

See:: #isStub(); sap.ui2.srvc.ChipInstance#getPage

addChipInstanceReference(oOriginal, fnSuccess, fnFailure)

Adds a new CHIP instance to this page which refers to the given original CHIP instance and loads the reference completely if and only if the original is not a stub anymore. Can only be called if this page is not a stub anymore.

Note: Does not affect this page's layout.

Parameters:
{sap.ui2.srvc.ChipInstance} oOriginal: the CHIP instance (or stub) to refer to (which MUST know its page)
{function (sap.ui2.srvc.ChipInstance)} fnSuccess: success handler, taking the newly created reference which knows its page
{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.21.1

Throws:
: Error if the page is still a stub

See:: #isStub(); sap.ui2.srvc.ChipInstance#getPage

exit()

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

Since:: 1.2.0

{sap.ui2.srvc.AllCatalogs} getAllCatalogs()

Returns this page's collection of all catalogs, which might still be a stub.

Note: Returns undefined in case the JavaScript file for sap.ui2.srvc.AllCatalogs has not been included!

Since:: 1.7.0

Returns:: {sap.ui2.srvc.AllCatalogs} this page's collection of all catalogs

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

Returns the property bag with given ID attached to this page.

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

Parameters:
{string} sBagId: the bag ID

Since:: 1.3.0

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

{string[]} getBagIds()

Returns an array of bag IDs attached to this page.

Since:: 1.3.0

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

{sap.ui2.srvc.Catalog} getCatalog()

Returns this page's catalog, which might still be a stub. Can only be called if the page itself is not a stub anymore.

Since:: 1.2.0

Throws:
: Error if the page is still a stub

Returns:: {sap.ui2.srvc.Catalog} this page's catalog or undefined if the page has no catalog

See:: #isStub()

{sap.ui2.srvc.ChipInstance[]} getChipInstances()

Returns this page's CHIP instances. Can only be called if the page is not a stub anymore.

Since:: 1.2.0

Throws:
: Error if the page is still a stub

Returns:: {sap.ui2.srvc.ChipInstance[]} this page's CHIP instances

See:: #isStub()

{string} getId()

Returns this page's ID.

Since:: 1.2.0

Returns:: {string} this page's ID

{string} getLayout()

Returns the layout for this page. Can only be called if the page is not a stub anymore.

Since:: 1.2.0

Throws:
: Error if the page is still a stub

Returns:: {string} the layout for this page

See:: #isStub()

{string} getOriginalLanguage()

Returns this page's original language (in which the page has been created) as BCP-47. If you are logged on in the same language or if the original language is empty, translatable texts can be created and modified on this page and its bags. The same is valid for the page's CHIP instances and their bags. See sap.ui2.srvc.Bag#setText.

Note: 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.

The following code is a flexible way of checking the current situation without knowing the current language or layer:

 if (oPage.getOriginalLanguage() === "" ||
     oPage.getOriginalLanguage() === sap.ui.getCore().getConfiguration().getLanguage()) {
   // create and modify the page's texts
 }

This method is intended to be only called in a design time use case. Can only be called if the page is not a stub anymore.

Since:: 1.17.1

Throws:
: Error if the page is still a stub

Returns:: {string} this page's original language (BCP-47) or ""

See:: #isStub()

{string} getScope()

Returns this page's scope. This method is intended to be only called on catalog pages (see sap.ui2.srvc.Catalog#getCatalogPage), so only in a design time use case. If you want to check if the page has been personalized (so in a runtime use case) you should rather use #isPersonalized. Can only be called if the page is not a stub anymore.

Since:: 1.34.0

Throws:
: Error if the page is still a stub

Returns:: {string} returns "PERSONALIZATION", "CUSTOMIZATION" or "CONFIGURATION".

See:: #isStub(); #isPersonalized()

{string} getTitle()

Returns this page's title. Can only be called if the page is not a stub anymore.

Since:: 1.2.0

Throws:
: Error if the page is still a stub

Returns:: {string} this page's title

See:: #isStub()

{boolean} isCatalogPage()

Tells whether this page is a catalog page (see sap.ui2.srvc.Catalog#getCatalogPage and sap.ui2.srvc.Factory#createNewPageBasedCatalog). This method is intended to be only called in a design time use case. Can only be called if the page is not a stub anymore (see #isStub).

Since:: 1.19.1

Throws:
: Error if the page is still a stub

Returns:: {boolean} whether this page is a catalog page

See:: #isStub()

{boolean} isOutdated()

Tells whether this page is marked as outdated. This method is intended to be only called in a design time use case. Can only be called if the page is not a stub anymore.

Since:: 1.7.0

Throws:
: Error if the page is still a stub

Returns:: {boolean} whether this page is marked as outdated

See:: #isStub()

{boolean} isPersonalizationLocked()

Tells whether this page can be altered on Personalization scope or not. Can only be called if the page is not a stub anymore.

Since:: 1.25.0

Throws:
: Error if the page is still a stub

Returns:: {boolean} true if this page is locked and false if not

See:: #isStub()

{boolean} isPersonalized()

Tells whether this page was originally read from 'PERSONALIZATION' scope or was modified in a way that had copied the page to that scope. Such modifications include changes of layout data and changes to CHIP instances, but not to property bags. This method is intended to be only called in a runtime use case. Can only be called if the page is not a stub anymore.

Since:: 1.16.1

Throws:
: Error if the page is still a stub

Returns:: {boolean} whether this page is personalized

See:: #isStub(); #addChipInstance(); #removeChipInstance(); #setLayout(); #setTitle()

{boolean} isReadOnly()

Tells whether this page is read-only. Can only be called if the page is not a stub anymore.

Since:: 1.32.0

Throws:
: Error if the page is still a stub

Returns:: {boolean} true if this page is read-only

See:: #isStub()

{boolean} isStub()

Tells whether this page is still only a stub and does not yet know its properties or related objects, for example layout, title, catalog, or CHIP instances.

Since:: 1.2.0

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

See:: #load()

load(fnSuccess, fnFailure, bPartially)

Loads the current page including its layout, title, (stub) catalog, and CHIP instances (see bPartially parameter). Notifies one of the given handlers. All CHIP instances know their page, see sap.ui2.srvc.ChipInstance#getPage.

Note: Preferably, CHIP instances should be loaded individually as needed (e.g. as they become visible).

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. If not given sap.ui2.srvc.ODataService#getDefaultErrorHandler is used
{boolean} bPartially Optional, Default: false: whether to load the page only partially (instead of completely, including its CHIP instances)

Since:: 1.2.0

{object} loadBag(sBagId)

Asynchronously get the property bag with given ID attached to this page. If that bag has not yet been loaded the bag is loaded first.

The done function will be called with a sap.ui2.srvc.Bag instance. If there was no such bag an empty sap.ui2.srvc.Bag is passed.

Parameters:
{string} sBagId: the bag ID

Since:: 1.11.0

Returns:: {object} jQuery.promise object

remove(fnSuccess, fnFailure)

Removes (in other words, deletes) this page from the page building service.

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. If not given sap.ui2.srvc.ODataService#getDefaultErrorHandler is used

Since:: 1.2.0

{boolean} removeChipInstance(oChipInstance, fnSuccess, fnFailure)

Removes the given page CHIP instance from this page's collection of CHIP instances, calls the instance's remove() method and returns true. If the given page CHIP instance does not belong to this page (any more), false is returned and nothing else happens. Can only be called if the page is not a stub anymore.

Parameters:
{sap.ui2.srvc.ChipInstance} oChipInstance: the CHIP instance to remove from this page
{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.9.0

Throws:
: Error if the page is still a stub

Returns:: {boolean} true iff. the given CHIP instance's remove() method has been called

See:: #isStub(); sap.ui2.srvc.ChipInstance#getPage; sap.ui2.srvc.ChipInstance#remove

setLayout(sLayout, fnSuccess, fnFailure)

Sets the layout (encoded as a string, for example in JSON) for this page and persists it. Can only be called if the page is not a stub anymore.

Parameters:
{string} sLayout: the new layout
{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. If not given sap.ui2.srvc.ODataService#getDefaultErrorHandler is used

Since:: 1.2.0

Throws:
: Error if the page is still a stub

See:: #isStub()

setPersonalizationLocked(bIsPersLocked, fnSuccess, fnFailure)

Determines and persists the locking status of a page which determines if a page can be altered on Personalization scope or not. This method is intended to be only called in a design time use case. Can only be called if the page is not a stub anymore.

Parameters:
{boolean} bIsPersLocked: Desired locking status
{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. If not given sap.ui2.srvc.ODataService#getDefaultErrorHandler is used

Since:: 1.25.0

Throws:
: Error if the page is still a stub

See:: #isStub()

setTitle(sTitle, fnSuccess, fnFailure)

Sets the title for this page and persists it. Can only be called if the page is not a stub anymore.

Parameters:
{string} sTitle: the new title
{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. If not given sap.ui2.srvc.ODataService#getDefaultErrorHandler is used

Since:: 1.2.0

Throws:
: Error if the page is still a stub

See:: #getOriginalLanguage(); #isStub()

{string} toString(bVerbose)

Returns this page's string representation.

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

Since:: 1.2.0

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

Classes

Class sap.ui2.srvc.Page