A Component based Master-Detail app template including device specific behavior and navigation and routing

SAPUI5 developers now that Master-Detail apps are quite common. However, often we don't know how to best implement a Master-Detail app with the default APIs of SAPUI5. I have implemented and seen some amusing approaches that worked, but from coding perspective many of them were horrible. In this tutorial I would like to illustrate a simple approach of implementing a Master-Detail app using the latest features introduced with SAPUI5 1.30 (however, without using semantic pages/controls). We will use OData, the MockServer, the Navigation & Routing API, XMLViews, manifest.json aka app descriptor as well dependency injection with sap.ui.define. You can use the result of this tutorial as a quick start template for your own Master-Detail apps. This tutorial works with SAPUI5/OpenUI5 1.30.x and above.

Before we start let's have a look at what we actually want to implement. As you can see from the Fiori Design Guidelines for Master-Detail apps a Master-Detail app has a master list and a details area. The master list contains items that can be selected in order to see the details of the selected item. When the app is started the first item in the master list is selected and the corresponding details are displayed in the details area. In case there is no item in the master list, the details area simply shows a message page. Depending on the device type (Desktop, Tablet or Phone) the app behaves slightly different. On desktops both the master list and the details area are displayed at the same time. On tablets only the details area is displayed while the master list can be displayed by either a swipe gesture or by pressing the menu button at the upper left corner of the details area's header. Typically, the master list would slide in as a popover. On phones, the first page that is displayed is the master list – it fills the whole screen. By pressing an item in the master list the user is navigated to the corresponding details page. That's the default behavior. Keep in mind that users might navigate to an item's details directly by a bookmark. In this case the corresponding item in the master list should be selected/highlighted. However, the master list can be quite large and most probably the requested item is currently not listed in the master list (think of "paging"). In such cases the search field of the master list can be filled with a corresponding value (i.e. the item's id) in order to make sure that the correct item is requested from the backend and displayed in the master list afterwards. In other words: the search field is used as a filter. That's it basically. Please check the official Master-Detail Demo App to see how a Master-Detail app feels like. Please be aware that this demo app uses a semantic control (see sap.m.semantic for details), which we will not use in this tutorial.

In this tutorial we are going to deviate a little bit from the behavior described above. We want to create an app that displays a list of companies in the master list and a list of all employees working for that company in the details area. From the employees list it will be possible to navigate one level deeper in order to see an employee's details. Of course, we will use the new navigation and routing features introduced with version 1.30 of SAPUI5. However, instead of selecting the first item of the master page and showing its details in the details page we will display an "app home page" which allows to search for a given employee across all or a specific company. The search page will also be available on phones. Furthermore, we will not select items in the master list in case of calling the app with a deep link (bookmark). I have seen many apps with requirements like these or apps that did not fulfill the Fiori Design Guidelines completely – and all of them had good reasons to do so. To prove this, a good example might be the SAPUI Explored app shipped with the SDK. It's basically a Master-Detail app. However, when opened on desktops or tablets it shows a nice and amusing "Star Wars"-like teaser in the default details area while the teaser is not available on phones. Besides that, the corresponding master list item is not selected when the app is called with a deep link, i.e. https://sapui5.hana.ondemand.com/explored.html#/entity/sap.m.Button/samples. So now, that the goal is set, let's write the code.