class sap.ui.generic.app.navigation.service.NavigationHandler

UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/generic/app/navigation/service/NavigationHandler
Application Component: CA-UI5-FE-NAV

Creates a new NavigationHandler class by providing the required environment.
The NavigationHandler supports the verification of sensitive information. All properties that are part of selectionVariant and valueTexts will be verified if they are annotated as com.sap.vocabularies.PersonalData.v1.IsPotentiallySensitive or com.sap.vocabularies.UI.v1.ExcludeFromNavigationContext and will be removed before the data is persisted as the app state.
Also, all properties annotated as com.sap.vocabularies.Analytics.v1.Measure will be removed from the data stored as the xapp state.
To verify the information to be removed, the NavigationHandler requires an unnamed model of type sap.ui.model.odata.v2.ODataModel on component level. It is possible to set such a model using the setModel method.
Note: The check for excluded data requires that the OData metadata has already been loaded completely.
If the OData metadata model has not been loaded completely, all properties are removed from the application context.
Note: This class requires that the UShell sap.ushell.services.CrossApplicationNavigation is available and initialized.


Constructor

new sap.ui.generic.app.navigation.service.NavigationHandler(oController, sParamHandlingMode?)
Param Type Default Value Description
oController object

UI5 controller that contains a router and a component; typically the main controller of your application, for example, a subclass of the sap.ca.scfld.md.controller.BaseFullscreenController if scaffolding is used

sParamHandlingMode? string SelVarWins

Mode to be used to handle conflicts when merging URL parameters and the SelectionVariant class, see sap.ui.generic.app.navigation.service.ParamHandlingMode


Methods Overview

Method Description
sap.ui.generic.app.navigation.service.NavigationHandler.constructContextUrl

The method creates a context url based on provided data. This context url can either be used as ParameterContextUrl or FilterContextUrl

sap.ui.generic.app.navigation.service.NavigationHandler.extend

Creates a new subclass of class sap.ui.generic.app.navigation.service.NavigationHandler with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.fe.navigation.NavigationHandler.extend.

sap.ui.generic.app.navigation.service.NavigationHandler.getMetadata

Returns a metadata object for class sap.ui.generic.app.navigation.service.NavigationHandler.

sap.ui.generic.app.navigation.service.NavigationHandler.getTechnicalParameters

Gets the application specific technical parameters. Technical parameters will not be added to the selection variant passed to the application. As a default the following values are considered as technical parameters:

  • sap-system
  • sap-ushell-defaultedParameterNames
  • "hcpApplicationId"

sap.ui.generic.app.navigation.service.NavigationHandler.mixAttributesAndSelectionVariant

Combines the given parameters and selection variant into a new selection variant containing properties from both, with the parameters overriding existing properties in the selection variant. The new selection variant does not contain any parameters. All parameters are merged into select options. The output of this function, converted to a JSON string, can be used for the NavigationHandler.navigate method.

sap.ui.generic.app.navigation.service.NavigationHandler.navigate

Triggers a cross-app navigation after saving the inner and the cross-app states. Since 1.52.0 the navigation mode based on sap-ushell-next-navmode is taken into account. If set to explace the inner app state will not be changed. Note: The sNavMode argument can be used to overwrite the SAP Fiori launchpad default navigation for opening a URL in-place or ex-place.

Since 1.83.0 <br> <b>Node:</b> If the <code>oExternalAppData</code> parameter is not supplied, the external app data will be calculated based on the <code>oInnerAppData</code> data.<br> SmartFilterBar control <b>Parameters:</b> <table> <tr> <td align="center">{object}</td> <td><b>oError</b></td> <td>Error object (instance of {@link sap.ui.generic.app.navigation.service.NavError}) that describes which kind of error occurred</td> <tr> <td align="center">{string}</td> <td><b>oError.errorCode</b></td> <td>Code to identify the error</td> <tr> <td align="center">{string}</td> <td><b>oError.type</b></td> <td>Severity of the error (info/warning/error)</td> <tr> <td align="center">{array}</td> <td><b>oError.params</b></td> <td>An array of objects (typically strings) that describe additional value parameters required for generating the message</td> </table>
sap.ui.generic.app.navigation.service.NavigationHandler.parseNavigation

