Running Mobile Apps in Hybrid Web Containers

SAPUI5 supports two options for building mobile apps: As a web application loaded from a URL, or as a hybrid app consisting of a native app wrapper, for example PhoneGap, and an HTML viewer to display the SAPUI5 content on the user interface.

Hybrid apps have the advantage that you can publish them in app stores. Also, by embedding the application code in hybrid apps and the SAPUI5 library files in the hybrid container, the user needs to install the files only once and does not need to download them every time he starts the application. But then the library size becomes important, because every user has to install the files, whereas in web applications the library is deployed on a server and the user only needs to download the required parts of the library at runtime.

To include the SAPUI5 resources you need in your hybrid app, SAPUI5 mobile provides the following static mobile runtime packages: sapui5-mobile-opt-static.zip or sapui5-mobile-static.zip.

Caution

The packages are not contained in the SAPUI5 runtime deployment. The packages are contained in the SCN download version of SAPUI5 and in the Open Source version OpenUI5 (file name in the OpenUI5 release: openui5-runtume-mobile*.zip)

The library size of these packages is rather small because the content that is most likely not needed has been removed, for example test pages. A package contains the debug version of all JavaScript files and the optimized and minimized version. Thus, you can use the package for productive use as well as for debugging purposes. To use this package in an app wrapper, such as PhoneGap, unzip the package in the respective resource location of the app development project. The app wrapper build then includes the files and makes them available at runtime.

To ensure that the file is small, it only contains the control libraries that are most likely used and not all control libraries. Depending on the hybrid app it may be necessary to add libraries by copying them from the respective folder of the SAPUI5 runtime, or to delete libraries to reduce the package size and, thus, also reduce the installation size for the user.

The SAPUI5 version contains the following control libraries:

sap.ui.core
sap.ui.layout
sap.ui.unified
sap.m
sap.me
sap.makit
sap.ca.ui
sap.ca.scfld
sap.viz

The OpenUI5 version contain the following control libraries:

sap.m
sap.ui.core
sap.ui.layout
sap.ui.suite
sap.ui.unified

The decision, which libraries to include or not may be disputed. It is only based on a rule of thumb, and adaptations are required anyway for many apps.

Also, the mobile/hybrid package excludes certain types of files which are typically not needed. Your mileage may vary, so you might need to add the respective files for the requirements of your specific app. One example are the library-RTL.css stylesheets and img-RTL folders containing the visuals for right-to-left languages. The library-preload.json files which contain all controls from a library to reduce the number of HTTP requests are also not required in hybrid apps because there is no HTTP latency. SAPUI5 will by default try to access them, so you might see a failed attempt to load these files in the log file or developer tools. These error messages do not hurt, though, and you can get rid of them by declaring that no such files exist and by setting the following configuration in the SAPUI5 bootstrap script tag:

data-sap-ui-preload=""

Optimization of the Package Size

Although the static SAPUI5 package is small enough to be included in hybrid apps, you can reduce the size further and optimize the content for a specific application by deleting additional files. The following list gives some examples:

You can delete one of the following files from the /resources folder depending on your setup: sap-ui-core-nojQuery.js if you reference SAPUI5 normally or sap-ui-core.js if you reference the nojQuery version and reference the jQuery version separately, for example if you run in a Sybase hybrid container.
You can delete all library folders if the respective control library is not needed. If you do not use charts, you can delete the complete makit and viz folder in /resources/sap. And in the OpenUI5 version you can, for example, delete the suite and the unified folder if you do not need them.
If you use the sap-ui-core.js file for bootstrap, you can delete the jquery and jqueryui folders in /resources/sap/ui/thirdparty. These files may be needed when you use the sap-ui-core-nojQuery.js script, but if you have another copy of jQuery available you can still delete the folder.
Depending on the theme you use, you can delete the base and either the sap_bluecrystal or the sap_mvi folders in each of the /resources/sap/* ... */themes folders.

Note

For all JavaScript files, an optimized version and a debug (dbg) version exists. If you delete the files, make sure that you always delete both versions. If you can do without easy debugging and want to achieve a minimum installation size instead, you can delete all *-dbg.js files.

You can delete further files, but the size reduction is limited and to find out the files that are not required gets increasingly difficult.

You can also add additional control libraries by copying the respective folder from the sapui5-static.zip or openui5-runtime-*.zip file. The control libraries are identical and can be used interchangeably provided that they have the exactly same version.

Device Ready Event

The hybrid web container needs some time for initialization. During this time, the sending of AJAX requests is blocked, meaning that JavaScript code stops once an AJAX request is sent and the code execution stops as well. This leads to a UI freeze effect.

The oData model in SAPUI5 uses AJAX requests internally and the oData model initialization must therefore be done after the hybrid container is ready to avoid a user interface freeze. After initialization, the hybrid web containers fires an event, which is called deviceready in PhoneGap. To fix this issue, move the code where the oData model is created and set to the core object or any other controls' model property to the deviceready event listener.

Example:

<script>
<!-- put the following code in the beginning of the application code -->
function appReady(){
    sap.ui.getCore().setModel(new sap.ui.model.odata.ODataModel(<ODATA_URL>, false));
}
<!-- bind to the deviceready event -->
document.addEventListener("deviceready", appReady, false);
</script>

Cross Domain Restrictions

If you load data from an external server or service using AJAX, the external domain has to be configured inside the hybrid web container to make the AJAX request go through the cross domain restriction. The following findings result from an integration of the SAPUI5 demo applications into PhoneGap:

Android

If the AJAX code runs inside the webview in Android, no cross domain restriction exists. This means that you can load data using AJAX from everywhere. The PhoneGap documentation, however, still says that the domain needs to be configured in one XML file.
iOS

The restriction in webview in iOS still exists and you need to add the domain that is visited using AJAX to a whitelist file to bypass the restriction. For detailed information about the whitelist file, see the PhoneGap documentation on the PhoneGap website.