Class sap.ui.core.routing.RouterModule: sap/ui/core/routing/Router

known direct subclasses: Router, Router

Constructor Summary
new sap.ui.core.routing.Router(oRoutes?, oConfig?, oOwner?, oTargetsConfig?)Instantiates a SAPUI5 Router
Event Summary
beforeRouteMatched(oEvent)The 'beforeRouteMatched' event is fired before the corresponding target is loaded and placed, when the current URL hash matches:
 a.
			
bypassed(oEvent) The 'bypassed' event is fired, when no route of the router matches the changed URL hash
routeMatched(oEvent) The 'routeMatched' event is fired, when the current URL hash matches:
 a.
			
routePatternMatched(oEvent) The 'routePatternMatched' event is fired, only when the current URL hash matches the pattern of a route in this router.
titleChanged(oEvent) Will be fired when the title of the "TitleTarget" in the currently matching Route has been changed.
Method Summary
sap.ui.core.routing.Router.extend(sClassName, oClassInfo?, FNMetaImpl?) Creates a new subclass of class sap.ui.core.routing.Router with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.core.routing.Router.getMetadata() Returns a metadata object for class sap.ui.core.routing.Router.
sap.ui.core.routing.Router.getRouter(sName) Get a registered router
addRoute(oConfig, oParent) Adds a route to the router
attachBeforeRouteMatched(oData?, fnFunction, oListener?) Attach event-handler fnFunction to the 'beforeRouteMatched' event of this sap.ui.core.routing.Router.
attachBypassed(oData?, fnFunction, oListener?) Attach event-handler fnFunction to the 'bypassed' event of this sap.ui.core.routing.Router.
attachRouteMatched(oData?, fnFunction, oListener?) Attach event-handler fnFunction to the 'routeMatched' event of this sap.ui.core.routing.Router.
attachRoutePatternMatched(oData?, fnFunction, oListener?) Attach event-handler fnFunction to the 'routePatternMatched' event of this sap.ui.core.routing.Router.
attachTitleChanged(oData?, fnFunction, oListener?) Attach event-handler fnFunction to the 'titleChanged' event of this sap.ui.core.routing.Router.
destroy() Removes the router from the hash changer @see sap.ui.core.routing.HashChanger
detachBeforeRouteMatched(fnFunction, oListener) Detach event-handler fnFunction from the 'beforeRouteMatched' event of this sap.ui.core.routing.Router.
detachBypassed(fnFunction, oListener) Detach event-handler fnFunction from the 'bypassed' event of this sap.ui.core.routing.Router.
detachRouteMatched(fnFunction, oListener) Detach event-handler fnFunction from the 'routeMatched' event of this sap.ui.core.routing.Router.
detachRoutePatternMatched(fnFunction, oListener) Detach event-handler fnFunction from the 'routePatternMatched' event of this sap.ui.core.routing.Router.
detachTitleChanged(fnFunction, oListener) Detach event-handler fnFunction from the 'titleChanged' event of this sap.ui.core.routing.Router.
fireBeforeRouteMatched(mArguments?) Fire event beforeRouteMatched to attached listeners.
fireBypassed(mArguments?) Fire event bypassed to attached listeners.
fireRouteMatched(mArguments?) Fire event routeMatched to attached listeners.
fireRoutePatternMatched(mArguments?) Fire event routePatternMatched to attached listeners.
getRoute(sName) Returns the Route with a name, if no route is found undefined is returned
getTargets() Returns the instance of Targets, if you pass a targets config to the router
getTitleHistory() Returns the title history.
getURL(sName, oParameters?) Returns the URL for the route and replaces the placeholders with the values in oParameters
getViews() Returns the views instance created by the router
initialize(bIgnoreInitialHash?) Attaches the router to the hash changer @see sap.ui.core.routing.HashChanger
navTo(sName, oParameters?, bReplace?) Navigates to a specific route defining a set of parameters.
parse(sNewHash) Will trigger routing events + place targets for routes matching the string
register(sName) Registers the router to access it from another context.
stop() Stops to listen to the hashChange of the browser.
attachViewCreated(oData?, fnFunction, oListener?) Attach event-handler fnFunction to the 'viewCreated' event of this sap.ui.core.routing.Router.
detachViewCreated(fnFunction, oListener) Detach event-handler fnFunction from the 'viewCreated' event of this sap.ui.core.routing.Router.
fireViewCreated(mArguments?) Fire event viewCreated to attached listeners.
getView(sViewName, sViewType, sViewId) Returns a cached view for a given name or creates it if it does not yet exists
setView(sViewName, oView) Adds or overwrites a view in the viewcache of the router, the viewname serves as a key
Methods borrowed from class sap.ui.base.Object
Constructor Detail
new sap.ui.core.routing.Router(oRoutes?, oConfig?, oOwner?, oTargetsConfig?)
Instantiates a SAPUI5 Router
Parameters:
object|object[] oRoutes?

