Class sap.ui.generic.app.navigation.service.NavigationHandlerModule: sap/ui/generic/app/navigation/service/NavigationHandler

extends Object

Creates a new NavigationHandler class by providing the required environment.

Note: This class requires that the UShell Navigation Service API CrossApplicationNavigation is available and initialized.

Constructor Summary
new sap.ui.generic.app.navigation.service.NavigationHandler(oController, sParamHandlingMode?)
Method Summary
sap.ui.generic.app.navigation.service.NavigationHandler.extend(sClassName, oClassInfo?, FNMetaImpl?)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.
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.mixAttributesAndSelectionVariant(mSemanticAttributes, sSelectionVariant, iSuppressionBehavior?)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.
sap.ui.generic.app.navigation.service.NavigationHandler.navigate(sSemanticObject, sActionName, vNavigationParameters?, oInnerAppData?, fnOnError?)Triggers a cross-app navigation after saving the inner and the cross-app states.
sap.ui.generic.app.navigation.service.NavigationHandler.parseNavigation()Parses the incoming URL and returns a Promise.
sap.ui.generic.app.navigation.service.NavigationHandler.processBeforeSmartLinkPopoverOpens(oTableEventParameters, sSelectionVariant, mInnerAppData?)Processes navigation-related tasks related to beforePopoverOpens event handling for the SmartLink control and returns a Promise object.
sap.ui.generic.app.navigation.service.NavigationHandler.storeInnerAppState(mInnerAppData, bImmediateHashReplace?)Changes the URL according to the current app state and stores the app state for later retrieval.
Methods borrowed from class sap.ui.base.Object
Constructor Detail
new sap.ui.generic.app.navigation.service.NavigationHandler(oController, sParamHandlingMode?)
Parameters:
{object}oController 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
{string}sParamHandlingMode?, Default: SelVarWins Mode to be used to handle conflicts when merging URL parameters and the SelectionVariant class, see sap.ui.generic.app.navigation.service.ParamHandlingMode
Exceptions:
An instance of sap.ui.generic.app.navigation.service.NavError in case of input errors. Valid error codes are:
Error codeDescription
NavigationHandler.INVALID_INPUTIndicates that the input parameter is invalid
Method Detail
sap.ui.generic.app.navigation.service.NavigationHandler.extend(sClassName, oClassInfo?, FNMetaImpl?): function
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.ui.base.Object.extend.

Parameters:
{string}sClassName Name of the class being created
{object}oClassInfo? Object literal with information about the class
{function}FNMetaImpl? Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
{function} Created class / constructor function
sap.ui.generic.app.navigation.service.NavigationHandler.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.generic.app.navigation.service.NavigationHandler.
Returns:
{sap.ui.base.Metadata} Metadata object describing this class
sap.ui.generic.app.navigation.service.NavigationHandler.mixAttributesAndSelectionVariant(mSemanticAttributes, sSelectionVariant, iSuppressionBehavior?): object
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.
Parameters:
{object}mSemanticAttributes Object containing key/value pairs
{string}sSelectionVariant The selection variant in string format as provided by the SmartFilterBar control
{integer}iSuppressionBehavior?, Default: 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 (|)

var mSemanticAttributes = { "Customer" : "C0001" };
var sSelectionVariant = oSmartFilterBar.getDataSuiteFormat();
var oNavigationHandler = new sap.ui.generic.app.navigation.service.NavigationHandler(oController);
var sNavigationSelectionVariant = oNavigationHandler.mixAttributesAndSelectionVariant(mSemanticAttributes, sSelectionVariant).toJSONString();
// Optionally, you can specify one or several suppression behaviors. Several suppression behaviors are combined with the bitwise OR operator, e.g.
// var iSuppressionBehavior = sap.ui.generic.app.navigation.service.SuppressionBehavior.raiseErrorOnNull | sap.ui.generic.app.navigation.service.SuppressionBehavior.raiseErrorOnUndefined;
// var sNavigationSelectionVariant = oNavigationHandler.mixAttributesAndSelectionVariant(mSemanticAttributes, sSelectionVariant, iSuppressionBehavior).toJSONString();

oNavigationHandler.navigate("SalesOrder", "create", sNavigationSelectionVariant);

