Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: callback-dev@cordova.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: shazron@apache.org
To: commits@cordova.apache.org
Subject: docs commit: [CB-1952] Document InAppBrowser events,
 InAppBrowser API and options
Message-Id: <20121212061415.E307981B5B7@tyr.zones.apache.org>
Date: Wed, 12 Dec 2012 06:14:15 +0000 (UTC)

Updated Branches:
  refs/heads/master 7f8859926 -> b31ddb2df


[CB-1952] Document InAppBrowser events, InAppBrowser API and options


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/b31ddb2d
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/b31ddb2d
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/b31ddb2d

Branch: refs/heads/master
Commit: b31ddb2df46612192989323a41acd98113d72b98
Parents: 7f88599
Author: Shazron Abdullah <shazron@apache.org>
Authored: Tue Dec 11 22:14:07 2012 -0800
Committer: Shazron Abdullah <shazron@apache.org>
Committed: Tue Dec 11 22:14:07 2012 -0800

----------------------------------------------------------------------
 docs/en/edge/config.json                          |    5 +
 docs/en/edge/cordova/inappbrowser/inappbrowser.md |  254 ++++++++++++++++
 docs/en/edge/cordova/inappbrowser/window.open.md  |   82 +++++
 docs/en/edge/index.md                             |    4 +
 4 files changed, 345 insertions(+), 0 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b31ddb2d/docs/en/edge/config.json
----------------------------------------------------------------------
diff --git a/docs/en/edge/config.json b/docs/en/edge/config.json
index 4583fce..8498cef 100644
--- a/docs/en/edge/config.json
+++ b/docs/en/edge/config.json
@@ -187,6 +187,11 @@
             "cordova/storage/sqlresultsetlist/sqlresultsetlist.md",
             "cordova/storage/sqlerror/sqlerror.md",
             "cordova/storage/localstorage/localstorage.md"
+        ],
+        "inappbrowser.md": [
+            "cordova/inappbrowser/inappbrowser.md",
+            "cordova/inappbrowser/window.open.md"
         ]