Parses the incoming URL and returns a Promise. If this method detects a back navigation, the inner app state is returned in the resolved Promise. Otherwise startup parameters will be merged into the app state provided by cross app navigation, and a combined app state will be returned. The conflict resolution can be influenced with sParamHandlingMode defined in the constructor.

sap.ui.generic.app.navigation.service.NavigationHandler.processBeforeSmartLinkPopoverOpens

Processes navigation-related tasks related to beforePopoverOpens event handling for the SmartLink control and returns a Promise object. In particular, the following tasks are performed before the SmartLink popover can be opened:

  • If mInnerAppData is provided, this inner app state is saved for back navigation at a later time.
  • The table event parameters (semantic attributes) and the selection variant data are combined by calling the method mixAttributesAndSelectionVariant.
  • The combined data is saved as the cross app state to be handed over to the target app, and the corresponding sap-xapp-state key is set in the URL.
  • All single selections ("including equal") of the combined selection data are passed to the SmartLink popover as semantic attributes.
  • The method oTableEventParameters.open() is called. Note that this does not really open the popover, but the SmartLink control proceeds with firing the event navigationTargetsObtained.

Since 1.83.0 <br> <b>Node:</b> If the <code>oExternalAppData</code> parameter is not supplied, the external app data will be calculated based on the <code>mInnerAppData</code> data.<br>
sap.ui.generic.app.navigation.service.NavigationHandler.replaceHash

Changes the URL according to the current sAppStateKey. As an reaction route change event will be triggered.

sap.ui.generic.app.navigation.service.NavigationHandler.setModel

Sets the model that is used for verification of sensitive information. If the model is not set, the unnamed component model is used for the verification of sensitive information.

sap.ui.generic.app.navigation.service.NavigationHandler.setTechnicalParameters

Sets the application specific technical parameters. Technical parameters will not be added to the selection variant passed to the application. As a default the following values are considered as technical parameters:

  • sap-system
  • sap-ushell-defaultedParameterNames
  • "hcpApplicationId"

sap.ui.generic.app.navigation.service.NavigationHandler.storeInnerAppState

Changes the URL according to the current app state and stores the app state for later retrieval.

sap.ui.generic.app.navigation.service.NavigationHandler.storeInnerAppStateWithImmediateReturn

Changes the URL according to the current app state and stores the app state for later retrieval.

sap.ui.generic.app.navigation.service.NavigationHandler.constructContextUrl

The method creates a context url based on provided data. This context url can either be used as ParameterContextUrl or FilterContextUrl

Param Type DefaultValue Description
sEntitySetName string

used for url determination

oModel sap.ui.model.odata.v2.ODataModel

used for url determination. If omitted, the NavigationHandler model is used.

sap.ui.generic.app.navigation.service.NavigationHandler.extend

Creates a new subclass of class sap.ui.generic.app.navigation.service.NavigationHandler with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.fe.navigation.NavigationHandler.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

sap.ui.generic.app.navigation.service.NavigationHandler.getMetadata

Returns a metadata object for class sap.ui.generic.app.navigation.service.NavigationHandler.

sap.ui.generic.app.navigation.service.NavigationHandler.getTechnicalParameters

Gets the application specific technical parameters. Technical parameters will not be added to the selection variant passed to the application. As a default the following values are considered as technical parameters:

sap.ui.generic.app.navigation.service.NavigationHandler.mixAttributesAndSelectionVariant

Combines the given parameters and selection variant into a new selection variant containing properties from both, with the parameters overriding existing properties in the selection variant. The new selection variant does not contain any parameters. All parameters are merged into select options. The output of this function, converted to a JSON string, can be used for the NavigationHandler.navigate method.