Returns:
{object} Instance of sap.ui.generic.app.navigation.service.SelectionVariant
sap.ui.generic.app.navigation.service.NavigationHandler.navigate(sSemanticObject, sActionName, vNavigationParameters?, oInnerAppData?, fnOnError?)
Triggers a cross-app navigation after saving the inner and the cross-app states.
Parameters:
{string}sSemanticObject Name of the semantic object of the target app
{string}sActionName Name of the action of the target app
{object|string}vNavigationParameters? Navigation parameters as an object with key/value pairs or as a stringified JSON object
{object}oInnerAppData? Object for storing current state of the app
{string}oInnerAppData.selectionVariant? Stringified JSON object as returned, for example, from getDataSuiteFormat() of the SmartFilterBar control
{string}oInnerAppData.tableVariantId? ID of the SmartTable variant
{object}oInnerAppData.customData? Object that can be used to store arbitrary data
{function}fnOnError? Callback that is called if an error occurs during navigation
Parameters:
{object}oErrorError object (instance of sap.ui.generic.app.navigation.service.NavError) that describes which kind of error occurred
{string}oError.errorCodeCode to identify the error
{string}oError.typeSeverity of the error (info/warning/error)
{array}oError.paramsAn array of objects (typically strings) that describe additional value parameters required for generating the message

var oNavigationHandler = new sap.ui.generic.app.navigation.service.NavigationHandler(oController);
var sSemanticObject = "SalesOrder";
var sActionName = "create";

//simple parameters as Object var vNavigationParameters = { CompanyCode : "0001", Customer : "C0001" };

//or as selection variant var oSelectionVariant = new sap.ui.generic.app.navigation.service.SelectionVariant(); oSelectionVariant.addSelectOption("CompanyCode", "I", "EQ", "0001"); oSelectionVariant.addSelectOption("Customer", "I", "EQ", "C0001"); vNavigationParameters = oSelectionVariant.toJSONString();

//or directly from SmartFilterBar vNavigationParameters = oSmartFilterBar.getDataSuiteFormat();

//app state for back navigation var oInnerAppData = { selectionVariant : oSmartFilterBar.getDataSuiteFormat(), tableVariantId : oSmartTable.getCurrentVariantId(), customData : oMyCustomData };

// callback function in case of errors var fnOnError = function(oError){ var oi18n = oController.getView().getModel("i18n").getResourceBundle(); oError.setUIText({oi18n : oi18n, sTextKey : "OUTBOUND_NAV_ERROR"}); oError.showMessageBox(); };

oNavigationHandler.navigate(sSemanticObject, sActionName, vNavigationParameters, oInnerAppData, fnOnError);

sap.ui.generic.app.navigation.service.NavigationHandler.parseNavigation(): object
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.

var oNavigationHandler = new sap.ui.generic.app.navigation.service.NavigationHandler(oController);
var oParseNavigationPromise = oNavigationHandler.parseNavigation();

