Using Densities for Controls

The devices on which applications developed with SAPUI5 are executed run on different operating systems and have very different screen sizes.

SAPUI5 provides different content densities for certain controls that allow an application to adapt to the device by displaying larger controls for touch-enabled devices and a smaller, more compact design for devices that are operated with the mouse.

In SAPUI5, the following content densities are available, among others:

• Cozy
• Compact

The default design for all controls belonging to the sap.m library is the Cozy density (larger dimensions and spacings). If your application only uses the sap.m library, you can skip setting the content density explicitly if the Cozy density is exactly what you require. However, controls belonging to other libraries may also support a Cozy design (such as sap.ui.table.Table) but the default might be different (such as Compact density). For this reason, if your application uses controls belonging to different libraries, it is strongly recommended to set the desired content density explicitly.

The content densities Cozy and Compact are triggered by the CSS classes sapUiSizeCozy and sapUiSizeCompact respectively.

You set the appropriate CSS class on the container that you want to switch to the content density in question, not on the control itself. It is recommended that you set it at a high level, since in most cases you will want to set it for the entire application. Once you set the CSS class at a particular level, it cascades down, meaning you can't override it in the lower levels of your code.

For example, to display a view with all contained UI elements with the Compact content density, you can implement the following:

123
<mvc:View class="sapUiSizeCompact" ... >
  ...
</mvc:View>

It is also possible to apply the relevant content density only under certain circumstances, for example, for devices that do not support touch interaction. In this case, add the CSS class dynamically to the UI instead of statically.

To specify a content density depending on certain properties of the device on which the application runs, the Device API (sap.ui.Device) can be used.

The Device API provides information about device specifics, like the operating system along with its version, the browser and browser version, screen size, current orientation and support for specific features such as, touch event support, orientation change, and so on. (For detailed information about the Device API, see the API Reference for the sap.ui.Device namespace.)

Implementing a Helper Method on the Component Controller 

The figure, Helper Method on the Component Controller, shows how the CSS class required for the content density can be determined with the help of the Device API. For this purpose, a helper method called getContentDensityClass is created on the component controller, which checks via the sap.ui.Device.support.touch field of the Device API whether the device on which the application is running has touch support. The Device API is loaded via the dependency array of the component controller. If the device has touch support, the method returns the CSS class sapUiSizeCozy, otherwise the CSS class sapUiSizeCompact.

Setting the CSS Class for a View

The getContentDensityClass helper method can be called, for example, in the controller of the component's root view to set the appropriate CSS class for the entire application. The coding required for this is shown in the figure Setting the CSS Class for a View.

In the onInit initialization method of the view controller, the controller's getOwnerComponent method is used to access the component controller. On this, the getContentDensityClass helper method discussed above is called, which returns the CSS class depending on the touch support of the device. The CSS class obtained is then added to the view via the addStyleClass method.

The sap.ui5 namespace of the application descriptor manifest.json has the mandatory attribute contentDensities. This attribute contains an object that is used to maintain the content density modes that the application supports (see the figure, Supported Content Densities, for an example). 

When the application is invoked through the SAP Fiori launchpad (FLP), the FLP reads the supported content densities from the application descriptor and sets the appropriate content density class for the <body> tag. On devices with mouse and touch support, the FLP also allows the user to configure the desired content density.

If you determine and set the CSS class for the content density of an application dynamically as described above, you should avoid that the application and the FLP set different content density classes in case the application is also started in the FLP. In the above example, you could do this by extending the helper method getContentDensityClass as follows: If the FLP has already set a content density CSS class, the helper method should return an empty string. The JavaScript coding required for such an extension can be found in the documentation.

In addition to the CSS classes for specifying the content density, SAPUI5 provides further CSS based options for adapting an application to the device on which it runs.

To determine a control’s visibility in a device-dependent way, you can use the following CSS classes:

• sapUiVisibleOnlyOnDesktop
• sapUiHideOnDesktop
• sapUiVisibleOnlyOnTablet
• sapUiHideOnTablet
• sapUiVisibleOnlyOnPhone
• sapUiHideOnPhone

The names of the CSS classes are self-explanatory; for each device type, you have a corresponding class that you can use to either explicitly hide or show a control.

Thus, the panel in the figure, CSS Based Device Adaptation, is displayed only on tablets and desktops, but not on phones.

SAPUI5 gives you the option to add space between controls by adding margins. A margin clears an area around its respective control, outside of its border.

If your application is supposed to run on phone, tablet and desktop, it may be useful to choose margins depending on the available screen width. SAPUI5 provides the CSS class sapUiResponsiveMargin that does just that. It works with media queries to determine the available screen width and adapts the margins to it.

In the figure, CSS Based Device Adaptation, the margins of the panel are made dependent on the available screen width by adding the CSS class sapUiResponsiveMargin.

Detailed information about further margin and padding classes can be found in the documentation.