class sap.ui.core.routing.Router

Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/core/routing/Router
Application Component: CA-UI5-COR

Constructor

Instantiates a SAPUI5 Router

new sap.ui.core.routing.Router(oRoutes?, oConfig?, oOwner?, oTargetsConfig?)
Param Type Default Value Description
oRoutes? object object[]

may contain many Route configurations as sap.ui.core.routing.Route#constructor.
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' for displaying the target 'targetView' which is defined in 'oTargets'
    {
        name: "anotherRoute"
        pattern : "anotherPattern",
        target: "targetView"
    },
    //Will create a route for displaying a nested component which is defined in 'oTargets' with the prefix 'componentPrefix'
    {
        pattern: "componentPattern",
        name: "componentRoute",
        target: [
             {
                 name: "subComponent",
                 prefix: "componentPrefix"
             }
        ]
    }
]

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' for displaying the target 'targetView' which is defined in 'oTargets'
    anotherRoute : {
        pattern : "anotherPattern",
        target: "targetView"
    },
    //Will create a route for displaying a nested component which is defined in 'oTargets' with the prefix 'componentPrefix'
    componentRoute{
        pattern: "componentPattern",
        target: [
             {
                 name: "subComponent",
                 prefix: "componentPrefix"
             }
        ]
    }
}
The values that may be provided are the same as in sap.ui.core.routing.Route#constructor

oConfig? object

Default values for route configuration - also takes the same parameters as sap.ui.core.routing.Target#constructor.
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.

bypassed? object

Since 1.28. Settings which are used when no route of the router is matched after a hash change.

target? string string[]

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
         }
    });

async? boolean false

Since 1.34. Whether views are loaded asynchronously within this router instance. As of 1.90 synchronous routing is deprecated. Therefore, you should explicitly set oConfig.async to true.

oOwner? sap.ui.core.UIComponent

the Component of all the views that will be created by this Router,
will get forwarded to the sap.ui.core.routing.Views#constructor.
If you are using the componentMetadata to define your routes you should skip this parameter.

oTargetsConfig? object

Since 1.28 the target configuration, see sap.ui.core.routing.Targets#constructor 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
    {
        path: "my.application.namespace",
        viewType: "XML"
    },
    // You should only use this constructor when you are using a router without 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
             type: "View",
             name: "Welcome",
             controlId: "app",
             controlAggregation: "pages"
         }
    })


Events Overview

Event Description
beforeRouteMatched

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 the nested route.


Since: 1.46.1.

bypassed

The bypassed event is fired, when no route of the router matches the changed URL hash.

routeMatched

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.

routePatternMatched

The routePatternMatched event is fired, only when the current URL hash matches the pattern of a route in this router.

titleChanged

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 title option 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 title option
  3. When the titleTarget option on the route is configured, this specific target is then used as the "TitleTarget"

beforeRouteMatched

The beforeRouteMatched event is fired before the corresponding target is loaded and placed, when the current URL hash matches:



Since: 1.46.1.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
name string

The name of the route

arguments object

A key-value pair object which contains the arguments defined in the route resolved with the corresponding information from the current URL hash

config object

The configuration object of the route

nestedRoute sap.ui.core.routing.Route

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#constructor

bypassed

The bypassed event is fired, when no route of the router matches the changed URL hash.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
hash string

the current URL hash which did not match any route

routeMatched

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

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.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
name string

The name of the route

arguments object

A key-value pair object which contains the arguments defined in the route resolved with the corresponding information from the current URL hash

config object

The configuration object of the route

nestedRoute sap.ui.core.routing.Route

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#constructor

view sap.ui.core.mvc.View|sap.ui.core.ComponentContainer

The first View or ComponentContainer instance which is created out of the first target. If multiple targets are displayed, use oEvent.getParameters.views to get all instances

views Array<(sap.ui.core.mvc.View|sap.ui.core.ComponentContainer)>

All View or ComponentContainer instances which are created out of the targets.

targetControl sap.ui.core.Control

The container control to which the first View or ComponentContainer is added. If multiple targets are displayed, use oEvent.getParameters.targetControls to get all container controls

targetControls sap.ui.core.Control[]

The container controls to which the View or ComponentContainer instances are added.

routePatternMatched