oParseNavigationPromise.done(function(oAppData, oStartupParameters, sNavType){ oSmartFilterBar.setDataSuiteFormat(oAppData.selectionVariant); // oAppData.oSelectionVariant can be used to manipulate the selection variant // oAppData.oDefaultedSelectionVariant contains the parameters which are set by user defaults // oAppData.bNavSelVarHasDefaultsOnly indicates whether only defaulted parameters and no navigation parameters are present }); oParseNavigationPromise.fail(function(oError, oURLParameters, sNavType){ // if e.g. the xapp state could not be loaded, nevertheless there may be URL parameters available //some error handling });

Returns:
{object} A Promise object to monitor when all the actions of the function have been executed. If the execution is successful, the extracted app state, the startup parameters, and the type of navigation are returned, see also the example above. The app state is an object that contains the following information:
  • oAppData.oSelectionVariant: An instance of sap.ui.generic.app.navigation.service.SelectionVariant containing only parameters/select options that are related to navigation
  • oAppData.selectionVariant: The navigation-related selection variant as a JSON-formatted string
  • oAppData.oDefaultedSelectionVariant: An instance of sap.ui.generic.app.navigation.service.SelectionVariant containing only the parameters/select options that are set by user default data
  • oAppData.bNavSelVarHasDefaultsOnly: A Boolean flag that indicates whether only defaulted parameters and no navigation parameters are present (Note: If no navigation parameters are available, bNavSelVarHasDefaultsOnly istrue, even also no defaulted parameters may be available)
If the navigation-related selection variant is empty, it is replaced by a copy of the defaulted selection variant.
The navigation type is an enumeration type of type sap.ui.generic.app.navigation.service.NavType (possible values are initial, URLParams, xAppState, and iAppState).
Note: If the navigation type is sap.ui.generic.app.navigation.service.NavType.iAppState oAppData has two additional properties
  • oAppData.tableVariantId
  • oAppData.customData
which return the inner app data as stored in navigate or storeInnerAppState. oAppData.oDefaultedSelectionVariant is an empty selection variant and oAppData.bNavSelVarHasDefaultsOnly is false in this case.
Note: If the navigation type is sap.ui.generic.app.navigation.service.NavType.initial oAppData is an empty object!
If an error occurs, an error object of type sap.ui.generic.app.navigation.service.NavError, URL parameters (if available) and the type of navigation are returned.
sap.ui.generic.app.navigation.service.NavigationHandler.processBeforeSmartLinkPopoverOpens(oTableEventParameters, sSelectionVariant, mInnerAppData?): object
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.
Parameters:
{object}oTableEventParameters The parameters made available by the SmartTable control when the SmartLink control has been clicked, an instance of a PopOver object
{string}sSelectionVariant Stringified JSON object as returned, for example, from getDataSuiteFormat() of the SmartFilterBar control
{object}mInnerAppData? 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.
{string}mInnerAppData.selectionVariant? Stringified JSON object as returned, for example, from getDataSuiteFormat() of the the SmartFilterBar control; if provided, the selection is merged into the semantic attributes
{string}mInnerAppData.tableVariantId? ID of the SmartTable variant
{object}mInnerAppData.customData? Object that can be used to store additional app-specific data

//event handler for the smart link event "beforePopoverOpens"
	onBeforePopoverOpens: function(oEvent) {
		var oTableEventParameters = oEvent.getParameters();

var mInnerAppData = { selectionVariant : oSmartFilterBar.getDataSuiteFormat(), tableVariantId : oSmartTable.getCurrentVariantId(), customData : oMyCustomData };

var oSelectionVariant = new sap.ui.generic.app.navigation.service.SelectionVariant(); oSelectionVariant.addSelectOption("CompanyCode", "I", "EQ", "0001"); oSelectionVariant.addSelectOption("Customer", "I", "EQ", "C0001"); var sSelectionVariant= oSelectionVariant.toJSONString();

var oNavigationHandler = new sap.ui.generic.app.navigation.service.NavigationHandler(oController); var oSmartLinkPromise = oNavigationHandler.processBeforeSmartLinkPopoverOpens(oTableEventParameters, sSelectionVariant, mInnerAppData);

oSmartLinkPromise.done(function(oTableEventParameters){ // here you can add coding that should run after all app states are saved and the semantic attributes are set });

oSmartLinkPromise.fail(function(oError){ //some error handling }); };

Returns:
{object} A Promise object to monitor when all actions of the function have been executed; if the execution is successful, the modified oTableEventParameters is returned; if an error occurs, an error object of type sap.ui.generic.app.navigation.service.NavError is returned
sap.ui.generic.app.navigation.service.NavigationHandler.storeInnerAppState(mInnerAppData, bImmediateHashReplace?): object
Changes the URL according to the current app state and stores the app state for later retrieval.
Parameters:
{object}mInnerAppData Object containing the current state of the app
{string}mInnerAppData.selectionVariant Stringified JSON object as returned, for example, from getDataSuiteFormat() of the SmartFilterBar control
{string}mInnerAppData.tableVariantId? ID of the SmartTable variant
{object}mInnerAppData.customData? Object that can be used to store additional app-specific data
{boolean}bImmediateHashReplace?, Default: 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

var oNavigationHandler = new sap.ui.generic.app.navigation.service.NavigationHandler(oController);
var mInnerAppData = {
		selectionVariant : oSmartFilterBar.getDataSuiteFormat(),
		tableVariantId : oSmartTable.getCurrentVariantId(),
		customData : oMyCustomData
};

var oStoreInnerAppStatePromise = oNavigationHandler.storeInnerAppState(mInnerAppData);

oStoreInnerAppStatePromise.done(function(sAppStateKey){ //your inner app state is saved now, sAppStateKey was added to URL //perform actions that must run after save });

oStoreInnerAppStatePromise.fail(function(oError){ //some error handling });

Returns:
{object} A Promise object to monitor when all the actions of the function have been executed; if the execution is successful, the app state key is returned; if an error occurs, an object of type sap.ui.generic.app.navigation.service.NavError is returned