PhoneGap ChildBrowser plug-in

Author: Eugeniy Marilev
Date of publication: 2014-05-06 10:30:17
It has already been told about the main principles of developing mobile applications using PhoneGap, if we are ready — let's move on - if not, read the first article on the PhoneGap. So what is this plug-in about? Imagine that your application PhoneGap implements web-search, for example, in Google, the results are displayed in a for of a list. For example, we need to open a link in your browser by clicking a search result. Actually, it is easy to implement by the kernel of the PhoneGap library, but by default all links open in a browser by default, that is to say, when you click on the link to open a separate application (for Android - Chrome, for IOS - Safari). There is a number of factor which are opposed to the standard method of treatment the links: When you open a new application in IOS, the previously opened minimizes to tray (IPhone 4G), or even close (IPhone 3G) Application loses control over the further processing of user's operations. That's why has been developed ChildBrowser plug-in. Here is a list of its features:
  • Open this link in a standard browser.
  • Open this link in a child browser.
  • Close the window of a child browser.
  • Callback for redirects within the child browser.
Let's take a close look at every detail of the above functions.

Open this link in a standard browser

window.plugins.childBrowser.openExternal(url, [usePhoneGap = false])
- Opens the default browser and loads the address of its «url», usePhoneGap parameter specifies the use of the mechanism of white list (a list of trusted addresses) of your application.

Open this link in a child browser

window.plugins.childBrowser.showWebPage(url, [options])
- Opens a child view for the main view of your application, which is a standard mechanism with help of which PhoneGap can communicate with the application. A child view can be called even a pop-up dialog. This functionality is commonly used instead of the standard javascript approach to open a child window - window.open. The list of options of the«showWebPage» method is still short enough: «showLocationBar» (true / false) — whether shows or not the navigation panel of browsing (the address field, button: back, forward, refresh the page).

Close the window of a child browser

window.plugins.childBrowser.close()
- Closes the window of a child browser. This method can not be called directly in any section of javascript code. The call of this method is only allowed inside the «onLocationChange» callback , which will be described hereinafter.

Callbacks of the child browser

onClose()
- Called at the time when the child browser receives the closing signal.
onLocationChange(location)
- Called on every time the address of a web document of a child browser is changed. Perhaps the above description will be updated in later versions of ChildBrowser plug-in, but for writing this article was used the information about the plug-in that is compatible with Phonegap 1.2.0 - 1.4.0.

Installing and using the plug-in childBrowser

Well, now let's begin to implement a simple but meaningful example of the plug-in childBrowser. So, download the source code of the plugin. As always it has two parts: javascript and native wrapper. Throw the native wrapper in the project - it will be compiled and included in the application as an ordinary class. Javascript wrapper throws in resources or asset, connect application in a html document. Furthermore, before using the plug-in at run-time it is to be installed first. Installing the plug-in is optional for the operation of all mobile platforms, but, for example, for IOS it is a requirement. This is done in javascript event handler «deviceready», and here we go, everything is ready for usage:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
    <head>
        <meta name="viewport" content="width=default-width; user-scalable=no" />
        <meta http-equiv="Content-type" content="text/html; charset=utf-8">
            <link rel="stylesheet" href="phonegap.css" type="text/css"/>
            <title>Childbrowser Gap</title>         
            <script type="text/javascript" charset="utf-8" src="phonegap-1.2.0.js"></script>
            <script type="text/javascript" charset="utf-8" src="ChildBrowser.js"></script>
            <script type="text/javascript" charset="utf-8">
                function onDocumentReady() {
                     if (document.addEventListener) {
                         document.addEventListener('deviceready',                               onDeviceReady, false);
                     } else {
                         document.attachEvent('deviceready', onDeviceReady, false);
                     }
                }
                function onChangeBrowserLocation(location) {
                     if (location.indexOf('maps.google.com') != -1) {
                         window.plugins.childBrowser.close();
                     }
                }
                function onBrowserClose() {
                     alert('child window closed');
                }
                function onDeviceReady() {
                     //для некоторых платформ данный метод не определен.
                     if (ChildBrowser.install) {
                         ChildBrowser.install();
                     }
                     window.plugins.childBrowser.onLocationChange = onChangeBrowserLocation;
                     window.plugins.childBrowser.onClose = onBrowserClose;
                }
                function openChildBrowser(url) {
                     try {
                         window.plugins.childBrowser.showWebPage(url);
                     } catch (err) {
                         alert(err);
                     }
                }
                function openExternalBrowser(url) {
                     try {
                         window.plugins.childBrowser.openExternal(url);
                     } catch (err) {
                         alert(err);
                     }
                }
                </script>
            </head>
            <body onload="onDocumentReady()">
                <button onclick="openChildBrowser('http://www.google.com');">Open Google in child window</button> 
                <button onclick="openExternalBrowser('http://www.google.com');">Open Google in default browser</button> 
    </body>
</html>
This example shows opening the page of Google search by clicking on «Open Google in child browser». In the transition inside the child browser to Google Maps the child window should close and display a message «child window closed». In real applications, on the PhoneGap this plug-in is simply irreplaceable. And fortunately, it works well with all mobile platforms, even with Windows Phone 7 (it's very few plug-ins are re-written for this platform so far). For example, in my applications, plug-in is used to authenticate to the Facebook pop-up window. If you say: "Why is that? There is a special plug-in Facebook Auth Dialog?», I answer: «It supports only IOS and Android, and besides, it's only for Facebook ... And if you want to do authentication, for example, Vkontakte?» This plugin is really cool and irreplaceable. In general, go for it!
Article comments
Comments:
Aleksandr
13\05\2012
Спасибо! Данный плагин будет играть важную роль в моём приложении.
Only logged users can leave comments.