class sap.ui.core.routing.Route

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

Constructor

Instantiates an SAPUI5 Route

new sap.ui.core.routing.Route(oRouter, oConfig, oParent?)
Param Type Default Value Description
oRouter sap.ui.core.routing.Router

Router instance to which the route will be added

oConfig object

Configuration object for the route

name string

Name of the route, it will be used to retrieve the route from the router, it needs to be unique per router instance

pattern? string

URL pattern where it needs to match again. A pattern may consist of the following:

  • hardcoded parts: "pattern" : "product/settings" - this pattern will only match if the hash of the browser is product/settings and no arguments will be passed to the events of the route.
  • mandatory parameters: "pattern" : "product/{id}" - {id} is a mandatory parameter, e. g. the following hashes would match: product/5, product/3. The pattenMatched event will get 5 or 3 passed as id in its arguments.The hash product/ will not match.
  • optional parameters: "pattern" : "product/{id}/detail/:detailId:" - :detailId: is an optional parameter, e. g. the following hashes would match: product/5/detail, product/3/detail/2
  • query parameters: "pattern" : "product{?query}" // {?query} allows you to pass queries with any parameters, e. g. the following hashes would match: product?first=firstValue, product?first=firstValue&second=secondValue
  • rest as string parameters: "pattern" : ":all*:" - this pattern will define an optional variable that will pass the whole hash as string to the routing events. It may be used to define a catchall route, e. g. the following hashes would match: foo, product/5/3, product/5/detail/3/foo. You can also combine it with the other variables but make sure a variable with a * is the last one.

greedy? boolean false

Since 1.27. By default only the first route matching the hash, will fire events. If greedy is turned on for a route, its events will be fired even if another route has already matched.

parent? string

Since 1.32. This property contains the information about the route which nests this route in the form: "[componentName:]routeName". The nesting routes pattern will be prefixed to this routes pattern and hence the nesting route also matches if this one matches.

target? string string[]

One or multiple name of targets sap.ui.core.routing.Targets. As soon as the route matches, the target(s) will be displayed. All the deprecated parameters are ignored, if a target is used.

view? string

Deprecated since 1.28, use target.viewName instead.
The name of a view that will be created, the first time this route will be matched. To place the view into a Control use the targetAggregation and targetControl. Views will only be created once per Router

viewType? string

Deprecated since 1.28, use target.viewType instead.
The type of the view that is going to be created. eg: "XML", "JS"

viewPath? string

Deprecated since 1.28, use target.viewPath instead.
A prefix that will be prepended in front of the view eg: view is set to "myView" and viewPath is set to "myApp" - the created view will be "myApp.myView"

targetParent? string

Deprecated since 1.28, use config.rootView (only available in the router config) instead.
The id of the parent of the targetControl - This should be the id view your targetControl is located in. By default, this will be the view created by a component, or if the Route is a subroute the view of the parent route is taken. You only need to specify this, if you are not using a router created by a component on your top level routes

targetControl? string

Deprecated since 1.28, use target.controlId instead.
Views will be put into a container Control, this might be a sap.ui.ux3.Shell control or a sap.m.NavContainer if working with mobile, or any other container. The id of this control has to be put in here

targetAggregation? string

Deprecated since 1.28, use target.controlAggregation instead.
The name of an aggregation of the targetControl, that contains views. Eg: a sap.m.NavContainer has an aggregation "pages", another Example is the sap.ui.ux3.Shell it has "content".

clearTarget? boolean false

Deprecated since 1.28, use target.clearControlAggregation instead.
Defines a boolean that can be passed to specify if the aggregation should be cleared before adding the View to it. When using a sap.ui.ux3.Shell this should be true. For a sap.m.NavContainer it should be false

subroutes? object

