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

known direct subclasses: Router

Constructor Summary
new sap.ui.core.routing.Router(oRoutes?, oConfig?, oOwner?, oTargetsConfig?)Instantiates a SAPUI5 Router
Event Summary
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.
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
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.
destroy() Removes the router from the hash changer @see sap.ui.core.routing.HashChanger
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.
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
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() 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: 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? @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#contructor.
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.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: 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
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 sap.ui.core.routing.Router#event:routePatternMatched|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 An 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 An 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
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).
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 Model 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 Model 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 Model is used.
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.
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
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
Since:
1.25.1
Returns:
{sap.ui.core.routing.Route} the route with the provided name or undefined.
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.
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
Since:
1.28
Returns:
{sap.ui.core.routing.Views} the Views instance
Attaches the router to the hash changer @see sap.ui.core.routing.HashChanger
Returns:
{sap.ui.core.routing.Router} this for chaining.
navTo(sName, oParameters?, bReplace?) : sap.ui.core.routing.Router
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 empty string.

Parameters:
{string} sName Name of the route
{object} oParameters? Parameters for the route
{boolean} bReplace? Defines if the hash should be replaced (no browser history entry) or set (browser history entry)
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 Model is used.
Deprecated:
Since 1.28 use getViews instead.
Returns:
{sap.ui.core.routing.Router} this to allow method chaining
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.
Deprecated:
Since 1.28 use getViews instead.
Returns:
{sap.ui.core.routing.Router} this to allow method chaining
fireViewCreated(mArguments?) : sap.ui.core.routing.Router
Fire event viewCreated to attached listeners.
Parameters:
{object} mArguments? the arguments to pass along with the event.
Deprecated:
Since 1.28 use getViews instead.
Returns:
{sap.ui.core.routing.Router} this to allow method chaining
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
Deprecated:
Since 1.28.1 use getViews instead.
Returns:
{sap.ui.core.mvc.View} the view instance
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
Deprecated:
Since 1.28 use getViews instead.
Since:
1.22
Returns:
{sap.ui.core.routing.Router} @since 1.28 the this pointer for chaining