may contain many Route configurations as sap.ui.core.routing.Route.
Each of the routes contained in the array/object will be added to the router.

One way of defining routes is an array:

[
    //Will create a route called 'firstRouter' you can later use this name in navTo to navigate to this route
    {
        name: "firstRoute"
        pattern : "usefulPattern"
    },
    //Will create a route called 'anotherRoute'
    {
        name: "anotherRoute"
        pattern : "anotherPattern"
    }
]

The alternative way of defining routes is an Object. If you choose this way, the name attribute is the name of the property.

{
    //Will create a route called 'firstRouter' you can later use this name in navTo to navigate to this route
    firstRoute : {
        pattern : "usefulPattern"
    },
    //Will create a route called 'anotherRoute'
    anotherRoute : {
        pattern : "anotherPattern"
    }
}
The values that may be provided are the same as in sap.ui.core.routing.Route

object oConfig?

Default values for route configuration - also takes the same parameters as sap.ui.core.routing.Target.
This config will be used for routes and for targets, used in the router
Eg: if the config object specifies :


{
    viewType : "XML"
}

The targets look like this:
{
    xmlTarget : {
        ...
    },
    jsTarget : {
        viewType : "JS"
        ...
    }
}
Then the effective config will look like this:
{
    xmlTarget : {
        viewType : "XML"
        ...
    },
    jsTarget : {
        viewType : "JS"
        ...
    }
}

Since the xmlTarget does not specify its viewType, XML is taken from the config object. The jsTarget is specifying it, so the viewType will be JS.

string|string[] oConfig.bypassed.target? @since 1.28. One or multiple names of targets that will be displayed, if no route of the router is matched.
A typical use case is a not found page.
The current hash will be passed to the display event of the target.
Example:

    new Router(
    // Routes
    [
        // Any route here
    ],
    {
        bypassed: {
            // you will find this name in the target config
            target: "notFound"
        }
    },
    // You should only use this constructor when you are not using a router with a component. Please use the metadata of a component to define your routes and targets. The documentation can be found here: {@link sap.ui.core.UIComponent.extend}.
    null,
    // Target config
    {
         //same name as in the config.bypassed.target
         notFound: {
             viewName: "notFound",
             ...
             // more properties to place the view in the correct container
         }
    });

boolean oConfig.async?, Default: false @since 1.34. Whether the views which are loaded within this router instance asyncly. The default value is set to false.
sap.ui.core.UIComponent oOwner? the Component of all the views that will be created by this Router,
will get forwarded to the sap.ui.core.routing.Views.
If you are using the componentMetadata to define your routes you should skip this parameter.
object oTargetsConfig? available @since 1.28 the target configuration, see sap.ui.core.routing.Targets documentation (the options object).
You should use Targets to create and display views. Since 1.28 the route should only contain routing relevant properties.
Example:

    new Router(
    // Routes
    [
        {
            // no view creation related properties are in the route
            name: "startRoute",
            //no hash
            pattern: "",
            // you can find this target in the targetConfig
            target: "welcome"
        }
    ],
    // Default values shared by routes and Targets
    {
        viewNamespace: "my.application.namespace",
        viewType: "XML"
    },
    // You should only use this constructor when you are not using a router with a component.
    // Please use the metadata of a component to define your routes and targets.
    // The documentation can be found here: {@link sap.ui.core.UIComponent.extend}.
    null,
    // Target config
    {
         //same name as in the route called 'startRoute'
         welcome: {
             // All properties for creating and placing a view go here or in the config
             viewName: "Welcome",
             controlId: "app",
             controlAggregation: "pages"
         }
    })

Event Detail
beforeRouteMatched(oEvent)
The 'beforeRouteMatched' event is fired before the corresponding target is loaded and placed, when the current URL hash matches:
 a. the pattern of a route in this router.
 b. the pattern of its sub-route.
 c. the pattern of its nested route. When this occurs, the 'nestedRoute' parameter is set with the instance of nested route.
