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:

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 Kony Visualizer recommends you to use global version 10.0 or higher while using Cordova.

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

For general information on the CordovaBrowser widget see the CordovaBrowser topic in the Kony Visualizer User Guide.

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

Layout

Events Description
doLayout Invoked for every widget when the widget position and dimensions are computed.
 
PropertiesDescription
anchorPoint Specifies the anchor point of the widget bounds rectangle using the widget's coordinate space.
bottom Determines the bottom edge of the widget and is measured from the bottom bounds of the parent container.
centerX Determines the center of a widget measured from the left bounds of the parent container.
centerY Determines the center of a widget measured from the top bounds of the parent container.
enableZoom Specifies if Zoom (ability to change the scale of the view area) must be enabled.
height Determines the height of the widget and measured along the y-axis.
leftDetermines the lower left corner edge of the widget and is measured from the left bounds of the parent container.
maxHeight Specifies the maximum height of the widget and is applicable only when the height property is not specified.
maxWidth Specifies the maximum width of the widget and is applicable only when the width property is not specified.
minHeight Specifies the minimum height of the widget and is applicable only when the height property is not specified.
minWidth Specifies the minimum width of the widget and is applicable only when the width property is not specified.
right Determines the lower right corner of the widget and is measured from the right bounds of the parent container.
screenLevelWidget Specifies whether the widget should occupy the whole container or not when your Browser widget has a large HTML content to display.
showProgressIndicatorSpecifies if the progress indicator must be displayed before loading the URL or executing an event.
topDetermines the top edge of the widget and measured from the top bounds of the parent container.
width Determines the width of the widget and is measured along the x-axis.
zIndex Specifies the stack order of a widget.
 

Navigation Features

MethodsDescription
canGoBack Specifies whether the CordovaBrowser can navigate back into history.
canGoForward Specifies whether the CordovaBrowser can navigate forward into history.
goBack Provides you with the ability to navigate one step back in the browser history.
goForward Provides you with the ability to navigate one step forward in the browser history.
reload Provides you with the ability to reload the current web page.

Animations

MethodsDescription
animateApplies an animation to the widget.
 
PropertiesDescription
transformContains an animation transformation that can be used to animate the widget.

Data Management

MethodsDescription
clearHistoryClears the page history of the specified CordovaBrowser.
clone When this method is used on a container widget, then all the widgets inside the container are cloned.
loadData Enables you to load the data into the CordovaBrowser widget with the provided configuration.
 
Events Description
handleRequestInvoked by the platform before CordovaBrowser widget navigates to a new URL.
onFailure Invoked by the platform when the given URL fails to load.
onProgressChanged Shows you the progress of the page loading in the CordovaBrowser Widget.
onSuccess Invoked by the platform when the given request URL is successful in loading the data.
 
PropertiesDescription
baseURL Used to configure the base URL that is displayed when a CordovaBrowser is rendered.
clearCanvasBeforeLoadingClears the browser's canvas before data is loaded.
detectTelNumber Specifies if the Browser widget must support the detection of phone numbers in the web page and display the phone numbers as clickable Phone links.
enableNativeCommunication Enables web apps to access Kony native capabilities from within the web app's JavaScript code.
loadPageInBrowserEnables the URL in CordovaBrowser widget to open inside the application.
requestURLConfig Specifies the configurations for the requested URL in key-value pairs as a JavaScript object or Lua table.
settingsHelps you to configure the Browser Widget settings.
zoomDensity Specifies the default zoom density of the page.
 

3D Touch

MethodsDescription
registerForPeekandPop Registers a widget to enable 3D Touch peek and pop gestures.
setOnPeek Sets and overrides the existing onPeekCallback for the widget.
setOnPop Overrides the existing onPopCallback for the widget.
unregisterForPeekandPop Unregisters a widget from 3D Touch peek and pop gestures.
 
PropertiesDescription
enableFocusInTouchModeEnables or disables the Browser widget from scrolling to the top of the device screen.

User Input Handling

