Navigating to Routes with Mandatory Parameters

Suppose that when the user selects an entity (for example, customer, sales order) on an initial view, the application is to navigate to another view where details about the selected entity are displayed. To implement such a master-detail scenario, you can pass the data of the selected entity (for example, the associated Id) to the detail view via one or more parameters of the route. The parameter(s) can then be used by the detail view to identify the entity and fetch and display additional information.

SAPUI5 supports routes with mandatory and optional parameters, which are both defined in the pattern of a route. You specify a mandatory parameter for the pattern by placing the parameter in curly brackets.

In the example shown, a mandatory parameter named customerId is defined for the detail route. This makes, for example, the hashes detail/5 and detail/(00505604-4e85-1edd-818f-21e64b9cd2cf) match the route, while the hash detail/ does not. The patternMatched event of the route (see the next section) is then passed 5 or (00505604-4e85-1edd-818f-21e64b9cd2cf) as customerId in its arguments parameter.

The parameters of a route are set using the navTo method of the router. After the name of the route to be navigated to, a configuration object with the parameter values for the route is passed to this method as the second parameter.

The router always makes sure that mandatory parameters as specified in the route's pattern are set; otherwise an error is thrown.

In the example shown, the router's navTo method is called in an event handler of the initial view to navigate to the route named detail. This route has the mandatory parameter customerId, which is supplied with a value via the object passed as the second parameter.

In the example, it is omitted how the Id of the customer is determined. For example, it could be obtained via the binding context of the UI element selected by the user.

Using the code shown, the hash of the browser is set to detail/<value of customerId parameter>.

In the view that is being navigated to, the passed customer Id must now be extracted again in order to be able to fetch and display additional information about the customer.

In the example shown, the Route object for the detail route is queried in the onInit initialization method of the detail view controller via the getRoute method of the router. On this object, the attachPatternMatched method is called. This registers the _onObjectMatched method of the view controller to the patternMatched event of the route. That is, the _onObjectMatched method is called if and only if the current URL hash matches the pattern of the route. In this case, the value of the customerId parameter is extracted in the _onObjectMatched method.

The context of the _onObjectMatched event handler method (its this) is bound to the Route object of the detail route by default. Therefore, the attachPatternMatched method is passed the view controller (this) as second parameter to bind the context of the _onObjectMatched method to the view controller. This allows the view controller to be accessed via this in the implementation of the _onObjectMatched method.

The patternMatched event has a parameter called arguments. This parameter is a key-value pair object that contains the parameters defined in the route resolved with the corresponding information from the current URL hash. In the implementation of the _onObjectMatched method, this event parameter is accessed and the value for the customerId parameter is extracted from it.

In the sample code, it is omitted how to proceed with the obtained Id. For example, using this.getView().bindElement(), the binding context of the view could be set to the selected customer to display additional information about it.