+        
     }
 }

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b31ddb2d/docs/en/edge/cordova/inappbrowser/inappbrowser.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/cordova/inappbrowser/inappbrowser.md b/docs/en/edge/cordova/inappbrowser/inappbrowser.md
new file mode 100644
index 0000000..a66beef
--- /dev/null
+++ b/docs/en/edge/cordova/inappbrowser/inappbrowser.md
@@ -0,0 +1,254 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+         or more contributor license agreements.  See the NOTICE file
+         distributed with this work for additional information
+         regarding copyright ownership.  The ASF licenses this file
+         to you under the Apache License, Version 2.0 (the
+         "License"); you may not use this file except in compliance
+         with the License.  You may obtain a copy of the License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+         Unless required by applicable law or agreed to in writing,
+         software distributed under the License is distributed on an
+         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+         KIND, either express or implied.  See the License for the
+         specific language governing permissions and limitations
+         under the License.
+---
+
+InAppBrowser
+============
+
+> The InAppBrowser is a web-browser that is shown in your app when you use the `window.open` call.
+
+    var ref = window.open('http://apache.org', '_blank', 'location=yes');
+    
+Description
+-----------
+
+The object returned from a call to `window.open`.
+
+Methods
+----------
+
+- addEventListener
+- removeEventListener
+- close
+
+Permissions
+-----------
+
+### Android
+
+#### app/res/xml/config.xml
+
+    <plugin name="InAppBrowser" value="org.apache.cordova.InAppBrowser" />
+
+### iOS
+
+#### config.xml
+
+    <plugin name="InAppBrowser" value="CDVInAppBrowser" />
+
+
+addEventListener
+================
+
+> Adds a listener for an event from the InAppBrowser.
+
+    ref.addEventListener(eventname, callback);
+
+- __ref:__ reference to the InAppBrowser window (`InAppBrowser`)
+- __eventname:__ the event to listen for (`String`)
+
+        loadstart - event fired when the InAppBrowser starts to load a URL 
+        loadstop - event fired when the InAppBrowser finished loading a URL
+        exit - event fired when the InAppBrowser window is closed 
+
+- __callback:__ the function that is called when the event is fired. 
+The function is passed an `InAppBrowserEvent` object.
+
+Supported Platforms
+-------------------
+
+- Android
+- iOS
+
+Quick Example
+-------------
+
+    var ref = window.open('http://apache.org', '_blank', 'location=yes');
+    ref.addEventListener('loadstart', function() { alert(event.url); });
+
+Full Example
+------------
+
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>InAppBrowser.addEventListener Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.3.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+             var ref = window.open('http://apache.org', '_blank', 'location=yes');
+             ref.addEventListener('loadstart', function() { alert('start: ' + event.url); });
+             ref.addEventListener('loadstop', function() { alert('stop: ' + event.url); });
+             ref.addEventListener('exit', function() { alert(event.type); });
+        }
+
+        </script>
+      </head>
+      <body>
+      </body>
+    </html>
+
+removeEventListener
+===================
+
+> Removes a listener for an event from the InAppBrowser.
+
+    ref.removeEventListener(eventname, callback);
+
+- __ref:__ reference to the InAppBrowser window (`InAppBrowser`)
+- __eventname:__ the event to stop listening for (`String`)
+
+        loadstart - event fired when the InAppBrowser starts to load a URL 
+        loadstop - event fired when the InAppBrowser finished loading a URL
+        exit - event fired when the InAppBrowser window is closed 
+
+- __callback:__ the function that was to be called when the event is fired. 
+The function is passed an `InAppBrowserEvent` object.
+
+Supported Platforms
+-------------------
+
+- Android
+- iOS
+
+Quick Example
+-------------
+
+    var ref = window.open('http://apache.org', '_blank', 'location=yes');
+    var myCallback = function() { alert(event.url); }
+    ref.addEventListener('loadstart', myCallback);
+    ref.removeEventListener('loadstart', myCallback);
+
+Full Example
+------------
+
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>InAppBrowser.removeEventListener Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.3.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+        
+        // Global InAppBrowser reference
+        var iabRef = null;
+        
+        function iabLoadStart(event) {
+            alert(event.type + ' - ' + event.url);
+        }
+
+        function iabLoadStop(event) {
+            alert(event.type + ' - ' + event.url);
+        }
+   
+        function iabClose(event) {
+             alert(event.type);
+             iabRef.removeEventListener('loadstart', iabLoadStart);
+             iabRef.removeEventListener('loadstop', iabLoadStop);
+             iabRef.removeEventListener('exit', iabClose);
+        }
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+             iabRef = window.open('http://apache.org', '_blank', 'location=yes');
+             iabRef.addEventListener('loadstart', iabLoadStart);
+             iabRef.addEventListener('loadstop', iabLoadStop);
+             iabRef.addEventListener('exit', iabClose);
+        }
+
+        </script>
+      </head>
+      <body>
+      </body>
+    </html>
+
+close
+=====
+
+> Closes the InAppBrowser window.
+
+    ref.close();
+
+- __ref:__ reference to the InAppBrowser window (`InAppBrowser`)
+
+Supported Platforms
+-------------------
+
+- Android
+- iOS
+
+Quick Example
+-------------
+
+    var ref = window.open('http://apache.org', '_blank', 'location=yes');
+    ref.close();
+
+Full Example
+------------
+
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>InAppBrowser.close Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.3.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+             var ref = window.open('http://apache.org', '_blank', 'location=yes');
+             // close InAppBrowser after 5 seconds
+             setTimeout(function() {
+                 ref.close();
+             }, 5000);
+        }
+
+        </script>
+      </head>
+      <body>
+      </body>
+    </html>
+
+InAppBrowserEvent
+=================
+
+The object that is passed to the callback function from an addEventListener call on an InAppBrowser object.
+
+Properties
+----------
+
+- __type:__ the eventname (`String`) - one of loadstart, loadstop, or exit
+- __url:__ the URL that was loaded (`String`)

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b31ddb2d/docs/en/edge/cordova/inappbrowser/window.open.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/cordova/inappbrowser/window.open.md b/docs/en/edge/cordova/inappbrowser/window.open.md
new file mode 100644
index 0000000..fe36860
--- /dev/null
+++ b/docs/en/edge/cordova/inappbrowser/window.open.md
@@ -0,0 +1,82 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+         or more contributor license agreements.  See the NOTICE file
+         distributed with this work for additional information
+         regarding copyright ownership.  The ASF licenses this file
+         to you under the Apache License, Version 2.0 (the
+         "License"); you may not use this file except in compliance
+         with the License.  You may obtain a copy of the License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+         Unless required by applicable law or agreed to in writing,
+         software distributed under the License is distributed on an
+         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+         KIND, either express or implied.  See the License for the
+         specific language governing permissions and limitations
+         under the License.
+---
+
+window.open
+===========
+
+Opens a URL in a new InAppBrowser instance, the current browser instance, or the system browser.
+
+    var ref = window.open(url, target, options);
+    
+- __ref:__ reference to the InAppBrowser window (`InAppBrowser`)
+- __url:__ the URL to load (`String`)
+- __target:__ the target to load the URL in (`String`) (Optional, Default: "_self")
+
+        _self - opens in the Cordova WebView if url is in the white-list, else it opens in the InAppBrowser 
+        _blank - always open in the InAppBrowser 
+        _system - always open in the system web browser 
+    
+    
+- __options:__ options for the InAppBrowser (`String`) (Optional, Default: "location=yes")
+    
+    The options string must not contain any blank space, each feature name and value must be separated by a comma. Only the value below is supported:
+
+            location - set to 'yes' or 'no' to turn the location bar on or off for the InAppBrowser
+            
+Supported Platforms
+-------------------
+
+- Android
+- iOS
+
+Quick Example
+-------------
+
+    var ref = window.open('http://apache.org', '_blank', 'location=yes');
+
+Full Example
+------------
+
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>window.open Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.3.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+            // external url
+            var ref = window.open('http://apache.org', '_blank', 'location=yes');
+            // relative document
+            ref = window.open('next.html', '_self');
+        }
+
+        </script>
+      </head>
+      <body>
+      </body>
+    </html>
+

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b31ddb2d/docs/en/edge/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/index.md b/docs/en/edge/index.md
index 1bdaa72..fc08a23 100644
--- a/docs/en/edge/index.md
+++ b/docs/en/edge/index.md
@@ -65,6 +65,10 @@ license: Licensed to the Apache Software Foundation (ASF) under one
             <span>Enable representation of objects specific to a locale.</span>
         </li>
         <li>
+            <h2>InAppBrowser</h2>
+            <span>Launch URLs in another in-app browser instance.</span>
+        </li>
+        <li>
             <h2>Media</h2>
             <span>Record and play back audio files.</span>
         </li>