The routePatternMatched event is fired, only when the current URL hash matches the pattern of a route in this router.

Param Type Description
oEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
name string

The name of the route

arguments object

A key-value pair object which contains the arguments defined in the route resolved with the corresponding information from the current URL hash

config object

The configuration object of the route

view sap.ui.core.mvc.View|sap.ui.core.ComponentContainer

The first View or ComponentContainer instance which is created out of the first target. If multiple targets are displayed, use oEvent.getParameters.views to get all instances

views Array<(sap.ui.core.mvc.View|sap.ui.core.ComponentContainer)>

All View or ComponentContainer instances which are created out of the targets.

targetControl sap.ui.core.Control

The container control to which the first View or ComponentContainer is added. If multiple targets are displayed, use oEvent.getParameters.targetControls to get all container controls

targetControls sap.ui.core.Control[]

The container controls to which the View or ComponentContainer instances are added.

titleChanged

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 title option 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 title option
  3. When the titleTarget option on the route is configured, this specific target is then used as the "TitleTarget"

Param Type Description
oEvent object
getSource sap.ui.base.EventProvider
getParameters object
title string

The current displayed title

history array

An array which contains the history of previous titles

title string

The title

hash string

The hash

isHome boolean

The app home indicator

nestedHistory array

An array which contains the title history information of the current router and of the router of the nested components, so the application doesn't need to merge the nestedHistory with the history parameter together. If a hierarchical control is used to show the title information (like the sap.m.Breadcrumbs control), the application can simply use the nestedHistory to build up the control and doesn't need the history anymore.

ownerComponentId string

The id of the component which is associated to the history entries

history array

An array which contains the history of previous titles of the router of the associated component

title string

The title

hash string

The hash

isHome boolean

The app home indicator

propagated boolean

Whether the titleChanged event is triggered by a nested component


Methods Overview

Method Description
sap.ui.core.routing.Router._interceptRouteMatched

Intercepts routeMatched event.

This method is meant for private usages. Apps are not supposed to used it. It is created for an experimental purpose. Implementation should be injected by outside.

addRoute

Adds a route to the router.

attachBeforeRouteMatched

Attaches event handler fnFunction to the beforeRouteMatched event of this sap.ui.core.routing.Router.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

attachBypassed

Attaches 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 router is matching.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

attachRouteMatched

Attaches event handler fnFunction to the routeMatched event of this sap.ui.core.routing.Router.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

attachRoutePatternMatched

Attaches event handler fnFunction to the routePatternMatched event of this sap.ui.core.routing.Router.

This event is similar to routeMatched. But it will only fire for the route that has a matching pattern, not for its parent routes.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

attachTitleChanged

Attaches event handler fnFunction to the titleChanged event of this sap.ui.core.routing.Router.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

attachViewCreated

Attaches event handler fnFunction to the viewCreated event of this sap.ui.core.routing.Router.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