Param Type DefaultValue Description
mSemanticAttributes object

Object containing key/value pairs

sSelectionVariant string

The selection variant in string format as provided by the SmartFilterBar control

iSuppressionBehavior int sap.ui.generic.app.navigation.service.SuppressionBehavior.standard

Indicates whether semantic attributes with special values (see suppression behavior) must be suppressed before they are combined with the selection variant; several suppression behaviors can be combined with the bitwise OR operator (|)

sap.ui.generic.app.navigation.service.NavigationHandler.navigate

Triggers a cross-app navigation after saving the inner and the cross-app states. Since 1.52.0 the navigation mode based on sap-ushell-next-navmode is taken into account. If set to explace the inner app state will not be changed. Note: The sNavMode argument can be used to overwrite the SAP Fiori launchpad default navigation for opening a URL in-place or ex-place.

Since 1.83.0 <br> <b>Node:</b> If the <code>oExternalAppData</code> parameter is not supplied, the external app data will be calculated based on the <code>oInnerAppData</code> data.<br> SmartFilterBar control <b>Parameters:</b> <table> <tr> <td align="center">{object}</td> <td><b>oError</b></td> <td>Error object (instance of {@link sap.ui.generic.app.navigation.service.NavError}) that describes which kind of error occurred</td> <tr> <td align="center">{string}</td> <td><b>oError.errorCode</b></td> <td>Code to identify the error</td> <tr> <td align="center">{string}</td> <td><b>oError.type</b></td> <td>Severity of the error (info/warning/error)</td> <tr> <td align="center">{array}</td> <td><b>oError.params</b></td> <td>An array of objects (typically strings) that describe additional value parameters required for generating the message</td> </table>
Param Type DefaultValue Description
sSemanticObject string

Name of the semantic object of the target app

sActionName string

Name of the action of the target app

vNavigationParameters object string

Navigation parameters as an object with key/value pairs or as a string representation of such an object. If passed as an object, the properties are not checked against the IsPotentialSensitive or Measure type.

oInnerAppData object

Object for storing current state of the app

selectionVariant string

Stringified JSON object as returned, for example, from getDataSuiteFormat() of the SmartFilterBar control

tableVariantId string

ID of the SmartTable variant

customData object

Object that can be used to store arbitrary data

presentationVariant object

Object containing the current ui state of the app

valueTexts object

Object containing value descriptions

semanticDates object

Object containing semanticDates filter information

fnOnError function

Callback that is called if an error occurs during navigation

oExternalAppData object

Object for storing the state which will be forwarded to the target component.

presentationVariant object

Object containing the current ui state of the app which will be forwarded to the target component.

valueTexts object

Object containing value descriptions which will be forwarded to the target component.

selectionVariant object

Stringified JSON object, which will be forwarded to the target component. If not provided the selectionVariant will be constructed based on the vNavigationParameters.

sNavMode string

Argument is used to overwrite the FLP-configured target for opening a URL. If used, only the explace or inplace values are allowed. Any other value will lead to an exception NavigationHandler.INVALID_NAV_MODE.

sap.ui.generic.app.navigation.service.NavigationHandler.parseNavigation

Parses the incoming URL and returns a Promise. If this method detects a back navigation, the inner app state is returned in the resolved Promise. Otherwise startup parameters will be merged into the app state provided by cross app navigation, and a combined app state will be returned. The conflict resolution can be influenced with sParamHandlingMode defined in the constructor.

sap.ui.generic.app.navigation.service.NavigationHandler.processBeforeSmartLinkPopoverOpens

Processes navigation-related tasks related to beforePopoverOpens event handling for the SmartLink control and returns a Promise object. In particular, the following tasks are performed before the SmartLink popover can be opened:

Since 1.83.0 <br> <b>Node:</b> If the <code>oExternalAppData</code> parameter is not supplied, the external app data will be calculated based on the <code>mInnerAppData</code> data.<br>
Param Type DefaultValue Description
oTableEventParameters object

The parameters made available by the SmartTable control when the SmartLink control has been clicked, an instance of a PopOver object

sSelectionVariant string

Stringified JSON object as returned, for example, from getDataSuiteFormat() of the SmartFilterBar control

mInnerAppData object

Object containing the current state of the app. If provided, opening the Popover is deferred until the inner app data is saved in a consistent way.

selectionVariant string

Stringified JSON object as returned, for example, from getDataSuiteFormat() of the the SmartFilterBar control; if provided, the selection is merged into the semantic attributes

tableVariantId string

ID of the SmartTable variant

customData object

Object that can be used to store additional app-specific data

presentationVariant object

Object containing the current ui presentationVariantof the app

valueTexts object

Object containing value descriptions

semanticDates object

Object containing semanticDates filter information

oExternalAppData object

Object containing the state which will be passed to the target screen.

selectionVariant object

Object containing selectionVariant, which will be passed to the target screen. If not set the sSelectionVariant will be used.

presentationVariant object

Object containing the current ui presentationVariant of the app, which will be passed to the target screen

valueTexts object

Object containing value descriptions, which will be passed to the target screen

sap.ui.generic.app.navigation.service.NavigationHandler.replaceHash

Changes the URL according to the current sAppStateKey. As an reaction route change event will be triggered.

Param Type DefaultValue Description
sAppStateKey string

the new app state key.

sap.ui.generic.app.navigation.service.NavigationHandler.setModel

Sets the model that is used for verification of sensitive information. If the model is not set, the unnamed component model is used for the verification of sensitive information.

Param Type DefaultValue Description
oModel sap.ui.model.odata.v2.ODataModel

for checking sensitive information

sap.ui.generic.app.navigation.service.NavigationHandler.setTechnicalParameters

Sets the application specific technical parameters. Technical parameters will not be added to the selection variant passed to the application. As a default the following values are considered as technical parameters:

Param Type DefaultValue Description
aTechnicalParameters array

list of parameter names to be considered as technical parameters. null or undefined may be used to reset the complete list.

sap.ui.generic.app.navigation.service.NavigationHandler.storeInnerAppState

Changes the URL according to the current app state and stores the app state for later retrieval.

Param Type DefaultValue Description
mInnerAppData object

Object containing the current state of the app

selectionVariant string

Stringified JSON object as returned, for example, from getDataSuiteFormat() of the SmartFilterBar control

tableVariantId string

ID of the SmartTable variant

customData object

Object that can be used to store additional app-specific data

presentationVariant object

Object containing the current ui state of the app

valueTexts object

Object containing value descriptions

semanticDates object

Object containing semanticDates filter information

bImmediateHashReplace boolean true

If set to false, the inner app hash will not be replaced until storing is successful; do not set to false if you cannot react to the resolution of the Promise, for example, when calling the beforeLinkPressed event

sap.ui.generic.app.navigation.service.NavigationHandler.storeInnerAppStateWithImmediateReturn

Changes the URL according to the current app state and stores the app state for later retrieval.

Param Type DefaultValue Description
mInnerAppData object

Object containing the current state of the app

selectionVariant string

Stringified JSON object as returned, for example, from getDataSuiteFormat() of the SmartFilterBar control

tableVariantId string

ID of the SmartTable variant

customData object

Object that can be used to store additional app-specific data

presentationVariant object

Object containing the current ui state of the app

valueTexts object

Object containing value descriptions

semanticDates object

Object containing semanticDates filter information

bImmediateHashReplace boolean false

If set to false, the inner app hash will not be replaced until storing is successful; do not set to false if you cannot react to the resolution of the Promise, for example, when calling the beforeLinkPressed event. Note:If not provided it will be treated as set to false. Note:If set to true, the calling instance has to ensure that a follow-on call to replaceHash will take place!