Parameters:
sap.ui.base.Event oEvent
sap.ui.base.EventProvider oEvent.getSource
object oEvent.getParameters
string oEvent.getParameters.name The name of the route
object oEvent.getParameters.arguments A key-value pair object which contains the arguments defined in the route resolved with the corresponding information from the current URL hash
object oEvent.getParameters.config The configuration object of the route
sap.ui.core.routing.Route oEvent.getParameters.nestedRoute? The nested route instance of this route. The event is fired on this route because the pattern in the nested route is matched with the current URL hash. This parameter can be used to decide whether the current route is matched because of its nested child route. For more information about nested child route please refer to the documentation of oConfig.parent in sap.ui.core.routing.Route
Since:
1.46.1
bypassed(oEvent)
The 'bypassed' event is fired, when no route of the router matches the changed URL hash
Parameters:
sap.ui.base.Event oEvent
sap.ui.base.EventProvider oEvent.getSource
object oEvent.getParameters
string oEvent.getParameters.hash the current URL hash which did not match any route
routeMatched(oEvent)

The 'routeMatched' event is fired, when the current URL hash matches:

 a. the pattern of a route in this router.
 b. the pattern of its sub-route.
 c. the pattern of its nested route. When this occurs, the 'nestedRoute' parameter is set with the instance of nested route.

Please refer to event routePatternMatched for getting notified only when a route's own pattern is matched with the URL hash not its sub-routes.

Parameters:
sap.ui.base.Event oEvent
sap.ui.base.EventProvider oEvent.getSource
object oEvent.getParameters
string oEvent.getParameters.name The name of the route
object oEvent.getParameters.arguments A key-value pair object which contains the arguments defined in the route resolved with the corresponding information from the current URL hash
object oEvent.getParameters.config The configuration object of the route
sap.ui.core.routing.Route oEvent.getParameters.nestedRoute? The nested route instance of this route. The event is fired on this route because the pattern in the nested route is matched with the current URL hash. This parameter can be used to decide whether the current route is matched because of its nested child route. For more information about nested child route please refer to the documentation of oConfig.parent in sap.ui.core.routing.Route
routePatternMatched(oEvent)
The 'routePatternMatched' event is fired, only when the current URL hash matches the pattern of a route in this router.
Parameters:
sap.ui.base.Event oEvent
sap.ui.base.EventProvider oEvent.getSource
object oEvent.getParameters
string oEvent.getParameters.name The name of the route
object oEvent.getParameters.arguments A key-value pair object which contains the arguments defined in the route resolved with the corresponding information from the current URL hash
object oEvent.getParameters.config The configuration object of the route
titleChanged(oEvent)

Will be fired when the title of the "TitleTarget" in the currently matching Route has been changed.

