At the beginning of SAP UI5, it can be confusing what the differences are between the main container controls in SAP UI5 and when to use which.
In the following are the SAP UI5 main container controls explained and stated when which control is to use.
The nesting of the main container controls usually looks like this:
For example, the App or SplitApp control goes into the Shell control, the View control in the App or SplitApp control, and so on.
The sap.m.Shell control is the root control for an SAP UI5 application.
The Shell control provides some functionalities across an SAP UI5 application such as the option to set a logo. Plus, the shell takes care of the visual adaption of the application.
For example, through the Shell, it is possible to limit the width of the content of an application – so-called letterboxing. The appWidthLimited property of the Shell is by default turned on and set to 1280 px.
The letterbox width limitation affects only the desktop view of an application. Because the purpose of the limitation is to preserve the original aspect ratio of the application for larger screens and therefore, prevents that the content does not become distorted or stretched when adapting to larger screens.
You can easily see if a Shell control exists in an SAP UI5 application without looking into the code: The Shell control adds this for SAP UI5 applications notorious little bar at the top of an application.
However, the Shell control is not mandatory for an application.
Here is an example of the sap.m.Shell control in an SAP UI5 mini-application to tinker around.
- Each does basic modifications to the HTML page which make it more suitable for mobile apps.
- Each inherits from sap.m.NavContainer and thus provides an application with navigation capabilities like navigation between pages and full-screen controls.
Furthermore, the App and SplitApp controls offer to set a background across an application with the backgroundImage property.
The App control is not necessary to make an SAP UI5 application work, but it is supposed to be in any application because of the two stated reasons above.
You are supposed to have only one App or SplitApp control for one SAP UI5 application.
However, the App control makes no visual adaptions out of the box to an application – if you add it to an application, you will see no difference to before by default.
Here is an example of the sap.m.App control in an SAP UI5 mini-application to tinker around.
The sap.m.SplitApp is just the same as sap.m.App except that it features two sap.m.NavContainer in the desktop and tablet mode – if it is running on a phone it has just as the sap.m.App one nav container control.
Each NavContainer has an area on its own – the SplitApp control splits the application into two containers:
- Master area
- Detail area
Here is an example of the sap.m.SplitApp control in an SAP UI5 mini-application to tinker around.
The sap.m.SplitContainer offers the same features as the sap.m.SplitApp. But the use case of a SplitContainer control is when an SAP UI5 application has as the root control the sap.m.App but the application is supposed to feature a master-detail view as well:
For example, the start page of the application is supposed to be a single site like a sap.m.App with a nested sap.ui.core.mvc.View and sap.m.Page. That site links to another site of the application. And this site is supposed to have a master-detail view – then this view contains a sap.m.SplitContainer:
——— sap.ui.core.mvc.View (site 1)
———— sap.m.Page (site 1)
——— sap.ui.core.mvc.View (site 2)
———— sap.m.SplitContainer (site 2)
————— sap.m.Page (site 2 – master)
————— sap.m.Page (site 2 – detail)
The sap.m.SplitContainer looks exactly the same as the sap.m.SplitApp.
The sap.ui.core.mvc.View does in particular three things:
- Connects itself to a controller and therefore, its content – such as for example, a sap.m.Page and its content inside of the View. Hence, the View is crucial in realizing the Model-View-Controller architecture in SAP UI5.
- Sets some basic visual appearances like width and height.
- Provides lifecycle event hooks which can be used in a View’s controller: onInit, onBeforeRendering, onAfterRendering, onExit.
A View control reflects a simple website or an area of a website. The sap.ui.core.mvc.View is the base class for its sub-views:
To use the XML View is best practice for SAP UI5.
The View control makes like the App control by default no visible adaption to an SAP UI5 application.
Here is an example of the sap.ui.core.mvc.View control in an SAP UI5 mini-application to tinker around.
The sap.m.Page represents one screen or one site of an SAP UI5 application. The Page control is usually the container control for all other non-container controls of a site: From a sap.m.Button, through a sap.ui.table.Table, to a sap.ui.comp.smartchart.SmartChart.
The page control features three areas in which the other controls go:
The header is the top area of a Page. The header contains a back navigation button and a title by default.
The content is the main area of a Page between the header and the footer. Only the content area is scrollable by default. In the content area goes usually the main content of the site.
The footer is the bottom area of a Page. The footer is optional. It is fixed to the bottom by default. But it can be set to float above the content area with the property floatingFooter. Into the footer area usually go buttons such as a save or cancel button.
Here is an example of the sap.m.Page control in an SAP UI5 mini-application to tinker around.
The sap.f.DynamicPage has the same scope as a sap.m.Page. Plus, a DynamicPage consists of three areas as well:
The sap.f.DynamicPage is kind of the new version of the sap.m.Page – almost all new SAP Fiori standard applications use the DynamicPage instead of the sap.m.Page. The sap.m.Page exists since the first SAP UI5 release in the year 2013 and the sap.f.DynamicPage exists since the SAP UI5 version 1.46 release in the year 2017.
The sap.f.DynamicPage features a new design in comparison to the sap.m.Page such as a redesigned footer area or a header that is toggleable.
The DynamicPage control is to use if a title is needed, that is always visible and a header, that is collapsible and expandable. If there is no need for the header toggle function then it is recommended to use the Page control because it is a lighter control than the DynamicPage.
But keep in mind that only the DynamicPage fulfills the newest Fiori design guidelines as stated above.
Semantic Page (Page)
The sap.m.semantic.SemanticPage is an enhanced sap.m.Page; the difference is that the SemanticPage contains semantic controls. Semantic controls are controls with predefined placement, behavior, and style in a SemanticPage.
Therefore, the purpose of a SemanticPage is to provide a consistent look and feel over different applications sites and various applications.
A SemanticPage automatically positions semantic controls inside of it in dedicated sections of its footer or the header area. In the content are you can put whatever you like.
SemanticPage (Dynamic Page)
The sap.f.semantic.SemanticPage is an enhanced sap.f.DynamicPage – same, same as what goes for the sap.m.semantic.SemanticPage and its relation to the sap.m.Page except that the sap.f.semantic.SemanticPage relations is to the sap.f.DynamicPage instead of to the sap.m.Page.
The obvious difference between the sap.m.semantic.SemanticPage and the sap.f.semantic.SemanticPage is that the sap.f.semantic.SemanticPage looks like a sap.f.DynamicPage whereas the sap.m.semantic.SemanticPage looks like a sap.m.Page. Who would have thought it.
Another difference is that the sap.m.semantic.SemanticPage uses the SAP Fiori 1.0 design guidelines and the sap.f.semantic.SemanticPage uses the SAP Fiori 2.0 design guidelines – same what goes for the sap.m.Page and the sap.f.DynamicPage.
The sap.ui.core.Fragment is like a sap.ui.core.mvc.View except that it does not have a controller on its own – Fragments are nested into Views and therefore, using the controllers of their View.
A Fragment is a container on its own inside of a View container, but it is using the controller of its View.
A Fragment can be defined in different formats just as a View:
Use cases of a Fragment are:
- Modularization of the user interface without fragmenting controllers
- Declarative definition of views
- Re-use of user interface parts
For example, an SAP UI5 application has a table which is used over multiple sites. That table would go into a Fragment. And the Fragment would go into each View of each site where the table is supposed to be. That would be a re-use of the user interface part of a table.
Instead of copy and pasting the table in each View over and over it is only necessary to define the table once in the Fragment and then to integrate the table via the Fragment into each View with just a few lines of code.
A Fragment does not have any visual effects on a site by default.
The sap.m.Dialog is at the end of the SAP UI5 container controls hierarchy. A Dialog finds usually place within a Page. The Dialog is a pop-up window which holds whatever you put inside.
The Dialog is best to use for:
- to display a message which requires a user input such as okay or cancel
- to interrupt a user action
- to show values help
- to show messages with a description
- to display additional content to a site without reloading the site
All used acronyms and their full forms are in this ultimate SAP acronyms list alphabetically ordered.