Deprecated since 1.28, use targets.parent instead. one or multiple route configs taking all of these parameters again. If a subroute is hit, it will fire the routeMatched event for all its parents. The routePatternMatched event will only be fired for the subroute not the parents. The routing will also display all the targets of the subroutes and its parents.

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 route matched of the parent and it will also create the view of the parent(if provided).


Events Overview

Event Description
beforeMatched

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

 a. the pattern of the route.
 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.


Since: 1.46.1.

matched

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

 a. the pattern of the route.
 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 patternMatched for getting notified only when its own pattern is matched with the URL hash not its sub-routes or nested route.

patternMatched

The patternMatched event is fired, only when the current URL hash matches the pattern of the route.

switched

The switched event is only fired, when the previously matched route has been left and another route is matched.

Since: 1.62.

beforeMatched

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

 a. the pattern of the route.
 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.


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

matched

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

 a. the pattern of the route.
 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 patternMatched for getting notified only when its own pattern is matched with the URL hash not its sub-routes or 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

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.

patternMatched

The patternMatched event is fired, only when the current URL hash matches the pattern of the 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

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.

switched

The switched event is only fired, when the previously matched route has been left and another route is matched.

Since: 1.62.

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


Methods Overview

Method Description
attachBeforeMatched

Attaches event handler fnFunction to the beforeMatched event of this sap.ui.core.routing.Route.

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.Route itself.

attachMatched

Attaches event handler fnFunction to the matched event of this sap.ui.core.routing.Route.

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.Route itself.

attachPatternMatched

Attaches event handler fnFunction to the patternMatched event of this sap.ui.core.routing.Route.

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.Route itself.

destroy

Destroys a route

detachBeforeMatched

Detaches event handler fnFunction from the beforeMatched event of this sap.ui.core.routing.Route.

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

detachMatched

Detaches event handler fnFunction from the matched event of this sap.ui.core.routing.Route.

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

detachPatternMatched

Detaches event handler fnFunction from the patternMatched event of this sap.ui.core.routing.Route.

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

sap.ui.core.routing.Route.extend

Creates a new subclass of class sap.ui.core.routing.Route 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.

fireBeforeMatched

Fires event beforeMatched to attached listeners.

sap.ui.core.routing.Route.getMetadata

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

getPattern

Returns the pattern of the route. If there are multiple patterns, the first pattern is returned

getPatternArguments

Returns the arguments of the route which matches the given hash

getURL

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

match

Returns whether the given hash can be matched by the Route

attachBeforeMatched

Attaches event handler fnFunction to the beforeMatched event of this sap.ui.core.routing.Route.

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.Route 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 Route itself

attachMatched

Attaches event handler fnFunction to the matched event of this sap.ui.core.routing.Route.

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.Route 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.Route itself

attachPatternMatched

Attaches event handler fnFunction to the patternMatched event of this sap.ui.core.routing.Route.

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.Route 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 Route itself

destroy

Destroys a route

detachBeforeMatched

Detaches event handler fnFunction from the beforeMatched event of this sap.ui.core.routing.Route.

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

detachMatched

Detaches event handler fnFunction from the matched event of this sap.ui.core.routing.Route.

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

detachPatternMatched

Detaches event handler fnFunction from the patternMatched event of this sap.ui.core.routing.Route.

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

sap.ui.core.routing.Route.extend

Creates a new subclass of class sap.ui.core.routing.Route 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

fireBeforeMatched

Fires event beforeMatched to attached listeners.

Param Type DefaultValue Description
oParameters object

Parameters to pass along with the event

sap.ui.core.routing.Route.getMetadata

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

getPattern

Returns the pattern of the route. If there are multiple patterns, the first pattern is returned

getPatternArguments

Returns the arguments of the route which matches the given hash

Param Type DefaultValue Description
sHash string

The hash

getURL

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

Param Type DefaultValue Description
oParameters object

Parameters for the route

match

Returns whether the given hash can be matched by the Route

Param Type DefaultValue Description
sHash string

which will be tested by the Route