A "TitleTarget" is resolved as the following:
 1. When the Route only has one target configured, the "TitleTarget" is resolved with this target when its {@link sap.ui.core.routing.Targets#constructor|title} options is set.
 2. When the Route has more than one target configured, the "TitleTarget" is resolved by default with the first target which has a {@link sap.ui.core.routing.Targets#constructor|title} option.
 3. When the {@link sap.ui.core.routing.Route#constructor|titleTarget} option on the Route is configured, this specific target is then used as the "TitleTarget".

Parameters:
object oEvent
sap.ui.base.EventProvider oEvent.getSource
object oEvent.getParameters
string oEvent.getParameters.title The current displayed title
array oEvent.getParameters.history An array which contains the history of previous titles
string oEvent.getParameters.history.title The title
string oEvent.getParameters.history.hash The hash
boolean oEvent.getParameters.history.isHome The app home indicator
Method Detail
sap.ui.core.routing.Router.extend(sClassName, oClassInfo?, FNMetaImpl?) : function

Creates a new subclass of class sap.ui.core.routing.Router 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.EventProvider.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.core.routing.Router.getMetadata() : sap.ui.base.Metadata
Returns a metadata object for class sap.ui.core.routing.Router.
Returns:
sap.ui.base.Metadata Metadata object describing this class
sap.ui.core.routing.Router.getRouter(sName) : sap.ui.core.routing.Router
Get a registered router
Parameters:
string sName Name of the router
Returns:
sap.ui.core.routing.Router The router with the specified name, else undefined
addRoute(oConfig, oParent)
Adds a route to the router
Parameters:
object oConfig configuration object for the route @see sap.ui.core.routing.Route#constructor
sap.ui.core.routing.Route oParent The parent route - if a parent route is given, the routeMatched event of this route will also trigger the route matched of the parent and it will also create the view of the parent (if provided).
attachBeforeRouteMatched(oData?, fnFunction, oListener?) : sap.ui.core.routing.Router
Attach event-handler fnFunction to the 'beforeRouteMatched' event of this sap.ui.core.routing.Router.
Parameters:
object oData? The object, that should be passed along with the event-object when firing the event.
function fnFunction The function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
object oListener? Object on which to call the given function. If empty, this router is used.
Returns:
sap.ui.core.routing.Router this to allow method chaining
attachBypassed(oData?, fnFunction, oListener?) : sap.ui.core.routing.Router
Attach event-handler fnFunction to the 'bypassed' event of this sap.ui.core.routing.Router.
The event will get fired, if none of the routes of the routes is matching.
Parameters:
object oData? The object, that should be passed along with the event-object when firing the event.
function fnFunction The function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
object oListener? Object on which to call the given function. If empty, this router is used.
Returns:
sap.ui.core.routing.Router this to allow method chaining
attachRouteMatched(oData?, fnFunction, oListener?) : sap.ui.core.routing.Router
Attach event-handler fnFunction to the 'routeMatched' event of this sap.ui.core.routing.Router.
Parameters:
object oData? The object, that should be passed along with the event-object when firing the event.
function fnFunction The function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
object oListener? Object on which to call the given function. If empty, this router is used.
Returns:
sap.ui.core.routing.Router this to allow method chaining
attachRoutePatternMatched(oData?, fnFunction, oListener?) : sap.ui.core.routing.Router
Attach event-handler fnFunction to the 'routePatternMatched' event of this sap.ui.core.routing.Router.
This event is similar to route matched. But it will only fire for the route that has a matching pattern, not for its parent Routes
Parameters:
object oData? The object, that should be passed along with the event-object when firing the event.
function fnFunction The function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
object oListener? Object on which to call the given function. If empty, this router is used.
Returns:
sap.ui.core.routing.Router this to allow method chaining
attachTitleChanged(oData?, fnFunction, oListener?) : sap.ui.core.routing.Router
Attach event-handler fnFunction to the 'titleChanged' event of this sap.ui.core.routing.Router.
Parameters:
object oData? The object, that should be passed along with the event-object when firing the event.
function fnFunction The function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
object oListener? Object on which to call the given function.
Returns:
sap.ui.core.routing.Router this to allow method chaining
Removes the router from the hash changer @see sap.ui.core.routing.HashChanger
Returns:
sap.ui.core.routing.Router this for chaining.
detachBeforeRouteMatched(fnFunction, oListener) : sap.ui.core.routing.Router

Detach event-handler fnFunction from the 'beforeRouteMatched' event of this sap.ui.core.routing.Router.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
function fnFunction The function to call, when the event occurs.
object oListener Object on which the given function had to be called.
Returns:
sap.ui.core.routing.Router this to allow method chaining
detachBypassed(fnFunction, oListener) : sap.ui.core.routing.Router

Detach event-handler fnFunction from the 'bypassed' event of this sap.ui.core.routing.Router.
The event will get fired, if none of the routes of the routes is matching.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
function fnFunction The function to call, when the event occurs.
object oListener Object on which the given function had to be called.
Returns:
sap.ui.core.routing.Router this to allow method chaining
detachRouteMatched(fnFunction, oListener) : sap.ui.core.routing.Router

Detach event-handler fnFunction from the 'routeMatched' event of this sap.ui.core.routing.Router.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
function fnFunction The function to call, when the event occurs.
object oListener Object on which the given function had to be called.
Returns:
sap.ui.core.routing.Router this to allow method chaining
detachRoutePatternMatched(fnFunction, oListener) : sap.ui.core.routing.Router

Detach event-handler fnFunction from the 'routePatternMatched' event of this sap.ui.core.routing.Router.
This event is similar to route matched. But it will only fire for the route that has a matching pattern, not for its parent Routes

The passed function and listener object must match the ones previously used for event registration.

Parameters:
function fnFunction The function to call, when the event occurs.
object oListener Object on which the given function had to be called.
Returns:
sap.ui.core.routing.Router this to allow method chaining
detachTitleChanged(fnFunction, oListener) : sap.ui.core.routing.Router

Detach event-handler fnFunction from the 'titleChanged' event of this sap.ui.core.routing.Router.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
function fnFunction The function to call, when the event occurs.
object oListener Object on which the given function had to be called.
Returns:
sap.ui.core.routing.Router this to allow method chaining
fireBeforeRouteMatched(mArguments?) : sap.ui.core.routing.Router
Fire event beforeRouteMatched to attached listeners.
Parameters:
object mArguments? the arguments to pass along with the event.
Returns:
sap.ui.core.routing.Router this to allow method chaining
fireBypassed(mArguments?) : sap.ui.core.routing.Router
Fire event bypassed to attached listeners. The event will get fired, if none of the routes of the routes is matching.
Parameters:
object mArguments? the arguments to pass along with the event.
Returns:
sap.ui.core.routing.Router this to allow method chaining
fireRouteMatched(mArguments?) : sap.ui.core.routing.Router
Fire event routeMatched to attached listeners.
Parameters:
object mArguments? the arguments to pass along with the event.
Returns:
sap.ui.core.routing.Router this to allow method chaining
fireRoutePatternMatched(mArguments?) : sap.ui.core.routing.Router
Fire event routePatternMatched to attached listeners. This event is similar to route matched. But it will only fire for the route that has a matching pattern, not for its parent Routes
Parameters:
object mArguments? the arguments to pass along with the event.
Returns:
sap.ui.core.routing.Router this to allow method chaining
getRoute(sName) : sap.ui.core.routing.Route
Returns the Route with a name, if no route is found undefined is returned
Parameters:
string sName Name of the route
Returns:
sap.ui.core.routing.Route the route with the provided name or undefined.
Since:
1.25.1
getTargets() : sap.ui.core.routing.Targets|undefined
Returns the instance of Targets, if you pass a targets config to the router
Returns:
sap.ui.core.routing.Targets|undefined The instance of targets, the router uses to place views or undefined if you did not specify the targets parameter in the router's constructor.
getTitleHistory() : array

Returns the title history.

History entry example: { title: "TITLE", // The displayed title hash: "HASH" // The url hash isHome: "true/false" // The app home indicator }

Returns:
array An array which contains the history entries.
getURL(sName, oParameters?) : string
Returns the URL for the route and replaces the placeholders with the values in oParameters
Parameters:
string sName Name of the route
object oParameters? Parameters for the route
Returns:
string the unencoded pattern with interpolated arguments
Returns the views instance created by the router
Returns:
sap.ui.core.routing.Views the Views instance
Since:
1.28
initialize(bIgnoreInitialHash?) : sap.ui.core.routing.Router
Attaches the router to the hash changer @see sap.ui.core.routing.HashChanger
Parameters:
boolean bIgnoreInitialHash?, Default: false @since 1.48.0 whether the current url hash shouldn't be parsed after the router is initialized
Returns:
sap.ui.core.routing.Router this for chaining.
parse(sNewHash)
Will trigger routing events + place targets for routes matching the string
Parameters:
string sNewHash a new hash
register(sName)
Registers the router to access it from another context. Use sap.ui.routing.Router.getRouter() to receive the instance
Parameters:
string sName Name of the router
Stops to listen to the hashChange of the browser.
If you want the router to start again, call initialize again.
Returns:
sap.ui.core.routing.Router this for chaining.
attachViewCreated(oData?, fnFunction, oListener?) : sap.ui.core.routing.Router
Attach event-handler fnFunction to the 'viewCreated' event of this sap.ui.core.routing.Router.
Parameters:
object oData? The object, that should be passed along with the event-object when firing the event.
function fnFunction The function to call, when the event occurs. This function will be called on the oListener-instance (if present) or in a 'static way'.
object oListener? Object on which to call the given function. If empty, this router is used.
Returns:
sap.ui.core.routing.Router this to allow method chaining
Deprecated API:
Since 1.28 use getViews instead.
detachViewCreated(fnFunction, oListener) : sap.ui.core.routing.Router

Detach event-handler fnFunction from the 'viewCreated' event of this sap.ui.core.routing.Router.

The passed function and listener object must match the ones previously used for event registration.

Parameters:
function fnFunction The function to call, when the event occurs.
object oListener Object on which the given function had to be called.
Returns:
sap.ui.core.routing.Router this to allow method chaining
Deprecated API:
Since 1.28 use getViews instead.
fireViewCreated(mArguments?) : sap.ui.core.routing.Router
Fire event viewCreated to attached listeners.
Parameters:
object mArguments? the arguments to pass along with the event.
Returns:
sap.ui.core.routing.Router this to allow method chaining
Deprecated API:
Since 1.28 use getViews instead.
getView(sViewName, sViewType, sViewId) : sap.ui.core.mvc.View
Returns a cached view for a given name or creates it if it does not yet exists
Parameters:
string sViewName Name of the view
string sViewType Type of the view
string sViewId Optional view id
Returns:
sap.ui.core.mvc.View the view instance
Deprecated API:
Since 1.28.1 use getViews instead.
setView(sViewName, oView) : sap.ui.core.routing.Router
Adds or overwrites a view in the viewcache of the router, the viewname serves as a key
Parameters:
string sViewName Name of the view
sap.ui.core.mvc.View oView the view instance
Returns:
sap.ui.core.routing.Router @since 1.28 the this pointer for chaining
Deprecated API:
Since 1.28 use getViews instead.
Since:
1.22