EventsDescription
onScrollWidgetPosition Invoked by the platform when the widget location position gets changed on scrolling.
scrollingEventsCalled when scrolling reaches beginning of the widget or end of the widget.
 
MethodsDescription
addGestureRecognizer Allows you to set a gesture recognizer for a specified gesture for a specified widget.
removeGestureRecognizer Allows you to remove the specified gesture recognizer for the specified widget.
setGestureRecognizer Allows you to set a gesture recognizer for a specified gesture for a specified widget.
 

Enabling RTL

PropertiesDescription
retainContentAlignmentHelps to retain the content alignment of the widget while applying RTL.
retainFlexPositionPropertiesHelps to retain the left, right and padding properties while applying RTL.
retainFlowHorizontalAlignmentEnables you to change the horizontal flow of the widget from left to right.

Miscellaneous

PropertiesDescription
cursorTypeSpecifies the type of the mouse pointer used.
enableOverviewMode Specifies whether the browser should load pages in overview mode.
opacity Specifies the opacity of the widget.
 
MethodsDescription
evaluateJavaScript Accepts a JavaScript snippet in the form of a string.
evaluateJavaScriptAsync Accepts a JavaScript snippet and a callback function as inputs.
getHTMLFilesInWebFolderRetrieves a list of the HTML files of the specified type.
getBadge Enables you to read the badge value (if any) attached to the specified widget.
isCordovaAppsEnabledRetrieves a Boolean value that indicates whether Apache Cordova apps are enabled.
isHtmlPreviewEnabledRetrieves a Boolean value that indicates whether your app can open an HTML preview.
isWebAppDevelopmentEnabledRetrieves a Boolean value indicating whether web app development is enabled in the app.
setBadge Enables you to set the badge value to the given widget at the upper, right corner of the widget.

Configurations common to all widgets

PropertiesDescription
accessibilityConfig Enables you to control accessibility behavior and alternative text for the widget.
enableCache Enables you to improve the performance of Positional Dimension Animations.
idid is a unique identifier of Browser widget consisting of alpha numeric characters.
info A custom JSObject with the key value pairs that a developer can use to store the context with the widget.
isVisible Controls the visibility of a widget on the form.
parent Helps you access the parent of the widget.
 
MethodsDescription
convertPointFromWidget Allows you to convert the coordinate system from a widget to a point (receiver's coordinate system).
convertPointToWidget Using the convertPointToWidget method, you can modify the co-ordinate system.
removeFromParent Allows you to remove a child widget from a parent widget.
setEnabledSpecifies the widget that must be enabled or disabled.
setFocus Specifies the widget on which there must be focus.
setVisibilityUse this method to set the visibility of the widget.

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

CordovaBrowser Widget Basics

Important Considerations

The CordovaBrowser widget has the following important considerations:

Building Web and Apache Cordova Apps

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

Web Apps are written in JavaScript and can execute in most browsers. Packaging a web app into a Kony Visualizer 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 Kony Visualizer easily and with very little modification by simply dragging and dropping a CordovaBrowser widget into a Kony Visualizer 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 a Kony CordovaBrowser widget. Therefore, anyone familiar with Apache Cordova or PhoneGap development is able to create apps within Kony Visualizer so that they can run their apps virtually anywhere.

Typically, developers who are creating web or Cordova apps within Kony Visualizersize 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 Kony Visualizer 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 Kony Visualizer, use the steps below.

  1. Start a new project in Kony Visualizer 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 Kony Visualizer app.

How to Build an Apache Cordova App in the CordovaBrowser Widget

To build a Cordova app using Kony Visualizer, use the steps below.

  1. Start a new project in Kony Visualizer 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 Kony Visualizer 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 MyKonyWebproject/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 Kony 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 kony.evaluateJavaScriptInNativeContext function to execute Kony 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 Kony 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 Kony Visualizer User Guide 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 Kony 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

Kony 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. Kony 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 Kony push notifications to use Cordova push notifications. This will cause an error. Always use the Kony push notifications rather than the Cordova push notifications.

premCopyright © 2012 Kony, Inc. All rights reserved.
premCopyright © 2012 Kony, Inc. All rights reserved.