You are here: Important Considerations

CordovaBrowser Widget

Cordova is an open-source development framework for mobile applications that rely on JavaScript, HTML5, and CSS3 rather than the APIs that are specific to a given platform, such as iOS and Android.The layout of a Cordova app is built using web views. This layout is not created using any platform’s native UI framework. But, unlike other web apps, Cordova apps cannot access native APIs and cannot be bundled as apps for publication.

Cordova Browser widget is a container that displays web application designed in the Cordova platform. This widget helps you to view HTML/JavaScript content without navigating away from the application.

Following are the real-time use cases of Cordova Browser widget:

• To run video calling web applications developed in Cordova platform, you must use the Cordova Browser widget.

• To view Cordova based travel applications that embed maps, you must use Cordova Browser widget.

Note: In iOS applications created prior to iOS 12, CordovaBrowser widget uses UIWebView class in UIKit framework of iOS by default to display its contents. Apple has deprecated UIWebView class and recommends using the WKWebView class in WebKit framework.
As UIWebView class has been deprecated and its support will be removed from Apple, you must change the Browser Type of CordovaBrowser widget to WKWebView class.

When you modify the CordovaBrowser widget type to WKWebView, ensure that you add the cordova-plugin-wkwebview-engine plugin to your Cordova apps.

If the Cordova global version is 10.0 or higher, you must not add the cordova-plugin-wkwebview-engine plugin to your cordova apps.

If the Cordova global version is less than 10.0, you can add the cordova-plugin-wkwebview-engine plugin. However, you cannot submit your application to the App Store as the previous versions of Cordova contains UIWebView.
Hence Volt MX Iris recommends you to use global version 10.0 or higher while using Cordova.

Widgets are normally added to your application using Volt MX Iris, but can also be added from code. For general information on using widgets in Volt MX Iris, see Designing an Application in the Iris User Guide.

For general information on the CordovaBrowser widget see the CordovaBrowser topic in the Volt MX Iris User Guide.

The CordovaBrowser widget capabilities can be broadly categorized into the following:

• Layout
• Navigation Features
• Animations
• Data Management
• 3D Touch
• User Input Handling
• Enabling RTL
• Miscellaneous
• Configurations Common To All Widgets

Layout

Navigation Features

Animations

Data Management

3D Touch

User Input Handling

Enabling RTL

Miscellaneous

Configurations common to all widgets

Important: For Cordova browser, the.htmlString property is not available.

CordovaBrowser Widget Basics

Important Considerations

The CordovaBrowser widget has the following important considerations:

• On iOS and Android platforms, when the CordovaBrowser widget is set as non-screen level widget, and if you keep some widgets before and after the browser, then double scrolling issue will be seen. This is a native iOS issue. To avoid this, use the CordovaBrowser widget as screen level widget and move other widgets to the header or footer of the form.
• The CordovaBrowser widget, unlike other widgets, is considered to be “heavy” widget as far as memory and performance is considered.
• The CordovaBrowser widget uses a lot of initial RAM. The RAM usage grows in proportion to the number of images and static text rendered.
• If there are multiple instances of the CordovaBrowser widget in the same application, there may be issues related to sharing of information. For example, cookies etc.
• You must not place multiple CordovaBrowser widgets in a screen. As a guideline, you must not have more than two CordovaBrowser widgets in an application.
• You must not use CordovaBrowser widget as a RichText widget. It should only be used to display large HTML content.
• You must avoid using the CordovaBrowser widget to create an application which looks and behaves like a mini web browser. Users normally expect to use the native browser to browse web content. Replicating this functionality within your application is not recommended.
• Server side Mobile Web platform does not support CordovaBrowser widget in startup form.
• On SPA platform,
• On SPA (Windows) platform, content is rendered using a URL, opening a new tab is not technically possible. It opens in the current tab itself.

Building Web and Apache Cordova Apps

As of Volt MX Iris 7.1, developers can package their web apps or Cordova/ PhoneGap apps inside a Volt MX Iris app that uses the CordovaBrowser widget.

Web Apps are written in JavaScript and can execute in most browsers. Packaging a web app into a Volt MX Iris CordovaBrowser widget makes it highly portable across many types of devices. Most web developers who are proficient in JavaScript will find that they can port their web apps to Volt MX Iris easily and with very little modification by simply dragging and dropping a CordovaBrowser widget into a Volt MX Iris app, The rest of the development is done within the CordovaBrowser widget. This capability gives web developers a straightforward way to transition into developing mobile apps everywhere.

