Skip to content

Commit d794190

Browse files
wridgeuwridgeu
committed
Adjusted readme - Added "Root-View" (App-Control) which gets replaced with 'content' by routing.
1 parent 3dff74c commit d794190

9 files changed

+124
-22
lines changed

‎readme.md

+85
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,91 @@ You basically read it like this - starting from the home page (here simply calle
1212

1313
![](readme_images/routing_overview.png)
1414

15+
# Routing Configuration in manifest.json
16+
17+
You can find more in the [UI5-Documentation](https://sapui5.hana.ondemand.com/#/topic/cf3c57c89ef0491793d1ce327ab4f9b2).
18+
19+
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:
20+
21+
__config__
22+
23+
This section contains the global router configuration and default values that apply for all routes and targets. The property routerClass is special as it determines the router implementation. The default value is `sap.ui.core.routing.Router`. Here, we set the routerClass to `sap.m.routing`.Router, because we implement an app based on `sap.m`. All other properties in config are given to the router instance. For example, we define where our views are located in the app. To load and display views automatically, we also specify the controlId of the control that is used to display the pages and the aggregation (controlAggregation) that will be filled when a new page is displayed. We will create only XMLviews in this tutorial, so we can set the viewType property to XML. All our views will be available in the view folder of the namespace "com.mrb.UI5-Navigation-and-Routing", so we can set the viewPath to `com.mrb.UI5-Navigation-and-Routing.view`. The transition allows us to set a default value for how the transition should happen; you can choose between slide (default), flip, fade, and show. All parameters of the config section can be overruled in the individual route and target definitions if needed.
24+
* __Note:__
25+
26+
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. Please check the [API Reference](https://sapui5.hana.ondemand.com/#/api/sap.m.routing.Router%23overview) for more information.
27+
28+
__routes__
29+
30+
Each route defines a name, a pattern, and one or more targets to navigate to when the route has been hit. The pattern is basically the hash part of the URL that matches the route. The sequence of the routes is important because only the first matched route is used by the router. In our case, we have an empty pattern to match the empty hash. The name property allows you to choose a unique route name that helps you to navigate a specific route or to determine the matched route in one of the matched handlers (we'll explain that in a later step). The target property references one or more targets from the section below that will be displayed when the route has been matched.
31+
32+
__targets__
33+
34+
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. This option is configured using _controlId_. Each target has a unique key (home). The viewName defines which view shall be loaded. In our little example, the absolute view path to be loaded for our home target is determined by the default "viewPath": "com.mrb.UI5-Navigation-and-Routing.view" and "viewName": "Home". This leads to "com.mrb.UI5-Navigation-and-Routing.view.Home". The viewLevel is especially relevant for flip and slide transitions. It helps the router to determine the direction of the transition from one page to another. (This will also be explained later.) A target can be assigned to a route, but it's not necessary. Targets can be displayed directly in the app without hitting a route.
35+
36+
## Example manifest.json configuration
37+
38+
```javascript
39+
"sap.ui5": {
40+
"rootView": {
41+
"viewName": "com.mrb.UI5-Navigation-and-Routing.view.App",
42+
"type": "XML",
43+
"async": true,
44+
"id": "app"
45+
},
46+
"routing": {
47+
"config": {
48+
"routerClass": "sap.m.routing.Router",
49+
"viewType": "XML",
50+
"viewPath": "com.mrb.UI5-Navigation-and-Routing.view",
51+
"controlId": "app",
52+
"controlAggregation": "pages",
53+
"transition": "slide",
54+
"async": true
55+
},
56+
"routes": [{
57+
"name": "appHome",
58+
"pattern": "",
59+
"target": ["home"]
60+
}],
61+
"targets": {
62+
"home": {
63+
"viewType": "XML",
64+
"viewId": "home",
65+
"viewLevel": 1,
66+
"viewName": "Home"
67+
}
68+
}
69+
}
70+
}
71+
```
72+
73+
## Example App Structure for the above shown configuration
74+
75+
```text
76+
.
77+
├── ProjectFolder
78+
│ └── webapp
79+
│ ├── controller
80+
│ │ └── App.controller.js
81+
| | └── Home.controller.js
82+
│ ├── css
83+
│ ├── i18n
84+
│ ├── view
85+
│ │ └── App.view.xml
86+
| | └── Home.view.xml
87+
│ ├── Component.js
88+
│ ├── index.html
89+
│ └── manifest.json
90+
├── package.json
91+
├── readme.md
92+
└── ui5.yaml
93+
```
94+
95+
## Routing Conventions
96+
97+
* Configure the router in the manifest.json descriptor file
98+
* Initialize the router exactly once
99+
* Initialize the router in the component
15100

16101
## Credits
17102
This project has been generated with 💙 and [easy-ui5](https://github.com/SAP)

‎webapp/controller/MainView.controller.js ‎webapp/controller/App.controller.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@ sap.ui.define([
33
], function(Controller) {
44
"use strict";
55

6-
return Controller.extend("com.mrb.UI5-Navigation-and-Routing.controller.MainView", {});
6+
return Controller.extend("com.mrb.UI5-Navigation-and-Routing.controller.App", {});
77
});

‎webapp/controller/Home.controller.js

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
sap.ui.define([
2+
"sap/ui/core/mvc/Controller"
3+
], function(Controller) {
4+
"use strict";
5+
6+
return Controller.extend("com.mrb.UI5-Navigation-and-Routing.controller.Home", {});
7+
});
8+

‎webapp/i18n/i18n_en.properties

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
title=UI5-Navigation-and-Routing
22
appTitle=UI5-Navigation-and-Routing
33
appDescription=App Description
4+
iWantToNavigate=I want to navigate
5+
homePageTitle=Home

‎webapp/index.html

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
<script id="sap-ui-bootstrap"
1212
src="https://openui5.hana.ondemand.com/resources/sap-ui-core.js"
13-
data-sap-ui-theme="sap_belize"
13+
data-sap-ui-theme="sap_fiori_3"
1414
data-sap-ui-resourceroots='{
1515
"com.mrb.UI5-Navigation-and-Routing": "./"
1616
}'

‎webapp/manifest.json

+8-6
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040

4141
"sap.ui5": {
4242
"rootView": {
43-
"viewName": "com.mrb.UI5-Navigation-and-Routing.view.MainView",
43+
"viewName": "com.mrb.UI5-Navigation-and-Routing.view.App",
4444
"type": "XML",
4545
"async": true,
4646
"id": "app"
@@ -80,18 +80,20 @@
8080
"viewPath": "com.mrb.UI5-Navigation-and-Routing.view",
8181
"controlId": "app",
8282
"controlAggregation": "pages",
83+
"transition": "slide",
8384
"async": true
8485
},
8586
"routes": [{
86-
"name": "RouteMainView",
87-
"pattern": "RouteMainView",
88-
"target": ["TargetMainView"]
87+
"name": "appHome",
88+
"pattern": "",
89+
"target": ["home"]
8990
}],
9091
"targets": {
91-
"TargetMainView": {
92+
"home": {
9293
"viewType": "XML",
94+
"viewId": "home",
9395
"viewLevel": 1,
94-
"viewName": "MainView"
96+
"viewName": "Home"
9597
}
9698
}
9799
}

‎webapp/view/App.view.xml

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<mvc:View
2+
controllerName="com.mrb.UI5-Navigation-and-Routing.controller.App"
3+
xmlns="sap.m"
4+
xmlns:mvc="sap.ui.core.mvc"
5+
displayBlock="true">
6+
<Shell>
7+
<App id="app"/>
8+
</Shell>
9+
</mvc:View>

‎webapp/view/Home.view.xml

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<mvc:View
2+
controllerName="com.mrb.UI5-Navigation-and-Routing.controller.Home"
3+
xmlns="sap.m"
4+
xmlns:mvc="sap.ui.core.mvc">
5+
<Page title="{i18n>homePageTitle}" class="sapUiResponsiveContentPadding">
6+
<content>
7+
<Button text="{i18n>iWantToNavigate}" class="sapUiTinyMarginEnd"/>
8+
</content>
9+
</Page>
10+
</mvc:View>

‎webapp/view/MainView.view.xml

-14
This file was deleted.

0 commit comments

Comments
 (0)