Show TOC

Routing ConfigurationLocate this document in the navigation structure

Routing configuration consists of routes, targets, config, and owner.

Routes

Each route defines a name, a pattern, and optionally one or more targets to which to navigate when the route has been matched. In the routes section, you define which patterns are available for navigation.

  • The name of the route (unique within one router instance)

  • The pattern as hash part of the URL that matches the route

  • The navigation target as defined in the targets section

    If you want to load multiple views at the same time, you can assign multiple targets (see Working with Multiple Targets).

  • The parent to specify a route reference in a parent component (see Working with Nested Components)

The sequence of the routes in the routes definition is important. As soon as a pattern is matched, the following patterns are ignored. To prevent this for a specific route, you use the greedy parameter. If set to true, the route is always taken into account.

If you define a "catchall" route, always define it as the last route.

Targets
A target defines the view that is displayed. It is associated with one or more routes or it can be displayed manually from within the app. Whenever a target is displayed, the corresponding view is loaded and added to the aggregation configured with the controlAggregation option of the control. The target definition can contain the following parameters:

  • The target key

  • The viewName

  • Additional optional parameters

    If you don't specify a parameter, the default value is taken from the config section.

    • viewType (e.g. XML)

    • viewPath where the view is located in the app

    • viewId of the view instance

    • viewLevel if you have different levels of navigation, especially for flip and slide transitions, where, for example, it is important to know whether the slide animation should go from left to right or vice versa

    • controlId of the control that is used to display the view (e.g. app)

    • targetParent where the control is located (see Working with Multiple Targets)

    • controlAggregation target aggregation to which the view is added

      The NavContainer control, for example, has an aggregation called Pages and the shell container has Content.

    • clearAggregation specifies whether the aggregation should be cleared before adding the new view instance.

    • transition defines how the transition happens; you can choose between slide (default), flip, fade, and show.

    • parent: a view is created and added before the target view is added

Note

You can also use targets without routes to call a view directly . For more information, see the tutorial Step 5: Display a Target Without Changing the Hash and Step 10: Implement "Lazy Loading".

Config
The config section contains the global router configuration and default values that apply for all routes and targets. The configsection contains the following settings.

  • routerClass defines which router is used.

    You can either use class sap.ui.core.routing.Router (default) or sap.m.routing.Router. If you use a sap.m control (such as NavContainer or SplitApp) in your app, you can benefit more from using sap.m.routing.Router because it not only loads the targets and places them in the corresponding container, but also triggers the animation for navigating to the right target.

    Note

    The possible values for routerClass are sap.ui.core.routing.Router, sap.m.routing.Router, or any other subclasses of sap.ui.core.routing.Router.

    Compared to sap.ui.core.routing.Router, the sap.m.routing.Router is optimized for mobile apps and adds the properties viewLevel, transition, and transitionParameters which can be specified for each route or target created by the sap.m.routing.Router. The transitionParameters can also be used for custom transitions. See the API Reference for more information.

  • You can define default values for all target parameters

  • async defines whether views are loaded asynchronously. Default value is false. We recommend setting this parameter to true to improve performance.

    Note

    If you use asynchronous loading, you cannot rely on the sequence of events that are fired during the load phase. If you follow our programming model with MVC, this should not be a problem.

  • Using the bypassed parameter, you specify the navigation target that is used whenever no navigation pattern is matched. If you use this setting, you also have to define a corresponding target in the targets section.

Owner

The owner parameter defines the owner of all views that are created by the router. This is typically a UIComponent. This parameter is set automatically if the router instance is instantiated by a component.

Example

{
    metadata: {
        routing: {
            config: {
                viewType: "XML",
                viewPath: "view",
                controlId: "splitApp",
                clearTarget: false,
                bypassed: {
                    target: "notFound"
                }
            },
            routes: [{
                    pattern: "category/{id}",
                    name: "category",
                    target: "category"
                },
                {
                    pattern: "category/{id}/product/{productId}",
                    name: "product",
                    target: "product"
                },
                {
                    pattern: "",
                    name : "home",
                    target: "home"
                }
            |
],
            targets: {
                category: {
                    viewName: "Category",
                    controlAggregation: "masterPages" 
                },
                product: {
                    viewName: "Product",
                    controlAggregation: "detailPages",
                    parent: "category"
                },
                home: {
                    viewName: "Home",
                    controlAggregation: "masterPages"
                },
                notFound: {
                    viewName: "NotFound",
                    controlAggregation: "detailPages",
                    parent: "home"
                }
            }
        }
    }    
}

In this example, the Home view is always shown when the hash is empty. The Category view is shown when the hash matches the pattern category/{id}. Both the Category and the Product view are shown when the hash matches the pattern category/{id}/product/{productId}, because the parent relationship between both views is established using the parent parameter for the product target.

Related Information