Scrolling: Implementation Details

SAPUI5 embeds the open source library iScroll4 that takes care of scrolling in the application.

Scrolling support in mobile browsers is weak and inconsistent. Only the latest platforms and browsers start to support partially usable scrolling functionality. To avoid this, SAPUI5 supports iScroll4. Though the library is globally available in a SAPUI5 application, programmers should not call it directly. The sap.ui.core.delegate.ScrollEnablement delegate provides all functionality and smooth integration of iScroll4 into the SAPUI5 library.

Do not use nested scrolling

We do not recommend to use nested levels of scrolling, for example, when a page with enabled vertical scrolling contains a scroll container that has vertical scrolling too. Such combinations may lead to behavior that is unexpected both for programmers and users.

Implement a custom scroll container

A custom control that needs to provide a scrollable area for its content should implement the following steps:

Instantiate a sap.ui.core.delegate.ScrollEnablement delegate, at best in the .onAfterRendering callback.
Implement a .getScrollDelegate method that returns the current instance of the delegate to other controls.
Destroy the ScrollEnablement delegate on exit.

Example:

myCustomScroller.prototype.onAfterRendering = function() {
  if(!this._oScroller){
    jQuery.sap.require("sap.ui.core.delegate.ScrollEnablement");
    // attach a scroller to the scrollable container DOM element
    this._oScroller = new sap.ui.core.delegate.ScrollEnablement(this, this._scrollContainerId, {
      horizontal: false,
      vertical: true
    });
  }
};

myCustomScroller.prototype.getScrollDelegate = function() {
  return this._oScroller;
};

myCustomScroller.prototype.exit = function() {
  if(this._oScroller){
    this._oScroller.destroy();
    this._oScroller = null;
  }
};

Note The Zynga scroller that is included in the SAPUI5 library is deprecated. The configuration parameter oConfig.zynga=true of the scrolling delegate should not be used.

Interaction with the scroll containers

There are cases, when an embedded control controls scrolling of the parent container, if required. These are

a sap.m.ScrollContainer inside a sap.m.Page may block parent scrolling, if it scrolls in the same direction itself;
a sap.m.TextArea control in edit mode blocks parent scrolling, so that the user can scroll text contents during input;
a sap.m.GrowingList control scrolls parent container to update positions of visible items after the new items have been loaded from the server.

When using a sap.m.FlexBox with fitContainer:true or sap.m.TileContainer inside a page, the enableScrolling property of the page needs to be set to false for the FlexBox or TileContainer to fit the viewport.