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 Quantum Visualizer recommends you to use global version 10.0 or higher while using Cordova.
Widgets are normally added to your application using Quantum Visualizer, but can also be added from code. For general information on using widgets in Quantum Visualizer, see Designing an Application in the Visualizer User Guide.
For general information on the CordovaBrowser widget see the CordovaBrowser topic in the Quantum Visualizer 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
| Events | Description |
|---|---|
| doLayout | Invoked for every widget when the widget position and dimensions are computed. |
| Properties | Description |
|---|---|
| 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. |
| left | Determines 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. |
| showProgressIndicator | Specifies if the progress indicator must be displayed before loading the URL or executing an event. |
| top | Determines 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
| Methods | Description |
|---|---|
| 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
| Methods | Description |
|---|---|
| animate | Applies an animation to the widget. |
| Properties | Description |
|---|---|
| transform | Contains an animation transformation that can be used to animate the widget. |
Data Management
| Methods | Description |
|---|---|
| clearHistory | Clears 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 |
|---|---|
| handleRequest | Invoked 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. |
| Properties | Description |
|---|---|
| baseURL | Used to configure the base URL that is displayed when a CordovaBrowser is rendered. |
| clearCanvasBeforeLoading | Clears 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 native capabilities from within the web app's JavaScript code. |
| loadPageInBrowser | Enables 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. |
| settings | Helps you to configure the Browser Widget settings. |
| zoomDensity | Specifies the default zoom density of the page. |
3D Touch
| Methods | Description |
|---|---|
| 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. |
| Properties | Description |
|---|---|
| enableFocusInTouchMode | Enables or disables the Browser widget from scrolling to the top of the device screen. |
User Input Handling
| Events | Description |
|---|---|
| onScrollWidgetPosition | Invoked by the platform when the widget location position gets changed on scrolling. |
| scrollingEvents | Called when scrolling reaches beginning of the widget or end of the widget. |
| Methods | Description |
|---|---|
| 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
| Properties | Description |
|---|---|
| retainContentAlignment | Helps to retain the content alignment of the widget while applying RTL. |
| retainFlexPositionProperties | Helps to retain the left, right and padding properties while applying RTL. |
| retainFlowHorizontalAlignment | Enables you to change the horizontal flow of the widget from left to right. |
Miscellaneous
| Properties | Description |
|---|---|
| cursorType | Specifies 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. |
| Methods | Description |
|---|---|
| evaluateJavaScript | Accepts a JavaScript snippet in the form of a string. |
| evaluateJavaScriptAsync | Accepts a JavaScript snippet and a callback function as inputs. |
| getHTMLFilesInWebFolder | Retrieves 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. |
| isCordovaAppsEnabled | Retrieves a Boolean value that indicates whether Apache Cordova apps are enabled. |
| isHtmlPreviewEnabled | Retrieves a Boolean value that indicates whether your app can open an HTML preview. |
| isWebAppDevelopmentEnabled | Retrieves 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
| Properties | Description |
|---|---|
| accessibilityConfig | Enables you to control accessibility behavior and alternative text for the widget. |
| enable | Allows you to make a widget visible but not actionable. |
| enableCache | Enables you to improve the performance of Positional Dimension Animations. |
| id | id 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. |
| Methods | Description |
|---|---|
| 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. |
| setEnabled | Specifies the widget that must be enabled or disabled. |
| setFocus | Specifies the widget on which there must be focus. |
| setVisibility | Use 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:
- 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.
Building Web and Apache Cordova Apps
As of Quantum Visualizer 7.1, developers can package their web apps or Cordova/ PhoneGap apps inside a Quantum 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 Quantum 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 Quantum Visualizer easily and with very little modification by simply dragging and dropping a CordovaBrowser widget into a Quantum 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 the CordovaBrowser widget. Therefore, anyone familiar with Apache Cordova or PhoneGap development is able to create apps within Quantum Visualizer so that they can run their apps virtually anywhere.
Typically, developers who are creating web or Cordova apps within Quantum 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 Quantum 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 Quantum Visualizer, use the steps below.
- Start a new project in Quantum Visualizer and drag a CordovaBrowser widget onto the app's form.
- Go to the Projects pane and find the Web folder in your project's hierarchy. In the Web folder is a subfolder called localfiles.
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.
- Build your app for as many platforms as you want to support in just the same way you would build and other Quantum Visualizer app.
How to Build an Apache Cordova App in the CordovaBrowser Widget
To build a Cordova app using Quantum Visualizer, use the steps below.
- Start a new project in Quantum Visualizer and drag a CordovaBrowser widget onto the app's form.
- Go to the Projects pane and find the Web folder in your project's hierarchy. In the Web folder is a subfolder called cordova.
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.
- Build your app for as many platforms as you want to support in just the same way you would build and other Quantum 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 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 kony.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 Quantum Visualizer 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
Quantum Visualizer 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. Quantum Visualizer 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.