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. 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. { //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. { 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. 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 |
oOwner? | sap.ui.core.UIComponent | the Component of all the views that will be created by this Router, |
|
oTargetsConfig? | object | Since 1.28 the target configuration, see sap.ui.core.routing.Targets#constructor documentation (the options object). 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" } }) |
Event | Description |
---|---|
beforeRouteMatched |
The
Since: 1.46.1. |
bypassed |
The |
routeMatched |
The
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 |
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:
|
The beforeRouteMatched
event is fired before the corresponding target is loaded and placed, when the current URL hash matches:
nestedRoute
parameter is set with the instance of the nested route. 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 |
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 |
The routeMatched
event is fired, when the current URL hash matches:
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.
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. |
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. |
Will be fired when the title of the "TitleTarget" in the currently matching route has been changed.
A "TitleTarget" is resolved as the following:
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 |
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 |
Method | Description |
---|---|
sap.ui.core.routing.Router._interceptRouteMatched |
Intercepts 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 When called, the context of the event handler (its |
attachBypassed |
Attaches event handler The event will get fired, if none of the routes of the router is matching. When called, the context of the event handler (its |
attachRouteMatched |
Attaches event handler When called, the context of the event handler (its |
attachRoutePatternMatched |
Attaches event handler This event is similar to When called, the context of the event handler (its |
attachTitleChanged |
Attaches event handler When called, the context of the event handler (its |
attachViewCreated |
Attaches event handler When called, the context of the event handler (its
Since 1.28 use {@link #getViews} instead.
|
destroy |
Removes the router from the hash changer. |
detachBeforeRouteMatched |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachBypassed |
Detaches event handler 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 The passed function and listener object must match the ones used for event registration. |
detachRoutePatternMatched |
Detaches event handler The passed function and listener object must match the ones used for event registration. This event is similar to |
detachTitleChanged |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
detachViewCreated |
Detaches event handler 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
|
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 |
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 |
getRouteByHash |
Returns the first route which matches the given hash or |
getRouteInfoByHash |
Returns a route info object containing the name and arguments of the route which matches the given hash or |
sap.ui.core.routing.Router.getRouter |
Get a registered router. |
getTarget |
Returns a target by its name. If you pass |
getTargets |
Returns the instance of |
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 |
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 |
initialize |
Attaches the router to the hash changer. |
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 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 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 |
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
Since 1.28 use {@link #getViews} instead.
|
stop |
Stops to listen to the If you want the router to start again, call #initialize again. |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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.
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 |
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 |
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 |
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 |
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 |
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 |
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.
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 |
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 |
Fires event beforeRouteMatched to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameters to pass along with the event |
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 |
Fires event routeMatched to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameters to pass along with the event |
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 |
Fires event viewCreated to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
oParameters | object |
Parameters to pass along with the event |
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.
Returns a metadata object for class sap.ui.core.routing.Router.
Returns the route with the given name or undefined
if no route is found.
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
Name of the route |
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 |
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 |
Get a registered router.
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
Name of the router |
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 |
Returns the instance of sap.ui.core.routing.Targets
, if you passed a targets
configuration to the router.
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 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 |
Returns a cached view for a given name or creates it if it does not exist yet.
Param | Type | DefaultValue | Description |
---|---|---|---|
sViewName | string |
Name of the view |
|
sViewType | string |
Type of the view |
|
sViewId | string |
Optional view id |
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 |
Returns whether the router is initialized by calling sap.ui.core.routing.Router#initialize function.
Returns whether the router is stopped by calling sap.ui.core.routing.Router#stop function.
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 |
Will trigger routing events + place targets for routes matching the string.
Param | Type | DefaultValue | Description |
---|---|---|---|
sNewHash | string |
A new hash |
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 |
Adds or overwrites a view in the view cache of the router which will be cached under the given sViewName
and the "undefined" key.
Param | Type | DefaultValue | Description |
---|---|---|---|
sViewName | string |
Name of the view |
|
oView | sap.ui.core.mvc.View |
The view instance |
Stops to listen to the hashchange
of the browser.
If you want the router to start again, call #initialize again.