Apache Cordova is an open source project that was donated to the Apache Software Foundation. Also known as PhoneGap, Apache Cordova is a development environment that enables developers familiar with HTML, CSS, and JavaScript to build cross-platform mobile applications. Like web apps, Cordova apps can run within the CordovaBrowser widget. Therefore, anyone familiar with Apache Cordova or PhoneGap development is able to create apps within Volt MX Iris so that they can run their apps virtually anywhere.

Typically, developers who are creating web or Cordova apps within Volt MX Irissize the CordovaBrowser widget so that it fills or nearly fills the device’s screen. The CordovaBrowser widget then executes the web or Cordova app. All of the files for web apps and Apache Cordova apps can be packaged into the Volt MX Iris app and stored locally on the device. Your web app’s asset files can consist of any file type that the CordovaBrowser widget supports, such as HTML, CSS, JS, JPG, PNG, and MP4 files.

How to Build a Web App in the CordovaBrowser Widget

To build a web app using Volt MX Iris, use the steps below.

1. Start a new project in Volt MX Iris and drag a CordovaBrowser widget onto the app’s form.
2. Go to the Projects pane and find the Web folder in your project’s hierarchy. In the Web folder is a subfolder called localfiles.

3. Copy your web app’s asset files (HTML, CSS, JS, PNG, and other files) into the localfiles folder. You may create sub-folders and store your app’s assets in them if you want to.

   Important: When your app accesses its asset files, such as JPG, MP4, or CSS files, it must use relative addressing and not absolute addressing.

4. Build your app for as many platforms as you want to support in just the same way you would build and other Volt MX Iris app.

How to Build an Apache Cordova App in the CordovaBrowser Widget

To build a Cordova app using Volt MX Iris, use the steps below.

1. Start a new project in Volt MX Iris and drag a CordovaBrowser widget onto the app’s form.
2. Go to the Projects pane and find the Web folder in your project’s hierarchy. In the Web folder is a subfolder called cordova.

3. Copy your web app’s asset files (HTML, CSS, JS, PNG, and other files) into the cordova folder. You may create subfolders and store your app’s assets in them if you want to.

   Important: When your app accesses its asset files, such as JPG, MP4, or CSS files, it must use relative addressing and not absolute addressing.

4. Build your app for as many platforms as you want to support in just the same way you would build and other Volt MX Iris app.

Relative Addressing

As noted above, all accesses to the asset files in your web app must use relative addressing. For example, suppose your web app contains a file called index.html that is stored in a folder called help. The help folder, in turn, is a subfolder of LocalFiles. Accesses to the index.html file would resemble the following code snippet.

//refers to file MyWebproject/web/localfiles/help/index.html
var urlConf = {
    URL: "help/index.html",
    requestMethod: constants.BROWSER_REQUEST_METHOD_GET
};

var webBasic = {
    id: "browserID",
    isVisible: true,
    screenLevelWidget: false,
    requestURLConfig: UrlConf
};

Accessing Native Functionality

For security reasons it is important that web apps in the CordovaBrowser widget do not have access to native capabilities by default. Therefore, when your app starts, this access is disabled. However, you can enable it by setting the CordovaBrowser widget’s enableNativeCommunication property. Your app can only set this property in the CordovaBrowser widget’s constructor. After the constructor executes, this property is read-only.

Executing JavaScript in the Native Context

If your app sets the enableNativeCommunication property to true when it starts, then your app can call the voltmx.evaluateJavaScriptInNativeContext function to execute JavaScript functions within the context of your web app’s JavaScript modules.

JavaScript modules within your web app are the JavaScript modules in the LocalFiles folder, or one of its subfolders.

Your app can also include JavaScript modules that are executed in the native context. These modules are located in the Modules folder in your project, or one of its subfolders. JavaScript modules in the Modules folder generally contain event handlers for form events, functions to help process application data. So your app can be a hybrid app that uses widgets, JavaScript, and other Volt MX Iris capabilities together with bundled web content that is hosted in a CordovaBrowser widget.

If your app is a hybrid app that contains JavaScript modules that are executed in the native context (i.e., modules located in Modules folder, or one of its subfolders), it can call globally available functions and execute them within the web app’s context by invoking the CordovaBrowser widget’s evaluateJavaScript method. The call would look similar to the following example.

browserWidget.evaluateJavaScript(“displayAlert(‘Hello World’)”);

Security Considerations

Volt MX Iris recommends that you only enable the enableNativeCommunication property for local packaged content, not for dynamically downloaded content.

There is a known security risk on the Android operating system for versions 4.1 (API 16) or earlier. Volt MX Iris highly recommends that you not enable the enableNativeCommunication property on any version of Android prior to 4.2 (API 17).

Push Notifications

When using push notifications with the CordovaBrowser widget, your app should never bypass push notifications to use Cordova push notifications. This will cause an error. Always use the push notifications rather than the Cordova push notifications.