Since 1.28 use {@link #getViews} instead.
destroy

Removes the router from the hash changer.

See sap.ui.core.routing.HashChanger.

detachBeforeRouteMatched

Detaches event handler fnFunction from the beforeRouteMatched event of this sap.ui.core.routing.Router.

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

detachBypassed

Detaches event handler fnFunction from the bypassed event of this sap.ui.core.routing.Router.

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

The event will get fired, if none of the routes of the router is matching.

detachRouteMatched

Detaches event handler fnFunction from the routeMatched event of this sap.ui.core.routing.Router.

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

detachRoutePatternMatched

Detaches event handler fnFunction from the routePatternMatched event of this sap.ui.core.routing.Router.

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

This event is similar to routeMatched. But it will only fire for the route that has a matching pattern, not for its parent routes.

detachTitleChanged

Detaches event handler fnFunction from the titleChanged event of this sap.ui.core.routing.Router.

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

detachViewCreated

Detaches event handler fnFunction from the viewCreated event of this sap.ui.core.routing.Router.

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

Since 1.28 use {@link #getViews} instead.
sap.ui.core.routing.Router.extend

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.

fireBeforeRouteMatched

Fires event beforeRouteMatched to attached listeners.

fireBypassed

Fires event bypassed to attached listeners.

The event will get fired, if none of the routes of the router is matching.

fireRouteMatched

Fires event routeMatched to attached listeners.

fireRoutePatternMatched

Fires event routePatternMatched to attached listeners.

This event is similar to routeMatched. But it will only fire for the route that has a matching pattern, not for its parent routes.

fireViewCreated

Fires event viewCreated to attached listeners.

Since 1.28 use {@link #getViews} instead.
getHashChanger

Returns the hash changer instance which is used in the router.

This hash changer behaves differently than the hash changer that is returned by sap.ui.core.routing.HashChanger.getInstance, especially when the router is created in a component which is nested within another component. When this hash changer is used, the other hash parts which belong to the parent components are kept in the browser hash, while the complete browser hash is changed when it's changed by using the sap.ui.core.routing.HashChanger.getInstance.

sap.ui.core.routing.Router.getMetadata

Returns a metadata object for class sap.ui.core.routing.Router.

getRoute

Returns the route with the given name or undefined if no route is found.

getRouteByHash

Returns the first route which matches the given hash or undefined if no matching route can be determined

getRouteInfoByHash

Returns a route info object containing the name and arguments of the route which matches the given hash or undefined.

sap.ui.core.routing.Router.getRouter

Get a registered router.

getTarget

Returns a target by its name.

If you pass myTarget: { view: "myView" }) in the config, myTarget is the name. See sap.ui.core.routing.Targets#getTarget.

getTargets

Returns the instance of sap.ui.core.routing.Targets, if you passed a targets configuration to the router.

getTitleHistory

Returns the title history.

History entry example:

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

getURL

Returns the URL for the route and replaces the placeholders with the values in oParameters.

getView

Returns a cached view for a given name or creates it if it does not exist yet.

Since 1.28.1 use {@link #getViews} instead.
getViews

Returns the sap.ui.core.routing.Views instance created by the router.

initialize

Attaches the router to the hash changer.

See sap.ui.core.routing.HashChanger.

isInitialized

Returns whether the router is initialized by calling sap.ui.core.routing.Router#initialize function.

isStopped

Returns whether the router is stopped by calling sap.ui.core.routing.Router#stop function.

match

Returns whether the given hash can be matched by any of the routes in the router.

navTo

Navigates to a specific route defining a set of parameters.

The parameters will be URI encoded - the characters ; , / ? : @ & = + $ are reserved and will not be encoded. If you want to use special characters in your oParameters, you have to encode them (encodeURIComponent).

If the given route name can't be found, an error message is logged to the console and the hash will be changed to the empty string.

This method excecutes following steps: 1. Interpolates the pattern with the given parameters 2. Sets the interpolated pattern to the browser's hash 3. Reacts to the browser's hashchange event to find out the route which matches the hash

If there are multiple routes that have the same pattern, the call of navTo with a specific route won't necessarily trigger the matching process of this route. In the end, the first route in the router configuration list that matches the browser hash will be chosen.

If the browser hash is already set with the interpolated pattern from the navTo call, nothing will happen because the browser won't fire hashchange event in this case.

parse

Will trigger routing events + place targets for routes matching the string.

register

Centrally register this router instance under a given name to be able to access it from another context, just by knowing the name.

Use Router.getRouter() to retrieve the instance.

setView

Adds or overwrites a view in the view cache of the router which will be cached under the given sViewName and the "undefined" key.

Since 1.28 use {@link #getViews} instead.
stop

Stops to listen to the hashchange of the browser.

If you want the router to start again, call #initialize again.

sap.ui.core.routing.Router._interceptRouteMatched

Intercepts routeMatched event.

This method is meant for private usages. Apps are not supposed to used it. It is created for an experimental purpose. Implementation should be injected by outside.

Param Type DefaultValue Description
sControlId string

the name of the container control (usually sap.m.App) which targets are rendered in.

oRouter sap.ui.core.routing.Router

The instance of the router

addRoute

Adds a route to the router.

Param Type DefaultValue Description
oConfig object

Configuration object for the route @see sap.ui.core.routing.Route#constructor

oParent sap.ui.core.routing.Route

The parent route - if a parent route is given, the routeMatched event of this route will also trigger the routeMatched of the parent and it will also create the view of the parent (if provided).

attachBeforeRouteMatched

Attaches event handler fnFunction to the beforeRouteMatched event of this sap.ui.core.routing.Router.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with, defaults to this sap.ui.core.routing.Router itself

attachBypassed

Attaches 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 router is matching.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with, defaults to this sap.ui.core.routing.Router itself

attachRouteMatched

Attaches event handler fnFunction to the routeMatched event of this sap.ui.core.routing.Router.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with, defaults to this sap.ui.core.routing.Router itself

attachRoutePatternMatched

Attaches event handler fnFunction to the routePatternMatched event of this sap.ui.core.routing.Router.

This event is similar to routeMatched. But it will only fire for the route that has a matching pattern, not for its parent routes.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with, defaults to this sap.ui.core.routing.Router itself

attachTitleChanged

Attaches event handler fnFunction to the titleChanged event of this sap.ui.core.routing.Router.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with, defaults to this sap.ui.core.routing.Router itself

attachViewCreated

Attaches event handler fnFunction to the viewCreated event of this sap.ui.core.routing.Router.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.core.routing.Router itself.

Since 1.28 use {@link #getViews} instead.
Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function

The function to be called when the event occurs

oListener object

Context object to call the event handler with, defaults to this sap.ui.core.routing.Router itself

destroy

Removes the router from the hash changer.

See sap.ui.core.routing.HashChanger.

detachBeforeRouteMatched

Detaches event handler fnFunction from the beforeRouteMatched event of this sap.ui.core.routing.Router.

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

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachBypassed

Detaches event handler fnFunction from the bypassed event of this sap.ui.core.routing.Router.

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

The event will get fired, if none of the routes of the router is matching.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachRouteMatched

Detaches event handler fnFunction from the routeMatched event of this sap.ui.core.routing.Router.

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

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachRoutePatternMatched

Detaches event handler fnFunction from the routePatternMatched event of this sap.ui.core.routing.Router.

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

This event is similar to routeMatched. But it will only fire for the route that has a matching pattern, not for its parent routes.

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachTitleChanged

Detaches event handler fnFunction from the titleChanged event of this sap.ui.core.routing.Router.

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

Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

detachViewCreated

Detaches event handler fnFunction from the viewCreated event of this sap.ui.core.routing.Router.

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

Since 1.28 use {@link #getViews} instead.
Param Type DefaultValue Description
fnFunction function

The function to be called when the event occurs

oListener object

Context object on which the given function had to be called

sap.ui.core.routing.Router.extend

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.

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

fireBeforeRouteMatched

Fires event beforeRouteMatched to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

fireBypassed

Fires event bypassed to attached listeners.

The event will get fired, if none of the routes of the router is matching.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

fireRouteMatched

Fires event routeMatched to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

fireRoutePatternMatched

Fires event routePatternMatched to attached listeners.

This event is similar to routeMatched. But it will only fire for the route that has a matching pattern, not for its parent routes.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

fireViewCreated

Fires event viewCreated to attached listeners.

Since 1.28 use {@link #getViews} instead.
Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

getHashChanger

Returns the hash changer instance which is used in the router.

This hash changer behaves differently than the hash changer that is returned by sap.ui.core.routing.HashChanger.getInstance, especially when the router is created in a component which is nested within another component. When this hash changer is used, the other hash parts which belong to the parent components are kept in the browser hash, while the complete browser hash is changed when it's changed by using the sap.ui.core.routing.HashChanger.getInstance.

sap.ui.core.routing.Router.getMetadata

Returns a metadata object for class sap.ui.core.routing.Router.

getRoute

Returns the route with the given name or undefined if no route is found.

Param Type DefaultValue Description
sName string

Name of the route

getRouteByHash

Returns the first route which matches the given hash or undefined if no matching route can be determined

Param Type DefaultValue Description
sHash string

The hash of the desired route

getRouteInfoByHash

Returns a route info object containing the name and arguments of the route which matches the given hash or undefined.

Param Type DefaultValue Description
sHash string

The hash to be matched

sap.ui.core.routing.Router.getRouter

Get a registered router.

Param Type DefaultValue Description
sName string

Name of the router

getTarget

Returns a target by its name.

If you pass myTarget: { view: "myView" }) in the config, myTarget is the name. See sap.ui.core.routing.Targets#getTarget.

Param Type DefaultValue Description
vName string string[]

Name of a single target or an array of names of multiple targets

getTargets

Returns the instance of sap.ui.core.routing.Targets, if you passed a targets configuration to the router.

getTitleHistory

Returns the title history.

History entry example:

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

getURL

Returns the URL for the route and replaces the placeholders with the values in oParameters.

Param Type DefaultValue Description
sName string

Name of the route

oParameters object

Parameters for the route

getView

Returns a cached view for a given name or creates it if it does not exist yet.

Since 1.28.1 use {@link #getViews} instead.
Param Type DefaultValue Description
sViewName string

Name of the view

sViewType string

Type of the view

sViewId string

Optional view id

getViews

Returns the sap.ui.core.routing.Views instance created by the router.

initialize

Attaches the router to the hash changer.

See sap.ui.core.routing.HashChanger.

Param Type DefaultValue Description
bIgnoreInitialHash boolean false

Since 1.48.0. Whether the current URL hash shouldn't be parsed after the router is initialized

isInitialized

Returns whether the router is initialized by calling sap.ui.core.routing.Router#initialize function.

isStopped

Returns whether the router is stopped by calling sap.ui.core.routing.Router#stop function.

match

Returns whether the given hash can be matched by any of the routes in the router.

Param Type DefaultValue Description
sHash string

which will be tested by the Router

navTo

Navigates to a specific route defining a set of parameters.

The parameters will be URI encoded - the characters ; , / ? : @ & = + $ are reserved and will not be encoded. If you want to use special characters in your oParameters, you have to encode them (encodeURIComponent).

If the given route name can't be found, an error message is logged to the console and the hash will be changed to the empty string.

This method excecutes following steps: 1. Interpolates the pattern with the given parameters 2. Sets the interpolated pattern to the browser's hash 3. Reacts to the browser's hashchange event to find out the route which matches the hash

If there are multiple routes that have the same pattern, the call of navTo with a specific route won't necessarily trigger the matching process of this route. In the end, the first route in the router configuration list that matches the browser hash will be chosen.

If the browser hash is already set with the interpolated pattern from the navTo call, nothing will happen because the browser won't fire hashchange event in this case.

Param Type DefaultValue Description
sName string

The name of the route

oParameters object

The parameters for the route. As of Version 1.75 the recommendation is naming the query parameter with a leading "?" character, which is identical to the definition in the route's pattern. The old syntax without a leading "?" character is deprecated. e.g. Route: {parameterName1}/:parameterName2:/{?queryParameterName} Parameter:

				{
					parameterName1: "parameterValue1",
					parameterName2: "parameterValue2",
					"?queryParameterName": {
						queryParameterName1: "queryParameterValue1"
					}
				}
				

oComponentTargetInfo object

Information for route name and parameters of the router in nested components. When any target of the route which is specified with the sName parameter loads a component and a route of this component whose pattern is different than an empty string should be matched directly with this navTo call, the route name and its parameters can be given by using this parameter. Information for deeper nested component target can be given within the componentTargetInfo property which contains the same properties as the top level.

anyName object

The name of a target which loads a component. This target is used in the Route which is specified by sName.

route string

The name of the route which should be matched after this navTo call.

parameters object

The parameters for the route. See the documentation of the oParameters.

componentTargetInfo object

The information for the targets within a nested component. This shares the same structure with the oComponentTargetInfo parameter.

bReplace boolean false

If set to true, the hash is replaced, and there will be no entry in the browser history. If set to false, the hash is set and the entry is stored in the browser history.

parse

Will trigger routing events + place targets for routes matching the string.

Param Type DefaultValue Description
sNewHash string

A new hash

register

Centrally register this router instance under a given name to be able to access it from another context, just by knowing the name.

Use Router.getRouter() to retrieve the instance.

Param Type DefaultValue Description
sName string

Name of the router instance

setView

Adds or overwrites a view in the view cache of the router which will be cached under the given sViewName and the "undefined" key.

Since 1.28 use {@link #getViews} instead.
Param Type DefaultValue Description
sViewName string

Name of the view

oView sap.ui.core.mvc.View

The view instance

stop

Stops to listen to the hashchange of the browser.

If you want the router to start again, call #initialize again.