How to Use Densities for Controls

Using Densities

A density is triggered by the related CSS class, for example, sapUiSizeCompact for the Compact density, set on a parent element of the UI region for which you want to use the controls. This means that some parts of the UI or different apps inside a sap.m.Shell can use the standard density of the sap.m controls, while other parts can use a different density at the same time. However, sub-parts of the UI part that is set to Compact density cannot use the Cozy density because the CSS class affects the entire HTML subtree.

As dialogs and other popups are located at the root of the HTML document, you also have to set the CSS class for those elements to the respective density. The CSS class only affects child controls. You cannot make a control itself compact or cozy by adding the CSS class to it. Instead, set the CSS class on the parent container, for example a view or a component.

XML view definition - Example:

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

JS view definition - Example:

createContent: function(oController) {
   ...
   this.addStyleClass("sapUiSizeCompact"); // make everything inside this View appear in Compact density
   ...
}

JavaScript opening a dialog - Example:

var myDialog = new sap.ui.commons.Dialog({.....}).addStyleClass("sapUiSizeCompact");
myDialog.open();

JavaScript instantiating a view - Example:

var myView = sap.ui.view(...);
myView.addStyleClass("sapUiSizeCompact");

Note

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

sap.ui.controller("my.controller", {
   onInit: function() {
      // apply compact density if touch is not supported, the standard cozy design otherwise
      this.getView().addStyleClass(sap.ui.Device.support.touch ? "sapUiSizeCozy" : "sapUiSizeCompact");
   }
});

As the check depends on several factors, you may not want to repeat the same logic again and again. A dialog opened from a compact or cozy view should, for example, also be in Compact or Cozy density.

Synchronizing a Density for a Dialog

As dialogs are rendered in a different part of the HTML tree, they do not automatically inherit the density. To decide if you set the relevant density for a dialog, either perform the same check as for the view or use the convenience function jQuery.sap.syncStyleClass. This convenience function synchronizes a style class between elements. The function accepts the following parameters: Name of the style class, source element, and destination element. The following code snippet shows an example:

<mvc:View
    controllerName="mycontroller"
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m">
    <Button text="Show Dialog" press="onOpenDialog" />
</mvc:View>

<core:FragmentDefinition xmlns="sap.m" xmlns:core="sap.ui.core">
    <Dialog title="Alert" type="Message">
        <Text text="Lorem ipsum dolor sit amet" />
        <beginButton>
            <Button text="Close" press="onDialogClose" />
        </beginButton>
    </Dialog>
</core:FragmentDefinition>

sap.ui.controller("mycontroller", {
    onOpenDialog: function (oEvent) {
        if (! this._oDialog) {
            this._oDialog = sap.ui.xmlfragment("mydialog", this);
            this.getView().addDependent(this._oDialog);
        }

        // sync compact style
        jQuery.sap.syncStyleClass("sapUiSizeCompact", this.getView(), this._oDialog);
        this._oDialog.open();
    }
});

When calling jQuery.sap.syncStyleClass, the source element can be a jQuery object, a SAPUI5 control, or the ID of an HTML element. The destination object can either be a jQuery object or a SAPUI5 control.

Checking for the Density Style Class

To determine if the relevant style class is set anywhere above a certain HTML element, you can use the closest function from jQuery as shown in the following example:

var btn = new sap.m.Button({
    text: "Hello World",
    press: function(){
        var dialog = new sap.m.Dialog({
            title: "Hello World",
            content: new sap.m.Button({text:"Test Me"})
        });
        
        
        // add the 'sapUiSizeCompact' class if the Button is in an area using Compact density
        if (this.$().closest(".sapUiSizeCompact").length > 0) { // "this" in the event handler is the control that triggered the event
            dialog.addStyleClass("sapUiSizeCompact");
        }
        
        
        dialog.open();
    }
});

Using Density Classes in the SAP Fiori Launchpad

The SAP Fiori launchpad (FLP) optionally reads the supported content densities from the app descriptor (manifest.json) and - if available - sets the appropriate content density class on the <body> tag. On devices with mouse and touch support, the FLP also allows the desired content density to be configured by the user. To avoid situations where an application and the FLP write different content density classes, we recommend using the following logic within all applications that are intended to be used inside the FLP:

getContentDensityClass : function() {
      if (this._sContentDensityClass === undefined) {
             // check whether FLP has already set the content density class; do nothing in this case
             if (jQuery(document.body).hasClass("sapUiSizeCozy") || jQuery(document.body).hasClass("sapUiSizeCompact")) {
                   this._sContentDensityClass = "";
             } else {
                    // Store "sapUiSizeCompact" or "sapUiSizeCozy" in this._sContentDensityClass, depending on which modes are supported by the app.
                    // E.g. the “cozy” class in case sap.ui.Device.support.touch is “true” and “compact” otherwise.
             }
      }
      return this._sContentDensityClass;
}

This function returns an empty string if the FLP has already set a content density CSS class, or the proper CSS class to be set. The result of this function should then be set as a style class on the root view of the application and all dialogs and popups.

Providing Density Support for a Control

If you want to apply content densities to your own controls, provide the default CSS styling for the Cozy density regardless of any size density classes and provide additional CSS styling to shrink the size, if an ancestor element has the sapUiSizeCompact class, for example, for the Compact density. The following code snippet shows you an example:

.myOwnControl { /* the standard (big) style */
   ...
   height: 3rem;
   ...
}

.sapUiSizeCompact .myOwnControl { /* reduce the height in compact density */
   height: 2rem;
}