You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by st...@apache.org on 2012/03/03 01:29:09 UTC
[2/5] updated to 1.5.0
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/compass/compass.watchHeadingFilter.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/compass/compass.watchHeadingFilter.md b/docs/en/1.5.0/phonegap/compass/compass.watchHeadingFilter.md
new file mode 100644
index 0000000..28f8394
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/compass/compass.watchHeadingFilter.md
@@ -0,0 +1,103 @@
+compass.watchHeadingFilter
+==========================
+
+Get the compass heading in degrees when it changes by at least a certain number of degrees.
+
+ var watchID = navigator.compass.watchHeadingFilter(compassSuccess, compassError, compassOptions);
+
+Description
+-----------
+
+The compass is a sensor that detects the direction or heading that the device is pointed. It measures the heading in degrees from 0 to 359.99.
+
+The `compass.watchHeadingFilter` gets the device's current heading when it changes by a specified number of degrees. Each time the heading changes by the specified number of degrees or more, the `headingSuccess` callback function is called. Specify the degrees of change via the `filter` parameter in the `compassOptions` object.
+
+The returned watch ID references references the compass watch interval. The watch ID can be used with `compass.clearWatchFilter` to stop watching the compass via a degree filter. Only one watchHeadingFilter can be in effect at one time. If a watchHeadingFilter is in effect, calling getCurrentHeading or watchHeading will use the existing filter value for specifying heading changes. On iOS this method is more efficient than compass.watchFilter() based on the iOS mechanism for monitoring compass heading changes.
+
+Supported Platforms
+-------------------
+
+- iPhone
+
+
+Quick Example
+-------------
+
+ function onSuccess(heading) {
+ var element = document.getElementById('heading');
+ element.innerHTML = 'Heading: ' + heading.magneticHeading;
+ };
+
+ function onError(compassError) {
+ alert('Compass error: ' + compassError.code);
+ };
+
+ var options = { filter: 10 }; // Get notified on compass heading changes or 10 degrees or more
+
+ var watchID = navigator.compass.watchHeadingFilter(onSuccess, onError, options);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Compass Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // The watch id references the current `watchHeading`
+ var watchID = null;
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ startWatch();
+ }
+
+ // Start watching the compass
+ //
+ function startWatch() {
+
+ // Get notified on compass heading changes or 10 degrees or more
+ var options = { filter: 10 };
+
+ watchID = navigator.compass.watchHeadingFilter(onSuccess, onError, options);
+ }
+
+ // Stop watching the compass
+ //
+ function stopWatch() {
+ if (watchID) {
+ navigator.compass.clearWatchFilter(watchID);
+ watchID = null;
+ }
+ }
+
+ // onSuccess: Get the current heading
+ //
+ function onSuccess(heading) {
+ var element = document.getElementById('heading');
+ element.innerHTML = 'Heading: ' + heading.magneticHeading;
+ }
+
+ // onError: Failed to get the heading
+ //
+ function onError(compassError) {
+ alert('Compass error: ' + compassError.code);
+ }
+
+ </script>
+ </head>
+ <body>
+ <div id="heading">Waiting for heading...</div>
+ <button onclick="startWatch();">Start Watching via Filter</button>
+ <button onclick="stopWatch();">Stop Watching</button>
+ </body>
+ </html>
+
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/compass/compassError/compassError.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/compass/compassError/compassError.md b/docs/en/1.5.0/phonegap/compass/compassError/compassError.md
new file mode 100644
index 0000000..2e1a24d
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/compass/compassError/compassError.md
@@ -0,0 +1,21 @@
+CompassError
+==========
+
+A `CompassError` object is returned to the `compassError` callback function when an error occurs.
+
+Properties
+----------
+
+- __code:__ One of the predefined error codes listed below.
+
+Constants
+---------
+- `CompassError.COMPASS_INTERNAL_ERR`
+- `CompassError.COMPASS_NOT_SUPPORTED`
+
+Description
+-----------
+
+The `CompassError` object is returned to the user through the `compassError` callback function when an error occurs.
+
+
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/compass/parameters/compassError.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/compass/parameters/compassError.md b/docs/en/1.5.0/phonegap/compass/parameters/compassError.md
new file mode 100755
index 0000000..c150f29
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/compass/parameters/compassError.md
@@ -0,0 +1,11 @@
+compassError
+==========
+
+onError callback function for compass functions.
+
+Example
+-------
+
+function(CompassError) {
+ // Handle the error
+}
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/compass/parameters/compassHeading.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/compass/parameters/compassHeading.md b/docs/en/1.5.0/phonegap/compass/parameters/compassHeading.md
new file mode 100644
index 0000000..4557e57
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/compass/parameters/compassHeading.md
@@ -0,0 +1,33 @@
+compassHeading
+==========
+
+A `CompassHeading` object is returned to the `compassSuccess` callback function when an error occurs.
+
+Properties
+----------
+- __magneticHeading:__ The heading in degrees from 0 - 359.99 at a single moment in time. _(Number)_
+- __trueHeading:__ The heading relative to the geographic North Pole in degrees 0 - 359.99 at a single moment in time. A negative value indicates that the true heading could not be determined. _(Number)_
+- __headingAccuracy:__ The deviation in degrees between the reported heading and the true heading. _(Number)_
+- __timestamp:__ The time at which this heading was determined. _(milliseconds)_
+
+Description
+-----------
+
+The `CompassHeading` object is returned to the user through the `compassSuccess` callback function.
+
+Android Quirks
+--------------
+- trueHeading is not supported. It will report the same value as magneticHeading
+- headingAccuracy will always be 0 as there is no difference between the magneticHeading and trueHeading on Android.
+
+iOS Quirks
+----------
+
+- trueHeading is only returned when location services are running via `navigator.geolocation.watchLocation()`
+- For iOS > 4 devices, if the device is rotated and the app supports that orientation, the heading values will be reported
+back with respect to the current orientation.
+
+Windows Phone 7 Quirks
+-------------
+
+- returns trueHeading only, note that this code is largely untested because of a lack of devices that support compass.
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/compass/parameters/compassOptions.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/compass/parameters/compassOptions.md b/docs/en/1.5.0/phonegap/compass/parameters/compassOptions.md
new file mode 100755
index 0000000..38e8bda
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/compass/parameters/compassOptions.md
@@ -0,0 +1,19 @@
+compassOptions
+==============
+
+An optional parameter to customize the retrieval of the compass.
+
+Options
+-------
+
+- __frequency:__ How often to retrieve the compass heading in milliseconds. _(Number)_ (Default: 100)
+- __filter:__ The change in degrees required to initiate a watchHeadingFilter success callback. _(Number)_
+
+Android Quirks
+______________
+- filter is not supported.
+
+Windows Phone 7 Quirks
+--------------
+
+- filter is not supported.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/compass/parameters/compassSuccess.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/compass/parameters/compassSuccess.md b/docs/en/1.5.0/phonegap/compass/parameters/compassSuccess.md
new file mode 100644
index 0000000..9e12a64
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/compass/parameters/compassSuccess.md
@@ -0,0 +1,21 @@
+compassSuccess
+==============
+
+onSuccess callback function that provides the compass heading information via a compassHeading object.
+
+ function(heading) {
+ // Do something
+ }
+
+Parameters
+----------
+
+
+- __heading:__ The heading information. _(compassHeading)_
+
+Example
+-------
+
+ function onSuccess(heading) {
+ alert('Heading: ' + heading.magneticHeading);
+ };
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/connection/connection.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/connection/connection.md b/docs/en/1.5.0/phonegap/connection/connection.md
new file mode 100644
index 0000000..1702e96
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/connection/connection.md
@@ -0,0 +1,23 @@
+Connection
+==========
+
+> The `connection` object gives access to the device's cellular and wifi connection information.
+
+This object is accessed under the navigator.network interface.
+
+Properties
+----------
+
+- connection.type
+
+Constants
+---------
+
+- Connection.UNKNOWN
+- Connection.ETHERNET
+- Connection.WIFI
+- Connection.CELL_2G
+- Connection.CELL_3G
+- Connection.CELL_4G
+- Connection.NONE
+
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/connection/connection.type.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/connection/connection.type.md b/docs/en/1.5.0/phonegap/connection/connection.type.md
new file mode 100644
index 0000000..d934050
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/connection/connection.type.md
@@ -0,0 +1,82 @@
+connection.type
+===================
+
+Checks the active network connection that is being used.
+
+Description
+-----------
+
+This property is a fast way to determine the device's network connection state, and type of connection.
+
+
+Supported Platforms
+-------------------
+
+- iOS
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- Windows Phone 7 ( Mango )
+
+Quick Example
+-------------
+
+ function checkConnection() {
+ var networkState = navigator.network.connection.type;
+
+ var states = {};
+ states[Connection.UNKNOWN] = 'Unknown connection';
+ states[Connection.ETHERNET] = 'Ethernet connection';
+ states[Connection.WIFI] = 'WiFi connection';
+ states[Connection.CELL_2G] = 'Cell 2G connection';
+ states[Connection.CELL_3G] = 'Cell 3G connection';
+ states[Connection.CELL_4G] = 'Cell 4G connection';
+ states[Connection.NONE] = 'No network connection';
+
+ alert('Connection type: ' + states[networkState]);
+ }
+
+ checkConnection();
+
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>navigator.network.connection.type Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
+ //
+ function onDeviceReady() {
+ checkConnection();
+ }
+
+ function checkConnection() {
+ var networkState = navigator.network.connection.type;
+
+ var states = {};
+ states[Connection.UNKNOWN] = 'Unknown connection';
+ states[Connection.ETHERNET] = 'Ethernet connection';
+ states[Connection.WIFI] = 'WiFi connection';
+ states[Connection.CELL_2G] = 'Cell 2G connection';
+ states[Connection.CELL_3G] = 'Cell 3G connection';
+ states[Connection.CELL_4G] = 'Cell 4G connection';
+ states[Connection.NONE] = 'No network connection';
+
+ alert('Connection type: ' + states[networkState]);
+ }
+
+ </script>
+ </head>
+ <body>
+ <p>A dialog box will report the network state.</p>
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/Contact/contact.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/Contact/contact.md b/docs/en/1.5.0/phonegap/contacts/Contact/contact.md
new file mode 100644
index 0000000..52f2e93
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/Contact/contact.md
@@ -0,0 +1,202 @@
+Contact
+=======
+
+Contains properties that describe a contact, such as a user's personal or business contact.
+
+Properties
+----------
+
+- __id:__ A globally unique identifier. _(DOMString)_
+- __displayName:__ The name of this Contact, suitable for display to end-users. _(DOMString)_
+- __name:__ An object containing all components of a persons name. _(ContactName)_
+- __nickname:__ A casual name to address the contact by. _(DOMString)_
+- __phoneNumbers:__ An array of all the contact's phone numbers. _(ContactField[])_
+- __emails:__ An array of all the contact's email addresses. _(ContactField[])_
+- __addresses:__ An array of all the contact's addresses. _(ContactAddresses[])_
+- __ims:__ An array of all the contact's IM addresses. _(ContactField[])_
+- __organizations:__ An array of all the contact's organizations. _(ContactOrganization[])_
+- __birthday:__ The birthday of the contact. _(Date)_
+- __note:__ A note about the contact. _(DOMString)_
+- __photos:__ An array of the contact's photos. _(ContactField[])_
+- __categories:__ An array of all the contacts user defined categories. _(ContactField[])_
+- __urls:__ An array of web pages associated to the contact. _(ContactField[])_
+
+Methods
+-------
+
+- __clone__: Returns a new Contact object that is a deep copy of the calling object, with the id property set to `null`.
+- __remove__: Removes the contact from the device contacts database. An error callback is called with a `ContactError` object if the removal is unsuccessful.
+- __save__: Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same __id__ already exists.
+
+
+Details
+-------
+
+The `Contact` object represents a user contact. Contacts can be created, saved to, or removed from the device contacts database. Contacts can also be retrieved (individually or in bulk) from the database by invoking the `contacts.find` method.
+
+_Note: Not all of the above contact fields are supported on every device platform. Please check each platform's Quirks section for information about which fields are supported._
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Save Quick Example
+------------------
+
+ function onSuccess(contact) {
+ alert("Save Success");
+ };
+
+ function onError(contactError) {
+ alert("Error = " + contactError.code);
+ };
+
+ // create a new contact object
+ var contact = navigator.contacts.create();
+ contact.displayName = "Plumber";
+ contact.nickname = "Plumber"; //specify both to support all devices
+
+ // populate some fields
+ var name = new ContactName();
+ name.givenName = "Jane";
+ name.familyName = "Doe";
+ contact.name = name;
+
+ // save to device
+ contact.save(onSuccess,onError);
+
+Clone Quick Example
+-------------------
+
+ // clone the contact object
+ var clone = contact.clone();
+ clone.name.givenName = "John";
+ console.log("Original contact name = " + contact.name.givenName);
+ console.log("Cloned contact name = " + clone.name.givenName);
+
+Remove Quick Example
+--------------------
+
+ function onSuccess() {
+ alert("Removal Success");
+ };
+
+ function onError(contactError) {
+ alert("Error = " + contactError.code);
+ };
+
+ // remove the contact from the device
+ contact.remove(onSuccess,onError);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Contact Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ // create
+ var contact = navigator.contacts.create();
+ contact.displayName = "Plumber";
+ contact.nickname = "Plumber"; //specify both to support all devices
+ var name = new ContactName();
+ name.givenName = "Jane";
+ name.familyName = "Doe";
+ contact.name = name;
+
+ // save
+ contact.save(onSaveSuccess,onSaveError);
+
+ // clone
+ var clone = contact.clone();
+ clone.name.givenName = "John";
+ console.log("Original contact name = " + contact.name.givenName);
+ console.log("Cloned contact name = " + clone.name.givenName);
+
+ // remove
+ contact.remove(onRemoveSuccess,onRemoveError);
+ }
+
+ // onSaveSuccess: Get a snapshot of the current contacts
+ //
+ function onSaveSuccess(contact) {
+ alert("Save Success");
+ }
+
+ // onSaveError: Failed to get the contacts
+ //
+ function onSaveError(contactError) {
+ alert("Error = " + contactError.code);
+ }
+
+ // onRemoveSuccess: Get a snapshot of the current contacts
+ //
+ function onRemoveSuccess(contacts) {
+ alert("Removal Success");
+ }
+
+ // onRemoveError: Failed to get the contacts
+ //
+ function onRemoveError(contactError) {
+ alert("Error = " + contactError.code);
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Find Contacts</p>
+ </body>
+ </html>
+
+Android 2.X Quirks
+------------------
+
+- __categories:__ This property is not support by Android 2.X devices, and will always be returned as `null`.
+
+Android 1.X Quirks
+------------------
+
+- __name:__ This property is not support by Android 1.X devices, and will always be returned as `null`.
+- __nickname:__ This property is not support by Android 1.X devices, and will always be returned as `null`.
+- __birthday:__ This property is not support by Android 1.X devices, and will always be returned as `null`.
+- __photos:__ This property is not support by Android 1.X devices, and will always be returned as `null`.
+- __categories:__ This property is not support by Android 1.X devices, and will always be returned as `null`.
+- __urls:__ This property is not support by Android 1.X devices, and will always be returned as `null`.
+
+
+BlackBerry WebWorks (OS 5.0 and higher) Quirks
+---------------------------------------------
+
+- __id:__ Supported. Assigned by device when contact is saved.
+- __displayName:__ Supported. Stored in BlackBerry __user1__ field.
+- __nickname:__ This property is not supported, and will always be returned as `null`.
+- __phoneNumbers:__ Partially supported. Phone numbers will be stored in BlackBerry fields __homePhone1__ and __homePhone2__ if _type_ is 'home', __workPhone1__ and __workPhone2__ if _type_ is 'work', __mobilePhone__ if _type_ is 'mobile', __faxPhone__ if _type_ is 'fax', __pagerPhone__ if _type_ is 'pager', and __otherPhone__ if _type_ is none of the above.
+- __emails:__ Partially supported. The first three email addresses will be stored in the BlackBerry __email1__, __email2__, and __email3__ fields, respectively.
+- __addresses:__ Partially supported. The first and second addresses will be stored in the BlackBerry __homeAddress__ and __workAddress__ fields, respectively.
+- __ims:__ This property is not supported, and will always be returned as `null`.
+- __organizations:__ Partially supported. The __name__ and __title__ of the first organization are stored in the BlackBerry __company__ and __title__ fields, respectively.
+- __photos:__ - Partially supported. A single thumbnail-sized photo is supported. To set a contact's photo, pass in a either a Base64 encoded image, or a URL pointing to the image. The image will be scaled down before saving to the BlackBerry contacts database. The contact photo is returned as a Base64 encoded image.
+- __categories:__ Partially supported. Only 'Business' and 'Personal' categories are supported.
+- __urls:__ Partially supported. The first url is stored in BlackBerry __webpage__ field.
+
+iOS Quirks
+----------
+- __displayName:__ This property is not supported by iOS and will be returned as `null` unless there is no ContactName specified. If there is no ContactName, then composite name, __nickame__ or "" is returned for __displayName__, respectively.
+- __birthday:__ For input, this property must be provided as a JavaScript Date object. It is returned as a JavaScript Date object.
+- __photos:__ Returned Photo is stored in the application's temporary directory and a File URL to photo is returned. Contents of temporary folder is deleted when application exits.
+- __categories:__ This property is not currently supported and will always be returned as `null`.
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/ContactAddress/contactaddress.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/ContactAddress/contactaddress.md b/docs/en/1.5.0/phonegap/contacts/ContactAddress/contactaddress.md
new file mode 100644
index 0000000..c84c15a
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/ContactAddress/contactaddress.md
@@ -0,0 +1,145 @@
+ContactAddress
+==============
+
+Contains address properties for a `Contact` object.
+
+Properties
+----------
+- __pref:__ Set to `true` if this `ContactAddress` contains the user's preferred value. _(boolean)_
+- __type:__ A string that tells you what type of field this is (example: 'home'). _(DOMString)
+- __formatted:__ The full address formatted for display. _(DOMString)_
+- __streetAddress:__ The full street address. _(DOMString)_
+- __locality:__ The city or locality. _(DOMString)_
+- __region:__ The state or region. _(DOMString)_
+- __postalCode:__ The zip code or postal code. _(DOMString)_
+- __country:__ The country name. _(DOMString)_
+
+Details
+-------
+
+The `ContactAddress` object stores the properties of a single address of a contact. A `Contact` object can have one or more addresses in a `ContactAddress[]` array.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Quick Example
+-------------
+
+ // display the address information for all contacts
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ for (var j=0; j<contacts[i].addresses.length; j++) {
+ alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
+ "Type: " + contacts[i].addresses[j].type + "\n" +
+ "Formatted: " + contacts[i].addresses[j].formatted + "\n" +
+ "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
+ "Locality: " + contacts[i].addresses[j].locality + "\n" +
+ "Region: " + contacts[i].addresses[j].region + "\n" +
+ "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
+ "Country: " + contacts[i].addresses[j].country);
+ }
+ }
+ };
+
+ function onError(contactError) {
+ alert('onError!');
+ };
+
+ // find all contacts
+ var options = new ContactFindOptions();
+ options.filter="";
+ var filter = ["displayName","addresses"];
+ navigator.contacts.find(filter, onSuccess, onError, options);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Contact Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ // find all contacts
+ var options = new ContactFindOptions();
+ options.filter="";
+ var filter = ["displayName","addresses"];
+ navigator.contacts.find(filter, onSuccess, onError, options);
+ }
+
+ // onSuccess: Get a snapshot of the current contacts
+ //
+ function onSuccess(contacts) {
+ // display the address information for all contacts
+ for (var i=0; i<contacts.length; i++) {
+ for (var j=0; j<contacts[i].addresses.length; j++) {
+ alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
+ "Type: " + contacts[i].addresses[j].type + "\n" +
+ "Formatted: " + contacts[i].addresses[j].formatted + "\n" +
+ "Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
+ "Locality: " + contacts[i].addresses[j].locality + "\n" +
+ "Region: " + contacts[i].addresses[j].region + "\n" +
+ "Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
+ "Country: " + contacts[i].addresses[j].country);
+ }
+ }
+ };
+
+ // onError: Failed to get the contacts
+ //
+ function onError(contactError) {
+ alert('onError!');
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Find Contacts</p>
+ </body>
+ </html>
+
+Android 2.X Quirks
+------------------
+
+- __pref:__ This property is not supported by Android 2.X devices and will always return `false`.
+
+Android 1.X Quirks
+------------------
+
+- __pref:__ This property is not supported by Android 1.X devices and will always return `false`.
+- __type:__ This property is not supported by Android 1.X devices and will always return `null`.
+- __streetAddress:__ This property is not support by Android 1.X devices, and will always return `null`.
+- __locality:__ This property is not support by Android 1.X devices, and will always return `null`.
+- __region:__ This property is not support by Android 1.X devices, and will always return `null`.
+- __postalCode:__ This property is not support by Android 1.X devices, and will always return `null`.
+- __country:__ This property is not support by Android 1.X devices, and will always return `null`.
+
+BlackBerry WebWorks (OS 5.0 and higher) Quirks
+--------------------------------------------
+- __pref:__ This property is not supported on Blackberry devices and will always return `false`.
+- __type:__ Partially supported. Only one each of "Work" and "Home" type addresses can be stored per contact.
+- __formatted:__ Partially supported. Will return concatenation of all BlackBerry address fields.
+- __streetAddress:__ Supported. Will return concatenation of BlackBerry __address1__ and __address2__ address fields.
+- __locality:__ Supported. Stored in BlackBerry __city__ address field.
+- __region:__ Supported. Stored in BlackBerry __stateProvince__ address field.
+- __postalCode:__ Supported. Stored in BlackBerry __zipPostal__ address field.
+- __country:__ Supported.
+
+iOS Quirks
+----------
+- __pref:__ This property is not supported on iOS devices and will always return `false`.
+- __formatted:__ Not currently supported.
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/ContactError/contactError.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/ContactError/contactError.md b/docs/en/1.5.0/phonegap/contacts/ContactError/contactError.md
new file mode 100644
index 0000000..62bd9fe
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/ContactError/contactError.md
@@ -0,0 +1,26 @@
+ContactError
+========
+
+A `ContactError` object is returned to the `contactError` callback when an error occurs.
+
+Properties
+----------
+
+- __code:__ One of the predefined error codes listed below.
+
+Constants
+---------
+
+- `ContactError.UNKNOWN_ERROR`
+- `ContactError.INVALID_ARGUMENT_ERROR`
+- `ContactError.TIMEOUT_ERROR`
+- `ContactError.PENDING_OPERATION_ERROR`
+- `ContactError.IO_ERROR`
+- `ContactError.NOT_SUPPORTED_ERROR`
+- `ContactError.PERMISSION_DENIED_ERROR`
+
+Description
+-----------
+
+The `ContactError` object is returned to the user through the `contactError` callback function when an error occurs.
+
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/ContactField/contactfield.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/ContactField/contactfield.md b/docs/en/1.5.0/phonegap/contacts/ContactField/contactfield.md
new file mode 100644
index 0000000..8eb0a8b
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/ContactField/contactfield.md
@@ -0,0 +1,122 @@
+ContactField
+============
+
+Supports generic fields in a `Contact` object. Some properties that are stored as `ContactField` objects include email addresses, phone numbers, and urls.
+
+Properties
+----------
+
+- __type:__ A string that tells you what type of field this is (example: 'home'). _(DOMString)_
+- __value:__ The value of the field (such as a phone number or email address). _(DOMString)_
+- __pref:__ Set to `true` if this `ContactField` contains the user's preferred value. _(boolean)_
+
+Details
+-------
+
+The `ContactField` object is a reusable component that is used to support contact fields in a generic fashion. Each `ContactField` object contains a value property, a type property, and a pref property. A `Contact` object stores several properties in `ContactField[]` arrays, such as phone numbers and email addresses.
+
+In most instances, there are no pre-determined values for the __type__ attribute of a `ContactField` object. For example, a phone number can have __type__ values of 'home', 'work', 'mobile', 'iPhone', or any other value that is supported by the contact database on a particular device platform. However, in the case of the `Contact` __photos__ field, PhoneGap makes use of the __type__ field to indicate the format of the returned image. PhoneGap will return __type: 'url'__ when the __value__ attribute contains a URL to the photo image, or __type: 'base64'__ when the returned __value__ attribute contains a Base64 encoded image string.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Quick Example
+-------------
+
+ // create a new contact
+ var contact = navigator.contacts.create();
+
+ // store contact phone numbers in ContactField[]
+ var phoneNumbers = [3];
+ phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
+ phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
+ phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
+ contact.phoneNumbers = phoneNumbers;
+
+ // save the contact
+ contact.save();
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Contact Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ // create a new contact
+ var contact = navigator.contacts.create();
+
+ // store contact phone numbers in ContactField[]
+ var phoneNumbers = [3];
+ phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
+ phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
+ phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
+ contact.phoneNumbers = phoneNumbers;
+
+ // save the contact
+ contact.save();
+
+ // search contacts, returning display name and phone numbers
+ var options = new ContactFindOptions();
+ options.filter="";
+ filter = ["displayName","phoneNumbers"];
+ navigator.contacts.find(filter, onSuccess, onError, options);
+ }
+
+ // onSuccess: Get a snapshot of the current contacts
+ //
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ // display phone numbers
+ for (var j=0; j<contacts[i].phoneNumbers.length; j++) {
+ alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" +
+ "Value: " + contacts[i].phoneNumbers[j].value + "\n" +
+ "Preferred: " + contacts[i].phoneNumbers[j].pref);
+ }
+ }
+ };
+
+ // onError: Failed to get the contacts
+ //
+ function onError(contactError) {
+ alert('onError!');
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Find Contacts</p>
+ </body>
+ </html>
+
+Android Quirks
+--------------
+
+- __pref:__ This property is not support by Android devices, and will always return `false`.
+
+BlackBerry WebWorks (OS 5.0 and higher) Quirks
+--------------------------------------------
+
+- __type:__ Partially supported. Used for phone numbers.
+- __value:__ Supported.
+- __pref:__ This property is not supported, and will always return `false`.
+
+iOS Quirks
+-----------
+- __pref:__ This property is not supported on iOS devices and will always return `false`.
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/ContactFindOptions/contactfindoptions.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/ContactFindOptions/contactfindoptions.md b/docs/en/1.5.0/phonegap/contacts/ContactFindOptions/contactfindoptions.md
new file mode 100644
index 0000000..586ba67
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/ContactFindOptions/contactfindoptions.md
@@ -0,0 +1,93 @@
+ContactFindOptions
+==================
+
+Contains properties that can be used to filter the results of a `contacts.find` operation.
+
+Properties
+----------
+
+- __filter:__ The search string used to find contacts. _(DOMString)_ (Default: "")
+- __multiple:__ Determines if the find operation should return multiple contacts. _(Boolean)_ (Default: false)
+
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Quick Example
+-------------
+
+ // success callback
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ alert(contacts[i].displayName);
+ }
+ };
+
+ // error callback
+ function onError(contactError) {
+ alert('onError!');
+ };
+
+ // specify contact search criteria
+ var options = new ContactFindOptions();
+ options.filter=""; // empty search string returns all contacts
+ options.multiple=true; // return multiple results
+ filter = ["displayName"]; // return contact.displayName field
+
+ // find contacts
+ navigator.contacts.find(filter, onSuccess, onError, options);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Contact Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ // specify contact search criteria
+ var options = new ContactFindOptions();
+ options.filter=""; // empty search string returns all contacts
+ options.multiple=true; // return multiple results
+ filter = ["displayName"]; // return contact.displayName field
+
+ // find contacts
+ navigator.contacts.find(filter, onSuccess, onError, options);
+ }
+
+ // onSuccess: Get a snapshot of the current contacts
+ //
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ alert(contacts[i].displayName);
+ }
+ };
+
+ // onError: Failed to get the contacts
+ //
+ function onError(contactError) {
+ alert('onError!');
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Find Contacts</p>
+ </body>
+ </html>
+
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/ContactName/contactname.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/ContactName/contactname.md b/docs/en/1.5.0/phonegap/contacts/ContactName/contactname.md
new file mode 100644
index 0000000..6399d3d
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/ContactName/contactname.md
@@ -0,0 +1,118 @@
+ContactName
+===========
+
+Contains name properties of a `Contact` object.
+
+Properties
+----------
+
+- __formatted:__ The complete name of the contact. _(DOMString)_
+- __familyName:__ The contacts family name. _(DOMString)_
+- __givenName:__ The contacts given name. _(DOMString)_
+- __middleName:__ The contacts middle name. _(DOMString)_
+- __honorificPrefix:__ The contacts prefix (example Mr. or Dr.) _(DOMString)_
+- __honorificSuffix:__ The contacts suffix (example Esq.). _(DOMString)_
+
+Details
+-------
+
+The `ContactName` object stores name properties of a contact.
+
+Supported Platforms
+-------------------
+
+- Android 2.X
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Quick Example
+-------------
+
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ alert("Formatted: " + contacts[i].name.formatted + "\n" +
+ "Family Name: " + contacts[i].name.familyName + "\n" +
+ "Given Name: " + contacts[i].name.givenName + "\n" +
+ "Middle Name: " + contacts[i].name.middleName + "\n" +
+ "Suffix: " + contacts[i].name.honorificSuffix + "\n" +
+ "Prefix: " + contacts[i].name.honorificSuffix);
+ }
+ };
+
+ function onError(contactError) {
+ alert('onError!');
+ };
+
+ var options = new ContactFindOptions();
+ options.filter="";
+ filter = ["displayName","name"];
+ navigator.contacts.find(filter, onSuccess, onError, options);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Contact Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ var options = new ContactFindOptions();
+ options.filter="";
+ filter = ["displayName","name"];
+ navigator.contacts.find(filter, onSuccess, onError, options);
+ }
+
+ // onSuccess: Get a snapshot of the current contacts
+ //
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ alert("Formatted: " + contacts[i].name.formatted + "\n" +
+ "Family Name: " + contacts[i].name.familyName + "\n" +
+ "Given Name: " + contacts[i].name.givenName + "\n" +
+ "Middle Name: " + contacts[i].name.middleName + "\n" +
+ "Suffix: " + contacts[i].name.honorificSuffix + "\n" +
+ "Prefix: " + contacts[i].name.honorificPrefix);
+ }
+ };
+
+ // onError: Failed to get the contacts
+ //
+ function onError(contactError) {
+ alert('onError!');
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Find Contacts</p>
+ </body>
+ </html>
+
+Android Quirks
+------------
+- __formatted:__ Partially supported. Will return the concatenation of honorificPrefix, givenName, middleName, familyName and honorificSuffix but will not store.
+
+BlackBerry WebWorks (OS 5.0 and higher) Quirks
+---------------------------------------------
+
+- __formatted:__ Partially supported. Will return concatenation of BlackBerry __firstName__ and __lastName__ fields.
+- __familyName:__ Supported. Stored in BlackBerry __lastName__ field.
+- __givenName:__ Supported. Stored in BlackBerry __firstName__ field.
+- __middleName:__ This property is not supported, and will always return `null`.
+- __honorificPrefix:__ This property is not supported, and will always return `null`.
+- __honorificSuffix:__ This property is not supported, and will always return `null`.
+
+iOS Quirks
+------------
+- __formatted:__ Partially supported. Will return iOS Composite Name but will not store.
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/ContactOrganization/contactorganization.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/ContactOrganization/contactorganization.md b/docs/en/1.5.0/phonegap/contacts/ContactOrganization/contactorganization.md
new file mode 100644
index 0000000..9f64f09
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/ContactOrganization/contactorganization.md
@@ -0,0 +1,131 @@
+ContactOrganization
+===================
+
+Contains organization properties of a `Contact` object.
+
+Properties
+----------
+- __pref:__ Set to `true` if this `ContactOrganization` contains the user's preferred value. _(boolean)_
+- __type:__ A string that tells you what type of field this is (example: 'home'). _(DOMString)
+- __name:__ The name of the organization. _(DOMString)_
+- __department:__ The department the contract works for. _(DOMString)_
+- __title:__ The contacts title at the organization. _(DOMString)_
+
+Details
+-------
+
+The `ContactOrganization` object stores a contact's organization properties. A `Contact` object stores one or more `ContactOrganization` objects in an array.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Quick Example
+-------------
+
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ for (var j=0; j<contacts[i].organizations.length; j++) {
+ alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
+ "Type: " + contacts[i].organizations[j].type + "\n" +
+ "Name: " + contacts[i].organizations[j].name + "\n" +
+ "Department: " + contacts[i].organizations[j].department + "\n" +
+ "Title: " + contacts[i].organizations[j].title);
+ }
+ }
+ };
+
+ function onError(contactError) {
+ alert('onError!');
+ };
+
+ var options = new ContactFindOptions();
+ options.filter="";
+ filter = ["displayName","organizations"];
+ navigator.contacts.find(filter, onSuccess, onError, options);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Contact Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ var options = new ContactFindOptions();
+ options.filter="";
+ filter = ["displayName","organizations"];
+ navigator.contacts.find(filter, onSuccess, onError, options);
+ }
+
+ // onSuccess: Get a snapshot of the current contacts
+ //
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ for (var j=0; j<contacts[i].organizations.length; j++) {
+ alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
+ "Type: " + contacts[i].organizations[j].type + "\n" +
+ "Name: " + contacts[i].organizations[j].name + "\n" +
+ "Department: " + contacts[i].organizations[j].department + "\n" +
+ "Title: " + contacts[i].organizations[j].title);
+ }
+ }
+ };
+
+ // onError: Failed to get the contacts
+ //
+ function onError(contactError) {
+ alert('onError!');
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Find Contacts</p>
+ </body>
+ </html>
+
+
+Android 2.X Quirks
+------------------
+
+- __pref:__ This property is not supported by Android 2.X devices and will always return `false`.
+
+Android 1.X Quirks
+------------------
+
+- __pref:__ This property is not supported by Android 1.X devices and will always return `false`.
+- __type:__ This property is not supported by Android 1.X devices and will always return `null`.
+- __title:__ This property is not supported by Android 1.X devices, and will always be returned as `null`.
+
+BlackBerry WebWorks (OS 5.0 and higher) Quirks
+--------------------------------------------
+- __pref:__ This property is not supported by Blackberry devices and will always return `false`.
+- __type:__ This property is not supported by Blackberry devices and will always return `null`.
+- __name:__ Partially supported. The first organization name will be stored in the BlackBerry __company__ field.
+- __department:__ This property is not supported, and will always be returned as `null`.
+- __title:__ Partially supported. The first organization title will be stored in the BlackBerry __jobTitle__ field.
+
+iOS Quirks
+-----------
+- __pref:__ This property is not supported on iOS devices and will always return `false`.
+- __type:__ This property is not supported on iOS devices and will always return `null`.
+- __name:__ Partially supported. The first organization name will be stored in the iOS __kABPersonOrganizationProperty__ field.
+- __department__: Partially supported. The first department name will be stored in the iOS __kABPersonDepartmentProperty__ field.
+- __title__: Partially supported. The first title will be stored in the iOS __kABPersonJobTitleProperty__ field.
+
+
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/contacts.create.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/contacts.create.md b/docs/en/1.5.0/phonegap/contacts/contacts.create.md
new file mode 100644
index 0000000..c9634f6
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/contacts.create.md
@@ -0,0 +1,57 @@
+contacts.create
+===============
+
+Returns a new Contact object.
+
+ var contact = navigator.contacts.create(properties);
+
+Description
+-----------
+
+contacts.create is a synchronous function that returns a new `Contact` object.
+
+This method does not persist the Contact object to the device contacts database. To persist the Contact object to the device, invoke the `Contact.save` method.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Quick Example
+-------------
+
+ var myContact = navigator.contacts.create({"displayName": "Test User"});
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Contact Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ var myContact = navigator.contacts.create({"displayName": "Test User"});
+ myContact.gender = "male";
+ console.log("The contact, " + myContact.displayName + ", is of the " + myContact.gender + " gender");
+ }
+
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Create Contact</p>
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/contacts.find.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/contacts.find.md b/docs/en/1.5.0/phonegap/contacts/contacts.find.md
new file mode 100644
index 0000000..e50cef3
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/contacts.find.md
@@ -0,0 +1,96 @@
+contacts.find
+=============
+
+Queries the device contacts database and returns one or more `Contact` objects, each containing the fields specified.
+
+ navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);
+
+Description
+-----------
+
+contacts.find is an asynchronous function that queries the device contacts database and returns an array of `Contact` objects. The resulting objects are passed to the `contactSuccess` callback function specified by the __contactSuccess__ parameter.
+
+Users must specify the contact fields to be used as a search qualifier in the __contactFields__ parameter. Only the fields specified in the __contactFields__ parameter will be returned as properties of the `Contact` objects that are passed to the __contactSuccess__ callback function. A zero-length __contactFields__ parameter will result in an array of `Contact` objects with only the `id` property populated. A __contactFields__ value of ["*"] will return all contact fields.
+
+The __contactFindOptions.filter__ string can be used as a search filter when querying the contacts database. If provided, a case-insensitive, partial value match is applied to each field specified in the __contactFields__ parameter. If a match is found in a comparison with _any_ of the specified fields, the contact is returned.
+
+Parameters
+----------
+
+- __contactFields:__ Contact fields to be used as search qualifier. Only these fields will have values in the resulting `Contact` objects. _(DOMString[])_ [Required]
+- __contactSuccess:__ Success callback function that is invoked with the contacts returned from the contacts database. [Required]
+- __contactError:__ Error callback function. Invoked when error occurs. [Optional]
+- __contactFindOptions:__ Search options to filter contacts. [Optional]
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Quick Example
+-------------
+
+ function onSuccess(contacts) {
+ alert('Found ' + contacts.length + ' contacts.');
+ };
+
+ function onError(contactError) {
+ alert('onError!');
+ };
+
+ // find all contacts with 'Bob' in any name field
+ var options = new ContactFindOptions();
+ options.filter="Bob";
+ var fields = ["displayName", "name"];
+ navigator.contacts.find(fields, onSuccess, onError, options);
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Contact Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ // find all contacts with 'Bob' in any name field
+ var options = new ContactFindOptions();
+ options.filter="Bob";
+ var fields = ["displayName", "name"];
+ navigator.contacts.find(fields, onSuccess, onError, options);
+ }
+
+ // onSuccess: Get a snapshot of the current contacts
+ //
+ function onSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ console.log("Display Name = " + contacts[i].displayName);
+ }
+ }
+
+ // onError: Failed to get the contacts
+ //
+ function onError(contactError) {
+ alert('onError!');
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Find Contacts</p>
+ </body>
+ </html>
+
+
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/contacts.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/contacts.md b/docs/en/1.5.0/phonegap/contacts/contacts.md
new file mode 100644
index 0000000..d6078ae
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/contacts.md
@@ -0,0 +1,29 @@
+Contacts
+========
+
+> The `contacts` object provides access to the device contacts database.
+
+Methods
+-------
+
+- contacts.create
+- contacts.find
+
+Arguments
+---------
+
+- contactFields
+- contactSuccess
+- contactError
+- contactFindOptions
+
+Objects
+-------
+
+- Contact
+- ContactName
+- ContactField
+- ContactAddress
+- ContactOrganization
+- ContactFindOptions
+- ContactError
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/parameters/contactError.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/parameters/contactError.md b/docs/en/1.5.0/phonegap/contacts/parameters/contactError.md
new file mode 100644
index 0000000..5d1af51
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/parameters/contactError.md
@@ -0,0 +1,8 @@
+contactError
+============
+
+Error callback function for contact functions.
+
+ function(error) {
+ // Handle the error
+ }
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/parameters/contactFields.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/parameters/contactFields.md b/docs/en/1.5.0/phonegap/contacts/parameters/contactFields.md
new file mode 100644
index 0000000..9d6005c
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/parameters/contactFields.md
@@ -0,0 +1,6 @@
+contactFields
+=============
+
+Required parameter of the `contacts.find` method. Use this parameter to specify which fields should be included in the `Contact` objects resulting from a find operation.
+
+ ["name", "phoneNumbers", "emails"]
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/parameters/contactFindOptions.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/parameters/contactFindOptions.md b/docs/en/1.5.0/phonegap/contacts/parameters/contactFindOptions.md
new file mode 100644
index 0000000..4a88e42
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/parameters/contactFindOptions.md
@@ -0,0 +1,16 @@
+contactFindOptions
+==================
+
+Optional parameter of the `contacts.find` method. Use this parameter to filter the contacts returned from the contacts database.
+
+ {
+ filter: "",
+ multiple: true,
+ };
+
+Options
+-------
+
+- __filter:__ The search string used to filter contacts. _(DOMString)_ (Default: "")
+- __multiple:__ Determines if the find operation should return multiple contacts. _(Boolean)_ (Default: false)
+
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/contacts/parameters/contactSuccess.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/contacts/parameters/contactSuccess.md b/docs/en/1.5.0/phonegap/contacts/parameters/contactSuccess.md
new file mode 100644
index 0000000..3625294
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/contacts/parameters/contactSuccess.md
@@ -0,0 +1,21 @@
+contactSuccess
+==============
+
+Success callback function that provides the `Contact` array resulting from a `contacts.find` operation.
+
+ function(contacts) {
+ // Do something
+ }
+
+Parameters
+----------
+
+- __contacts:__ The contact array resulting from a find operation. (`Contact`)
+
+Example
+-------
+
+ function contactSuccess(contacts) {
+ for (var i=0; i<contacts.length; i++) {
+ console.log("Display Name = " + contacts[i].displayName;
+ }
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/device/device.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/device/device.md b/docs/en/1.5.0/phonegap/device/device.md
new file mode 100644
index 0000000..925f7e7
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/device/device.md
@@ -0,0 +1,23 @@
+Device
+======
+
+> The `device` object describes the device's hardware and software.
+
+Properties
+----------
+
+- device.name
+- device.phonegap
+- device.platform
+- device.uuid
+- device.version
+
+Variable Scope
+--------------
+
+Since `device` is assigned to the `window` object, it is implicitly in the global scope.
+
+ // These reference the same `device`
+ //
+ var phoneName = window.device.name;
+ var phoneName = device.name;
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/device/device.name.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/device/device.name.md b/docs/en/1.5.0/phonegap/device/device.name.md
new file mode 100644
index 0000000..1fad923
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/device/device.name.md
@@ -0,0 +1,79 @@
+device.name
+===========
+
+Get the device's model name.
+
+ var string = device.name;
+
+Description
+-----------
+
+`device.name` returns the name of the device's model or product. This value is set by the device manufacturer and may be different across versions of the same product.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iPhone
+- Windows Phone 7 ( Mango )
+
+Quick Example
+-------------
+
+ // Android: Nexus One returns "Passion" (Nexus One code name)
+ // Motorola Droid returns "voles"
+ // BlackBerry: Bold 8900 returns "8900"
+ // iPhone: All devices returns a name set by iTunes e.g. "Joe's iPhone"
+ //
+ var name = device.name;
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Device Properties Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ var element = document.getElementById('deviceProperties');
+
+ element.innerHTML = 'Device Name: ' + device.name + '<br />' +
+ 'Device PhoneGap: ' + device.phonegap + '<br />' +
+ 'Device Platform: ' + device.platform + '<br />' +
+ 'Device UUID: ' + device.uuid + '<br />' +
+ 'Device Version: ' + device.version + '<br />';
+ }
+
+ </script>
+ </head>
+ <body>
+ <p id="deviceProperties">Loading device properties...</p>
+ </body>
+ </html>
+
+
+Android Quirks
+--------------
+
+- Gets the [product name](http://developer.android.com/reference/android/os/Build.html#PRODUCT) instead of the [model name](http://developer.android.com/reference/android/os/Build.html#MODEL).
+ - The product name is often the code name given during production.
+ - e.g. Nexus One returns "Passion", Motorola Droid returns "voles"
+
+iPhone Quirks
+-------------
+
+- Gets the [device's custom name](http://developer.apple.com/iphone/library/documentation/uikit/reference/UIDevice_Class/Reference/UIDevice.html#//apple_ref/doc/uid/TP40006902-CH3-SW13) instead of the [device model name](http://developer.apple.com/iphone/library/documentation/uikit/reference/UIDevice_Class/Reference/UIDevice.html#//apple_ref/doc/uid/TP40006902-CH3-SW1).
+ - The custom name is set by the owner in iTunes.
+ - e.g. "Joe's iPhone"
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/device/device.phonegap.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/device/device.phonegap.md b/docs/en/1.5.0/phonegap/device/device.phonegap.md
new file mode 100644
index 0000000..80da863
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/device/device.phonegap.md
@@ -0,0 +1,60 @@
+device.phonegap
+===============
+
+Get the version of phonegap running on the device.
+
+ var string = device.phonegap;
+
+Description
+-----------
+
+`device.phonegap` returns the version of phonegap running on the device.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iPhone
+- Windows Phone 7 ( Mango )
+
+Quick Example
+-------------
+
+ var name = device.phonegap;
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Device Properties Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ var element = document.getElementById('deviceProperties');
+
+ element.innerHTML = 'Device Name: ' + device.name + '<br />' +
+ 'Device PhoneGap: ' + device.phonegap + '<br />' +
+ 'Device Platform: ' + device.platform + '<br />' +
+ 'Device UUID: ' + device.uuid + '<br />' +
+ 'Device Version: ' + device.version + '<br />';
+ }
+
+ </script>
+ </head>
+ <body>
+ <p id="deviceProperties">Loading device properties...</p>
+ </body>
+ </html>
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/device/device.platform.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/device/device.platform.md b/docs/en/1.5.0/phonegap/device/device.platform.md
new file mode 100644
index 0000000..ba38f86
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/device/device.platform.md
@@ -0,0 +1,70 @@
+device.platform
+===============
+
+Get the device's operating system name.
+
+ var string = device.platform;
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iPhone
+- Windows Phone 7 ( Mango )
+
+Quick Example
+-------------
+
+ // Depending on the device, a few examples are:
+ // - "Android"
+ // - "BlackBerry"
+ // - "iPhone"
+ // - "webOS"
+ // - "WinCE"
+ var devicePlatform = device.platform;
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Device Properties Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ var element = document.getElementById('deviceProperties');
+
+ element.innerHTML = 'Device Name: ' + device.name + '<br />' +
+ 'Device PhoneGap: ' + device.phonegap + '<br />' +
+ 'Device Platform: ' + device.platform + '<br />' +
+ 'Device UUID: ' + device.uuid + '<br />' +
+ 'Device Version: ' + device.version + '<br />';
+ }
+
+ </script>
+ </head>
+ <body>
+ <p id="deviceProperties">Loading device properties...</p>
+ </body>
+ </html>
+
+iPhone Quirks
+-------------
+
+All devices return `iPhone` as the platform. This is inaccurate because Apple has rebranded the iPhone operating system as `iOS`.
+
+BlackBerry Quirks
+-----------------
+
+Devices may return the device platform version instead of the platform name. For example, the Storm2 9550 would return '2.13.0.95' or similar.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/device/device.uuid.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/device/device.uuid.md b/docs/en/1.5.0/phonegap/device/device.uuid.md
new file mode 100644
index 0000000..7082d93
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/device/device.uuid.md
@@ -0,0 +1,72 @@
+device.uuid
+===========
+
+Get the device's Universally Unique Identifier ([UUID](http://en.wikipedia.org/wiki/Universally_Unique_Identifier)).
+
+ var string = device.uuid;
+
+Description
+-----------
+
+The details of how a UUID is generated are determined by the device manufacturer and specific to the device's platform or model.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iPhone
+- Windows Phone 7 ( Mango )
+
+Quick Example
+-------------
+
+ // Android: Returns a random 64-bit integer (as a string, again!)
+ // The integer is generated on the device's first boot
+ //
+ // BlackBerry: Returns the PIN number of the device
+ // This is a nine-digit unique integer (as a string, though!)
+ //
+ // iPhone: (Paraphrased from the UIDevice Class documentation)
+ // Returns a string of hash values created from multiple hardware identifies.
+ // It is guaranteed to be unique for every device and cannot be tied
+ // to the user account.
+ // Windows Phone 7 : Returns a hash of device+current user,
+ // if the user is not defined, a guid is generated and will persist until the app is uninstalled
+ //
+ var deviceID = device.uuid;
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Device Properties Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ var element = document.getElementById('deviceProperties');
+
+ element.innerHTML = 'Device Name: ' + device.name + '<br />' +
+ 'Device PhoneGap: ' + device.phonegap + '<br />' +
+ 'Device Platform: ' + device.platform + '<br />' +
+ 'Device UUID: ' + device.uuid + '<br />' +
+ 'Device Version: ' + device.version + '<br />';
+ }
+
+ </script>
+ </head>
+ <body>
+ <p id="deviceProperties">Loading device properties...</p>
+ </body>
+ </html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/device/device.version.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/device/device.version.md b/docs/en/1.5.0/phonegap/device/device.version.md
new file mode 100644
index 0000000..cf41777
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/device/device.version.md
@@ -0,0 +1,63 @@
+device.version
+==============
+
+Get the operating system version.
+
+ var string = device.version;
+
+Supported Platforms
+-------------------
+
+- Android 2.1+
+- BlackBerry
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iPhone
+- Windows Phone 7 ( Mango )
+
+Quick Example
+-------------
+
+ // Android: Froyo OS would return "2.2"
+ // Eclair OS would return "2.1", "2.0.1", or "2.0"
+ // Version can also return update level "2.1-update1"
+ //
+ // BlackBerry: Bold 9000 using OS 4.6 would return "4.6.0.282"
+ //
+ // iPhone: iOS 3.2 returns "3.2"
+ //
+ // Windows Phone 7: returns current OS version number, ex. on Mango returns 7.10.7720
+ var deviceVersion = device.version;
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Device Properties Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for PhoneGap to load
+ //
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ // PhoneGap is ready
+ //
+ function onDeviceReady() {
+ var element = document.getElementById('deviceProperties');
+
+ element.innerHTML = 'Device Name: ' + device.name + '<br />' +
+ 'Device PhoneGap: ' + device.phonegap + '<br />' +
+ 'Device Platform: ' + device.platform + '<br />' +
+ 'Device UUID: ' + device.uuid + '<br />' +
+ 'Device Version: ' + device.version + '<br />';
+ }
+
+ </script>
+ </head>
+ <body>
+ <p id="deviceProperties">Loading device properties...</p>
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/events/events.backbutton.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/events/events.backbutton.md b/docs/en/1.5.0/phonegap/events/events.backbutton.md
new file mode 100644
index 0000000..3949a7e
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/events/events.backbutton.md
@@ -0,0 +1,67 @@
+backbutton
+===========
+
+This is an event that fires when the user presses the back button.
+
+ document.addEventListener("backbutton", yourCallbackFunction, false);
+
+Details
+-------
+
+If you need to override the default back button behaviour you can register an event listener for the 'backbutton' event. It is no longer necessary to call any other method to over ride the back button behaviour. Now, you only need to register an event listener for 'backbutton'.
+
+Typically, you will want to attach an event listener with `document.addEventListener` once you receive the PhoneGap 'deviceready' event.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+
+Quick Example
+-------------
+
+ document.addEventListener("backbutton", onBackKeyDown, false);
+
+ function onBackKeyDown() {
+ // Handle the back button
+ }
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>PhoneGap Back Button Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Call onDeviceReady when PhoneGap is loaded.
+ //
+ // At this point, the document has loaded but phonegap.js has not.
+ // When PhoneGap is loaded and talking with the native device,
+ // it will call the event `deviceready`.
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // PhoneGap is loaded and it is now safe to call PhoneGap methods
+ //
+ function onDeviceReady() {
+ // Register the event listener
+ document.addEventListener("backbutton", onBackKeyDown, false);
+ }
+
+ // Handle the back button
+ //
+ function onBackKeyDown() {
+ }
+
+ </script>
+ </head>
+ <body onload="onLoad()">
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/events/events.batterycritical.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/events/events.batterycritical.md b/docs/en/1.5.0/phonegap/events/events.batterycritical.md
new file mode 100644
index 0000000..e169a99
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/events/events.batterycritical.md
@@ -0,0 +1,74 @@
+batterycritical
+===========
+
+This is an event that fires when a PhoneGap application detects the battery has reached the critical level threshold.
+
+ window.addEventListener("batterycritical", yourCallbackFunction, false);
+
+Details
+-------
+
+This event that fires when a PhoneGap application detects the percentage of battery has reached the critical battery threshold. This value is device specific.
+
+The batterycritical handler will be called with an object that contains two properties:
+
+- __level:__ The percentage of battery (0-100). _(Number)_
+- __isPlugged:__ A boolean that represents whether or not the device is plugged in or not. _(Boolean)_
+
+Typically, you will want to attach an event listener with `window.addEventListener` once you receive the PhoneGap 'deviceready' event.
+
+Supported Platforms
+-------------------
+
+- iOS
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+
+Quick Example
+-------------
+
+ window.addEventListener("batterycritical", onBatteryCritical, false);
+
+ function onBatteryCritical(info) {
+ // Handle the battery critical event
+ alert("Battery Level Critical " + info.level + "%\nRecharge Soon!");
+ }
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>PhoneGap Device Ready Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Call onDeviceReady when PhoneGap is loaded.
+ //
+ // At this point, the document has loaded but phonegap.js has not.
+ // When PhoneGap is loaded and talking with the native device,
+ // it will call the event `deviceready`.
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
+ //
+ function onDeviceReady() {
+ window.addEventListener("batterycritical", onBatteryCritical, false);
+ }
+
+ // Handle the batterycritical event
+ //
+ function onBatteryCritical(info) {
+ alert("Battery Level Critical " + info.level + "%\nRecharge Soon!");
+ }
+
+ </script>
+ </head>
+ <body onload="onLoad()">
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/events/events.batterylow.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/events/events.batterylow.md b/docs/en/1.5.0/phonegap/events/events.batterylow.md
new file mode 100644
index 0000000..e051be4
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/events/events.batterylow.md
@@ -0,0 +1,74 @@
+batterylow
+===========
+
+This is an event that fires when a PhoneGap application detects the battery has reached the low level threshold.
+
+ window.addEventListener("batterylow", yourCallbackFunction, false);
+
+Details
+-------
+
+This event that fires when a PhoneGap application detects the percentage of battery has reached the low battery threshold. This value is device specific.
+
+The batterylow handler will be called with an object that contains two properties:
+
+- __level:__ The percentage of battery (0-100). _(Number)_
+- __isPlugged:__ A boolean that represents whether or not the device is plugged in or not. _(Boolean)_
+
+Typically, you will want to attach an event listener with `document.addEventListener` once you receive the PhoneGap 'deviceready' event.
+
+Supported Platforms
+-------------------
+
+- iOS
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+
+Quick Example
+-------------
+
+ window.addEventListener("batterylow", onBatteryLow, false);
+
+ function onBatteryLow(info) {
+ // Handle the battery low event
+ alert("Battery Level Low " + info.level + "%");
+ }
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>PhoneGap Device Ready Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Call onDeviceReady when PhoneGap is loaded.
+ //
+ // At this point, the document has loaded but phonegap.js has not.
+ // When PhoneGap is loaded and talking with the native device,
+ // it will call the event `deviceready`.
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
+ //
+ function onDeviceReady() {
+ window.addEventListener("batterylow", onBatteryLow, false);
+ }
+
+ // Handle the batterylow event
+ //
+ function onBatteryLow(info) {
+ alert("Battery Level Low " + info.level + "%");
+ }
+
+ </script>
+ </head>
+ <body onload="onLoad()">
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/events/events.batterystatus.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/events/events.batterystatus.md b/docs/en/1.5.0/phonegap/events/events.batterystatus.md
new file mode 100644
index 0000000..1fa5dc0
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/events/events.batterystatus.md
@@ -0,0 +1,74 @@
+batterystatus
+===========
+
+This is an event that fires when a PhoneGap application detects a change in the battery status.
+
+ window.addEventListener("batterystatus", yourCallbackFunction, false);
+
+Details
+-------
+
+This event that fires when a PhoneGap application detects the percentage of battery has changed by at least 1 percent. It is also fired if the device has been plugged in or un-plugged.
+
+The battery status handler will be called with an object that contains two properties:
+
+- __level:__ The percentage of battery (0-100). _(Number)_
+- __isPlugged:__ A boolean that represents whether or not the device is plugged in or not. _(Boolean)_
+
+Typically, you will want to attach an event listener with `window.addEventListener` once you receive the PhoneGap 'deviceready' event.
+
+Supported Platforms
+-------------------
+
+- iOS
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+
+Quick Example
+-------------
+
+ window.addEventListener("batterystatus", onBatteryStatus, false);
+
+ function onBatteryStatus(info) {
+ // Handle the online event
+ console.log("Level: " + info.level + " isPlugged: " + info.isPlugged);
+ }
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>PhoneGap Device Ready Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Call onDeviceReady when PhoneGap is loaded.
+ //
+ // At this point, the document has loaded but phonegap.js has not.
+ // When PhoneGap is loaded and talking with the native device,
+ // it will call the event `deviceready`.
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
+ //
+ function onDeviceReady() {
+ window.addEventListener("batterystatus", onBatteryStatus, false);
+ }
+
+ // Handle the batterystatus event
+ //
+ function onBatteryStatus(info) {
+ console.log("Level: " + info.level + " isPlugged: " + info.isPlugged);
+ }
+
+ </script>
+ </head>
+ <body onload="onLoad()">
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/events/events.deviceready.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/events/events.deviceready.md b/docs/en/1.5.0/phonegap/events/events.deviceready.md
new file mode 100644
index 0000000..743e305
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/events/events.deviceready.md
@@ -0,0 +1,92 @@
+deviceready
+===========
+
+This is an event that fires when PhoneGap is fully loaded.
+
+ document.addEventListener("deviceready", yourCallbackFunction, false);
+
+Details
+-------
+
+This is a very important event that every PhoneGap application should use.
+
+PhoneGap consists of two code bases: native and JavaScript. While the native code is loading, a custom loading image is displayed. However, JavaScript is only loaded once the DOM loads. This means your web application could, potentially, call a PhoneGap JavaScript function before it is loaded.
+
+The PhoneGap `deviceready` event fires once PhoneGap has fully loaded. After the device has fired, you can safely make calls to PhoneGap function.
+
+Typically, you will want to attach an event listener with `document.addEventListener` once the HTML document's DOM has loaded.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+
+Quick Example
+-------------
+
+ document.addEventListener("deviceready", onDeviceReady, false);
+
+ function onDeviceReady() {
+ // Now safe to use the PhoneGap API
+ }
+
+Full Example
+------------
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>PhoneGap Device Ready Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Call onDeviceReady when PhoneGap is loaded.
+ //
+ // At this point, the document has loaded but phonegap.js has not.
+ // When PhoneGap is loaded and talking with the native device,
+ // it will call the event `deviceready`.
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
+ //
+ function onDeviceReady() {
+ // Now safe to use the PhoneGap API
+ }
+
+ </script>
+ </head>
+ <body onload="onLoad()">
+ </body>
+ </html>
+
+BlackBerry (OS 4.6) Quirks
+--------------------------
+
+Custom events are not supported in the RIM BrowserField (web browser view), so the `deviceready` event will never fire.
+
+A workaround is to manually query `PhoneGap.available` until PhoneGap has fully loaded.
+
+ function onLoad() {
+ // BlackBerry OS 4 browser does not support events.
+ // So, manually wait until PhoneGap is available.
+ //
+ var intervalID = window.setInterval(
+ function() {
+ if (PhoneGap.available) {
+ window.clearInterval(intervalID);
+ onDeviceReady();
+ }
+ },
+ 500
+ );
+ }
+
+ function onDeviceReady() {
+ // Now safe to use the PhoneGap API
+ }
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/events/events.endcallbutton.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/events/events.endcallbutton.md b/docs/en/1.5.0/phonegap/events/events.endcallbutton.md
new file mode 100644
index 0000000..48db299
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/events/events.endcallbutton.md
@@ -0,0 +1,67 @@
+endcallbutton
+===========
+
+This is an event that fires when the user presses the end call button.
+
+ document.addEventListener("endcallbutton", yourCallbackFunction, false);
+
+Details
+-------
+
+If you need to override the default end call behaviour you can register an event listener for the 'endcallbutton' event.
+
+Typically, you will want to attach an event listener with `document.addEventListener` once you receive the PhoneGap 'deviceready' event.
+
+Supported Platforms
+-------------------
+
+- BlackBerry WebWorks (OS 5.0 and higher)
+
+Quick Example
+-------------
+
+ document.addEventListener("endcallbutton", onEndCallKeyDown, false);
+
+ function onEndCallKeyDown() {
+ // Handle the end call button
+ }
+
+Full Example
+------------
+
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+ <html>
+ <head>
+ <title>PhoneGap End Call Button Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Call onDeviceReady when PhoneGap is loaded.
+ //
+ // At this point, the document has loaded but phonegap.js has not.
+ // When PhoneGap is loaded and talking with the native device,
+ // it will call the event `deviceready`.
+ //
+ function onLoad() {
+ document.addEventListener("deviceready", onDeviceReady, false);
+ }
+
+ // PhoneGap is loaded and it is now safe to make calls PhoneGap methods
+ //
+ function onDeviceReady() {
+ // Register the event listener
+ document.addEventListener("endcallbutton", onEndCallKeyDown, false);
+ }
+
+ // Handle the end call button
+ //
+ function onEndCallKeyDown() {
+ }
+
+ </script>
+ </head>
+ <body onload="onLoad()">
+ </body>
+ </html>
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/de72da52/docs/en/1.5.0/phonegap/events/events.md
----------------------------------------------------------------------
diff --git a/docs/en/1.5.0/phonegap/events/events.md b/docs/en/1.5.0/phonegap/events/events.md
new file mode 100644
index 0000000..831138f
--- /dev/null
+++ b/docs/en/1.5.0/phonegap/events/events.md
@@ -0,0 +1,24 @@
+Events
+======
+
+> PhoneGap lifecycle events.
+
+Event Types
+-----------
+
+- deviceready
+- pause
+- resume
+- online
+- offline
+- backbutton
+- batterycritical
+- batterylow
+- batterystatus
+- menubutton
+- searchbutton
+- startcallbutton
+- endcallbutton
+- volumedownbutton
+- volumeupbutton
+