docs

Routing Configuration

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

Routes

A route defines a navigable path in your application. Routes are added to the router as an array. Each route entry must include a unique name, a pattern that matches the hash, and optionally one or more targets that define what to display when the route is matched.

Remember:

Routes must be defined in an array, not in an object. The order of routes in the array determines their matching priority - routes are evaluated sequentially, and the first matching route is used. If a route matches, subsequent routes are ignored, unless the greedy parameter is set to true for that route.

Tip:

Each of the following properties can also be defined in the config section of the router configuration. This allows you to set defaults that apply to all routes, reducing duplication. You can then override these defaults in individual routes as needed.

The subclass sap.f.routing.Router provides one additional property that can be used in the route configuration:

For more information, see API Reference: sap.ui.core.routing.Router, API Reference: sap.m.routing.Router, and API Reference: sap.f.routing.Router.

Tip:

For a better understanding about how patterns work and what matched parameters look like, see the following page in the Samples in the Demo Kit: sap.ui.core.sample.PatternMatching/preview.

Note:

OpenUI5 uses Crossroads.js for parsing the hash and the Hasher framework for manipulating the hash.

Targets

A target defines the view or component that is displayed when a route is matched or explicitly invoked in code. Targets allow you to decouple route configuration from view/component instantiation and placement.

Each target is responsible for loading and inserting a view or component into a specific aggregation of a container control — typically defined via controlId and controlAggregation.

The target can be:

When a target is displayed:

The targets section of the router configuration is an object in which each key defines the name of a target, and the corresponding value is a configuration object for that specific target. A target configuration object contains the following properties:

Tip:

Each of the following properties can also be defined in the config section of the router configuration. This allows you to set defaults that apply to all targets, reducing duplication. You can then override these defaults in individual targets as needed.

When a target is defined with type: "Component", the following additional properties can be used to control how the component is instantiated and embedded into the app:

The subclasses of sap/ui/core/routing/Router provide additional properties that can be used in the target configuration. sap/m/routing/Router and sap/f/routing/Router add the following properties:

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”, and the sample Targets Without a Router in the Samples in the Demo Kit.

For more information, see API Reference: sap.ui.core.routing.Targets.

Config

The config section defines global router settings and default values that apply to all routes and targets in your app. This helps reduce duplication by centralizing common configuration.

Every property that can be used in a route or a target can also be defined in the config section. These values will then act as defaults. If a route or target defines the same property explicitly in its own configuration, that local value overrides the global default from config.

In addition to the defaults for the routes and targets of your app, the config section can contain the following properties:

For more information, see API Reference: sap.m.routing.Router.

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: {
                async: true
                viewType: "XML",
                path: "view",
                controlId: "splitApp",
                clearTarget: false,
                bypassed: {
                    target: "notFound"
                },
                homeRoute: "home"
            },
            routes: [
                {
                    pattern: "",
                    name : "home",
                    target: "home"
                },
                {
                    pattern: "category/{id}",
                    name: "category",
                    target: "category"
                },
                {
                    pattern: "category/{id}/product/{productId}",
                    name: "product",
                    target: ["category", "product"]
                },
],
            targets: {
                category: {
                    type: "View",
                    name: "Category",
                    controlAggregation: "masterPages" 
                },
                product: {
                    type: "View",
                    name: "Product",
                    controlAggregation: "detailPages",
                },
                home: {
                    type: "View",
                    name: "Home",
                    controlAggregation: "masterPages"
                },
                notFound: {
                    type: "View",
                    name: "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 both of them are added to the target property of the product route.

Related Information

API Reference: sap.ui.core.routing

API Reference: sap.m.routing.Router

API Reference: sap.f.routing.Router

Sample: Targets Without a Router

Working with Multiple Targets

Tutorial: Navigation and Routing

Enabling Routing in Nested Components

This site is open source. Improve this page.