tutorials

Step 2: Enable Routing

In this step we will modify the app and introduce routing. Instead of having the home page of the app hard coded we will configure a router to wire multiple views together when our app is called. The routing configuration controls the application flow when the user triggers a navigation action or opens a link to the application directly.

Preview

Views are wired together using the router

Views are wired together using the router

Coding

You can view this step live: 🔗 Live Preview of Step 2.

Folder structure for this step

webapp/
├── controller/
│   ├── App.controller.?s
│   └── Home.controller.?s
├── i18n/
│   └── i18n.properties
├── localService/
│   ├── mockdata/
│   │   ├── Employees.json
│   │   └── Resumes.json
│   ├── metadata.xml
│   └── mockserver.?s
├── view/
│   ├── App.view.xml
│   └── Home.view.xml
├── Component.?s
├── index.html
├── initMockServer.?s
└── manifest.json

webapp/manifest.json

{
  "_version": "2.8.0",
  "sap.app": {
    ...
  },
  "sap.ui": {
    ...
  },
  "sap.ui5": {

    "rootView": {
      "viewName": "ui5.tutorial.navigation.view.App",
      "type": "XML",
      "id": "app"
    },
    "dependencies": {
      ...
    },
    "models": {
      ...
    },
    "routing": {
      "config": {
        "routerClass": "sap.m.routing.Router",
        "type": "View",
        "viewType": "XML",
        "path": "ui5.tutorial.navigation.view",
        "controlId": "app",
        "controlAggregation": "pages",
        "transition": "slide"
      },
      "routes": [{
        "pattern": "",
        "name": "appHome",
        "target": "home"
      }],
      "targets": {
        "home": {
          "id": "home",
          "name": "Home",
          "level": 1
        }
      }
    }
  }
}

Single-page applications based on SAPUI5 can use a so-called “router” to dispatch hash-based URLs to one or more views of the app. Therefore, the router needs to know how to address and show the views. In SAPUI5, we can simply add a routing section to our existing sap.ui5 section in the descriptor file to configure the router. There are three properties that can be used to configure the routing of your application:

:note: As of SAPUI5 version 1.30, we recommend that you define the routing in the manifest.json descriptor file using routes and targets. In older versions of SAPUI5, the routing configuration had to be done directly in the metadata section of the component, and with different syntax.

webapp/Component.?s

import UIComponent from "sap/ui/core/UIComponent";

/**
 * @namespace ui5.tutorial.navigation
 */
export default class Component extends UIComponent {

	public static metadata = {
		manifest: "json"
	};

	public init(): void {
		super.init();

		// create the views based on the url/hash
		this.getRouter().initialize();
	}
}

sap.ui.define(["sap/ui/core/UIComponent"], function (UIComponent) {
	"use strict";

	const Component = UIComponent.extend("ui5.tutorial.navigation.Component", {
		metadata: {
			interfaces: ["sap.ui.core.IAsyncContentCreation"],
			manifest: "json"
		},
		init: function _init() {
			UIComponent.prototype.init.call(this);

			// create the views based on the url/hash
			this.getRouter().initialize();
		}
	});
	return Component;
});

We override the init function and call the parent’s init function first. We get a reference to the router and call initialize()on it. The router is instantiated automatically with the configuration loaded in the descriptor. The routing events and our configuration in the descriptor are now automatically enabled in the app. Running the app at this point would lead to an error, because the home view is not implemented yet.

webapp/view/App.view.xml

<mvc:View
  controllerName="ui5.tutorial.navigation.controller.App"
  xmlns="sap.m"
  xmlns:mvc="sap.ui.core.mvc"
  displayBlock="true">
  <Shell>
    <App id="app"/>
  </Shell>
</mvc:View>

In the App view, we remove the content of App control. The pages will be added dynamically the way we have configured it in the descriptor. The view configured with the property rootView is automatically instantiated when the app is called initially.

webapp/view/Home.view.xml (New)

<mvc:View
  controllerName="ui5.tutorial.navigation.controller.Home"
  xmlns="sap.m"
  xmlns:mvc="sap.ui.core.mvc">
  <Page
    title="{i18n>homePageTitle}"
    titleAlignment="Center"
    class="sapUiResponsiveContentPadding">
    <content>
      <Button text="{i18n>iWantToNavigate}" class="sapUiTinyMarginEnd"/>
    </content>
  </Page>
</mvc:View>

Create a file Home.view.xml in the webapp/view folder. The home view only contains a page control that displays a button. For illustration, we bind the title of the page to the i18n>homePageTitle, you can use data binding just the way you are used to it.

webapp/controller/Home.controller.?s (New)

import Controller from "sap/ui/core/mvc/Controller";

/**
 * @namespace ui5.tutorial.navigation.controller
 */
export default class Home extends Controller {

}

sap.ui.define(["sap/ui/core/mvc/Controller"], function (Controller) {
	"use strict";

	const Home = Controller.extend("ui5.tutorial.navigation.controller.Home", {});
	return Home;
});

Create a file Home.controller.ts in the webapp/controller folder. The controller for the home view does not contain any custom logic in this step, but we will add some features to it soon. Finally, run the app by calling the webapp/index.html file. This will be the entry point for our app in all the next steps. As you can see, the app is initially displaying the home view that we configured as the default pattern in the routing configuration. We have now successfully enabled routing in the app.

:note: We think of routing as a set of features that dispatch hash-based URLs to an app’s views and manage the views’ states.

Based on the routing configuration, you define the navigation between pages and pass parameters to the target views.

Conventions

Next: Step 3: Catch Invalid Hashes

Previous: Step 1: Set Up the Initial App

This site is open source. Improve this page.