In this blog post, I would like to give you an overview of some new routing features and demonstrate how you can leverage them to enhance the user experience of your applications.
This blog post describes our recent enhancements of leveraging the
titleChanged
event in nested components. You will also see how this could be applied to the sample application featured in our previous blog post
UI5er Buzz #46 – Routing with Nested Components.
The titleChanged Event in Nested Components
Up to UI5 Version 1.74, the
titleChanged
event was fired on a router instance if the displayed target of the router had a
title
property defined. In order to react to the
titleChanged
event from any component in an application (including nested components), you had to use the
getRouter
method for all available components, attach a callback to the
titleChanged
event on every router and check if the provided title should be displayed or not. Furthermore, the
titleChanged
events needed to be forwarded to the root component, because the consumption of the event, for instance displaying the title in a header control, typically occurs in the root element of an application. Therefore, the consumption of the
titleChanged
event should become more convenient in the context of nested components.
Propagate titleChanged Event from Nested Components
With UI5 Version 1.75, a new property called
propagateTitle
was introduced. This property identifies whether a
titleChanged
event occurring in a child component should be propagated to its parent component. This property can be defined under the
target
manifest entry of a route (or in a router's global configuration) to enable or disable the title propagation from all its nested components. The following sequence for determining the value of the property is used:
1. The config of the desired route on
sap.ui5/routing/route/target
2. The routing config on
sap.ui5/routing/config
3. The default value
false
Advanced Usage and New Parameters
Since UI5 Version 1.75, the
titleChanged
event has been providing two additional
parameters which make the consumption of the event much easier and more powerful.
The propagated parameter
The
propagated
parameter provides information whether the
titleChanged
event was initially triggered by a nested component or by the component itself.
The nestedHistory parameter
The second newly introduced parameter
nestedHistory
is an array which contains the title history information of the current router and those of the routers of the nested components. If a hierarchical control is used to display title information (like the
sap.m.Breadcrumbs
control), the application could simply use the
nestedHistory
parameter to build up the control. It no longer has to merge the
history
parameters of all routers by itself.
Consume the titleChanged Event in the Sample Application
Let's see how to apply the new feature to the sample application featured in
UI5er Buzz #46 – Routing with Nested Components.
Concept
The following diagram shows how the set of components in the sample app are configured to propagate the
titleChanged
event. The
Root Component includes the
Suppliers Component as a target with _activated_ title propagation in the
manifest.json
property (
propagateTitle: true
). The
Suppliers Component includes the
Products Component as a target with _deactivated_ title propagation in the manifest property (
propagateTitle: false
).
Scenario 1
When the title of the
Suppliers Component is changed, a
titleChanged
event is fired on the router of the
Suppliers Component and propagated to the router of the
Root Component, which then fires its own
titleChanged
event:
Scenario 1 - The title of the
Suppliers Component is changed
Scenario 2
When the title of
Products Component changes, a
titleChanged
event is fired, but the event is not propagated to the
Root Component:
Scenario 2 - The title of
Products Component is changed
Coding
Firstly, I have to attach a callback to the
titleChanged
event of the
Root Component router. Therefore, I create a model in the
onInit
function of the
App.controller.js
of the
Root Component and provide the event parameters of the
titleChanged
event to the callback function.
onInit: function(){
...
var oTitlesModel = new JSONModel();
this.getView().setModel(oTitlesModel, "titleModel");
this.getOwnerComponent().getRouter().attachTitleChanged(function (oEvent) {
oTitlesModel.setData(oEvent.getParameters());
});
...
}
Secondly, I have to update the title value of the header in
App.view.xml
of the
Root Component. Therefore, I replace the hardcoded value with a property binding to the title, which is stored in the newly created model.
<tnt:ToolPage id="toolPage">
<tnt:header>
<tnt:ToolHeader>
<ToolbarSpacer />
<Title text="{= ${titleModel>/title}">
<ToolbarSpacer />
</tnt:ToolHeader>
</tnt:header>
Finally, I have to enable the title propagation from the included components (Suppliers, Categories and Products) by updating the
manifest.json
of the
Root Component. Therefore, I add the
propagateTitle
property to the
sap.ui5.routing.config
entry and set its value to
true
.
{
...,
"routing": {
"config": {
...
"propagateTitle": true
},
...
}
Define Titles for the Targets
While I have now activated the title propagation, one important step is still missing. I need to define titles! The proper places for defining titles is the
manifest.json
of the
Root Component and, if desired, also the
manifest.json
files of the nested components (Suppliers, Categories and Products).
There are multiple ways of defining titles. The default way is to add the
title
property to the
targets
entry of the
sap.ui5.routing
section:
{
...,
"targets": {
"home": {
"type": "View",
"id": "home",
"name": "Home",
"title": "Home"
},
"suppliers": {
"type": "Component",
"usage": "suppliersComponent",
"title": "Supplier"
},
"categories": {
"type": "Component",
"usage": "categoriesComponent",
"title": "Category"
},
"products": {
"type": "Component",
"usage": "productsComponent",
"title": "Product",
"id": "productRoot"
},
...
}
The
title
property might not only contain fixed text values. It's also possible to put a binding into the value of the
title
property. This allows me to dynamically change its value during the application lifecycle.
{
...,
"suppliers": {
"type": "Component",
"usage": "suppliersComponent",
"title": "{myModel>/myTitle}"
},
...
}
I can use this option to display the most current title in the component header.
Conclusion
With the above procedure, you can now use title propagation to display titles from nested components in the
Root Component even when you don't have a deeper knowledge of the included components' structures. This enables you to create strongly modularized apps with powerful navigational options.
Previous Post:
UI5ers Buzz #47: Performance Checklist for UI5 Apps
Next Post:
UI5ers Buzz #49: The UI5 Tooling and SAPUI5 – The Next Step
Author
florian.vogt#about is a UI5 Core developer, javascript advocate and cultivates a vineyard in the black forest. He is currently working on the UI5 Core to raise it to the next level. |