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 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.