Return-Path: X-Original-To: apmail-incubator-callback-commits-archive@minotaur.apache.org Delivered-To: apmail-incubator-callback-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id CBD2FD0D0 for ; Thu, 21 Jun 2012 19:01:08 +0000 (UTC) Received: (qmail 52795 invoked by uid 500); 21 Jun 2012 19:01:08 -0000 Delivered-To: apmail-incubator-callback-commits-archive@incubator.apache.org Received: (qmail 52763 invoked by uid 500); 21 Jun 2012 19:01:08 -0000 Mailing-List: contact callback-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: callback-dev@incubator.apache.org Delivered-To: mailing list callback-commits@incubator.apache.org Received: (qmail 52714 invoked by uid 99); 21 Jun 2012 19:01:08 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 21 Jun 2012 19:01:08 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id D2A696303; Thu, 21 Jun 2012 19:01:07 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: mwbrooks@apache.org To: callback-commits@incubator.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [2/8] Version 1.9.0rc1 Message-Id: <20120621190107.D2A696303@tyr.zones.apache.org> Date: Thu, 21 Jun 2012 19:01:07 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/compass/compass.watchHeading.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/compass/compass.watchHeading.md b/docs/en/1.9.0rc1/cordova/compass/compass.watchHeading.md new file mode 100755 index 0000000..da1af1b --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/compass/compass.watchHeading.md @@ -0,0 +1,132 @@ +--- +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. +--- + +compass.watchHeading +==================== + +At a regular interval, get the compass heading in degrees. + + var watchID = navigator.compass.watchHeading(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.watchHeading` gets the device's current heading at a regular interval. Each time the heading is retrieved, the `headingSuccess` callback function is executed. Specify the interval in milliseconds via the `frequency` parameter in the `compassOptions` object. + +The returned watch ID references references the compass watch interval. The watch ID can be used with `compass.clearWatch` to stop watching the compass. + +Supported Platforms +------------------- + +- Android +- iPhone +- Windows Phone 7 ( Mango ) if available in hardware +- Bada 1.2 & 2.x +- webOS + + +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 = { frequency: 3000 }; // Update every 3 seconds + + var watchID = navigator.compass.watchHeading(onSuccess, onError, options); + +Full Example +------------ + + + + + Compass Example + + + + + +
Waiting for heading...
+ + + + + +iOS Quirks +-------------- + +In iOS `compass.watchHeading` can also get 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. Clear the watch as normal by passing the returned watch ID to `compass.clearWatch`. This functionality replaces the previously separate, iOS only functions, watchHeadingFilter and clearWatchFilter, which were removed in 1.6. + +In iOS only one watchHeading can be in effect at one time. If a watchHeading via filter is in effect, calling getCurrentHeading or watchHeading will use the existing filter value for specifying heading changes. On iOS watching heading changes via a filter is more efficient than via time. http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/compass/compass.watchHeadingFilter.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/compass/compass.watchHeadingFilter.md b/docs/en/1.9.0rc1/cordova/compass/compass.watchHeadingFilter.md new file mode 100644 index 0000000..6a0283f --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/compass/compass.watchHeadingFilter.md @@ -0,0 +1,23 @@ +--- +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. +--- + +compass.watchHeadingFilter +========================== + +No longer supported as of 1.6, see `compass.watchHeading` for equivalent functionality. http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/compass/compassError/compassError.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/compass/compassError/compassError.md b/docs/en/1.9.0rc1/cordova/compass/compassError/compassError.md new file mode 100644 index 0000000..989b4dc --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/compass/compassError/compassError.md @@ -0,0 +1,40 @@ +--- +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. +--- + +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/f14a877d/docs/en/1.9.0rc1/cordova/compass/parameters/compassError.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/compass/parameters/compassError.md b/docs/en/1.9.0rc1/cordova/compass/parameters/compassError.md new file mode 100755 index 0000000..cf89324 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/compass/parameters/compassError.md @@ -0,0 +1,30 @@ +--- +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. +--- + +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/f14a877d/docs/en/1.9.0rc1/cordova/compass/parameters/compassHeading.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/compass/parameters/compassHeading.md b/docs/en/1.9.0rc1/cordova/compass/parameters/compassHeading.md new file mode 100644 index 0000000..935ea06 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/compass/parameters/compassHeading.md @@ -0,0 +1,48 @@ +--- +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. +--- + +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. + http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/compass/parameters/compassOptions.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/compass/parameters/compassOptions.md b/docs/en/1.9.0rc1/cordova/compass/parameters/compassOptions.md new file mode 100755 index 0000000..252966c --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/compass/parameters/compassOptions.md @@ -0,0 +1,42 @@ +--- +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. +--- + +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 watchHeading success callback. _(Number)_ + +Android Quirks +______________ +- filter is not supported. + +Windows Phone 7 Quirks +-------------- + +- filter is not supported. + +Bada Quirks +----------- +- filter is not supported. http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/compass/parameters/compassSuccess.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/compass/parameters/compassSuccess.md b/docs/en/1.9.0rc1/cordova/compass/parameters/compassSuccess.md new file mode 100644 index 0000000..1b0fc9c --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/compass/parameters/compassSuccess.md @@ -0,0 +1,40 @@ +--- +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. +--- + +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/f14a877d/docs/en/1.9.0rc1/cordova/connection/connection.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/connection/connection.md b/docs/en/1.9.0rc1/cordova/connection/connection.md new file mode 100644 index 0000000..c9b7c09 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/connection/connection.md @@ -0,0 +1,92 @@ +--- +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. +--- + +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 + +Permissions +----------- + +### Android + +#### app/res/xml/plugins.xml + + + +#### app/AndroidManifest.xml + + + + + +### Bada + + + SYSTEM_SERVICE + + +### BlackBerry WebWorks + +#### www/plugins.xml + + + +### iOS + +#### App/Supporting Files/Cordova.plist + + Plugins + + NetworkStatus + CDVConnection + + +### webOS + + No permissions are required. + +### Windows Phone + +#### Properties/WPAppManifest.xml + + + + + +Reference: [Application Manifest for Windows Phone](http://msdn.microsoft.com/en-us/library/ff769509%28v=vs.92%29.aspx) http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/connection/connection.type.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/connection/connection.type.md b/docs/en/1.9.0rc1/cordova/connection/connection.type.md new file mode 100644 index 0000000..9a05c19 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/connection/connection.type.md @@ -0,0 +1,123 @@ +--- +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. +--- + +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 ) +- Bada 2.x +- webOS + +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 +------------ + + + + + navigator.network.connection.type Example + + + + + +

A dialog box will report the network state.

+ + + +iOS Quirks +---------- + +- iOS cannot detect the type of cellular network connection. + - `navigator.network.connection.type` is set to `Connection.CELL_2G` for all cellular data. + +Bada Quirks +----------- + +- Bada can only detect a WiFi or cellular connection. + - `navigator.network.connection.type` is set to `Connection.CELL_2G` for all cellular data. + +webOS Quirks +------------ + +- Only shows that a connection is available, but not which type. + +Windows Phone Quirks +-------------------- + +- Windows Phone Emulator always detects `navigator.network.connection.type` as `Connection.UNKNOWN`. http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/Contact/contact.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/Contact/contact.md b/docs/en/1.9.0rc1/cordova/contacts/Contact/contact.md new file mode 100644 index 0000000..47bcf37 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/Contact/contact.md @@ -0,0 +1,232 @@ +--- +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. +--- + +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. _(ContactAddress[])_ +- __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 +- Bada 1.2 & 2.0 + +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 +------------ + + + + + Contact Example + + + + + +

Example

+

Find Contacts

+ + + +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`. + + +Bada Quirks +----------- + +- __displayName:__ This property is not supported +- __birthday:__ This property is not supported +- __photos:__ This property should be a list with one URL to a photo +- __categories:__ This property is not supported +- __ims:__ This property is not supported http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/ContactAddress/contactaddress.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/ContactAddress/contactaddress.md b/docs/en/1.9.0rc1/cordova/contacts/ContactAddress/contactaddress.md new file mode 100644 index 0000000..c5078ef --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/ContactAddress/contactaddress.md @@ -0,0 +1,170 @@ +--- +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. +--- + +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 +- Bada 1.2 & 2.0 + +Quick Example +------------- + + // display the address information for all contacts + function onSuccess(contacts) { + for (var i=0; i + + + Contact Example + + + + + +

Example

+

Find Contacts

+ + + +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. + +Bada Quirks +----------- +- __formatted:__ This property is not supported +- __type:__ Has to be one of the following: WORK, HOME http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/ContactError/contactError.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/ContactError/contactError.md b/docs/en/1.9.0rc1/cordova/contacts/ContactError/contactError.md new file mode 100644 index 0000000..45b5873 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/ContactError/contactError.md @@ -0,0 +1,45 @@ +--- +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. +--- + +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/f14a877d/docs/en/1.9.0rc1/cordova/contacts/ContactField/contactfield.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/ContactField/contactfield.md b/docs/en/1.9.0rc1/cordova/contacts/ContactField/contactfield.md new file mode 100644 index 0000000..d00f870 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/ContactField/contactfield.md @@ -0,0 +1,146 @@ +--- +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. +--- + +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, Cordova makes use of the __type__ field to indicate the format of the returned image. Cordova 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 +- Bada 1.2 & 2.0 + +Quick Example +------------- + + // create a new contact + var contact = navigator.contacts.create(); + + // store contact phone numbers in ContactField[] + var phoneNumbers = []; + 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 +------------ + + + + + Contact Example + + + + + +

Example

+

Find Contacts

+ + + +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`. + +Bada Quirks +----------- +- __type:__ Property has to be one of the following for Email or Address fields: "WORK", "HOME". Property has to be one of the following for Phone fields: "WORK", "HOME", "VOICE", "FAX", "MSG", "CELL", "PAGER","BBS", "MODEM", "CAR", "ISDN","VIDEO", "PCS" http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/ContactFindOptions/contactfindoptions.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/ContactFindOptions/contactfindoptions.md b/docs/en/1.9.0rc1/cordova/contacts/ContactFindOptions/contactfindoptions.md new file mode 100644 index 0000000..f4625de --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/ContactFindOptions/contactfindoptions.md @@ -0,0 +1,116 @@ +--- +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. +--- + +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 +- Bada 1.2 & 2.0 + +Quick Example +------------- + + // success callback + function onSuccess(contacts) { + for (var i=0; i + + + Contact Example + + + + + +

Example

+

Find Contacts

+ + + +Bada Quirks +----------- +__filter:__ Property can only apply to the following: "firstName", "lastName", "nickname", "phoneNumber", "email", "address" http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/ContactName/contactname.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/ContactName/contactname.md b/docs/en/1.9.0rc1/cordova/contacts/ContactName/contactname.md new file mode 100644 index 0000000..3a5199b --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/ContactName/contactname.md @@ -0,0 +1,145 @@ +--- +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. +--- + +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 +- Bada 1.2 & 2.0 + +Quick Example +------------- + + function onSuccess(contacts) { + for (var i=0; i + + + Contact Example + + + + + +

Example

+

Find Contacts

+ + + +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. + +Bada Quirks +----------- +- __formatted:__ Property not supported +- __middleName:__ Property not supported +_ __honorificPrefix:__ Property not supported +- __honorificSuffix:__ Property not supported http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/ContactOrganization/contactorganization.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/ContactOrganization/contactorganization.md b/docs/en/1.9.0rc1/cordova/contacts/ContactOrganization/contactorganization.md new file mode 100644 index 0000000..34f7dc9 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/ContactOrganization/contactorganization.md @@ -0,0 +1,153 @@ +--- +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. +--- + +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 +- Bada 1.2 + +Quick Example +------------- + + function onSuccess(contacts) { + for (var i=0; i + + + Contact Example + + + + + +

Example

+

Find Contacts

+ + + + +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. + +Bada 2.0 Quirks +--------------- +- ContactOrganization not supported http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/contacts.create.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/contacts.create.md b/docs/en/1.9.0rc1/cordova/contacts/contacts.create.md new file mode 100644 index 0000000..1ab4a75 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/contacts.create.md @@ -0,0 +1,77 @@ +--- +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. +--- + +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 +- Bada 1.2 & 2.0 + +Quick Example +------------- + + var myContact = navigator.contacts.create({"displayName": "Test User"}); + +Full Example +------------ + + + + + Contact Example + + + + + +

Example

+

Create Contact

+ + http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/contacts.find.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/contacts.find.md b/docs/en/1.9.0rc1/cordova/contacts/contacts.find.md new file mode 100644 index 0000000..424478f --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/contacts.find.md @@ -0,0 +1,116 @@ +--- +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. +--- + +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 +- Bada 1.2 & 2.0 + +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 +------------ + + + + + Contact Example + + + + + +

Example

+

Find Contacts

+ + + + http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/contacts.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/contacts.md b/docs/en/1.9.0rc1/cordova/contacts/contacts.md new file mode 100644 index 0000000..c5db19d --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/contacts.md @@ -0,0 +1,108 @@ +--- +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. +--- + +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 + +Permissions +----------- + +### Android + +#### app/res/xml/plugins.xml + + + +#### app/AndroidManifest.xml + + + + + +### Bada + +#### manifest.xml + + + ADDRESSBOOK + + +### BlackBerry WebWorks + +#### www/plugins.xml + + + +#### www/config.xml + + + + + + +### iOS + +#### App/Supporting Files/Cordova.plist + + Plugins + + Contacts + CDVContacts + + +### webOS + + No permissions are required. + +### Windows Phone + +#### Properties/WPAppManifest.xml + + + + + +Reference: [Application Manifest for Windows Phone](http://msdn.microsoft.com/en-us/library/ff769509%28v=vs.92%29.aspx) http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/f14a877d/docs/en/1.9.0rc1/cordova/contacts/parameters/contactError.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/parameters/contactError.md b/docs/en/1.9.0rc1/cordova/contacts/parameters/contactError.md new file mode 100644 index 0000000..6b50ddc --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/parameters/contactError.md @@ -0,0 +1,27 @@ +--- +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. +--- + +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/f14a877d/docs/en/1.9.0rc1/cordova/contacts/parameters/contactFields.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/parameters/contactFields.md b/docs/en/1.9.0rc1/cordova/contacts/parameters/contactFields.md new file mode 100644 index 0000000..66c9d3d --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/parameters/contactFields.md @@ -0,0 +1,25 @@ +--- +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. +--- + +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/f14a877d/docs/en/1.9.0rc1/cordova/contacts/parameters/contactFindOptions.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/parameters/contactFindOptions.md b/docs/en/1.9.0rc1/cordova/contacts/parameters/contactFindOptions.md new file mode 100644 index 0000000..2eb9afc --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/parameters/contactFindOptions.md @@ -0,0 +1,35 @@ +--- +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. +--- + +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/f14a877d/docs/en/1.9.0rc1/cordova/contacts/parameters/contactSuccess.md ---------------------------------------------------------------------- diff --git a/docs/en/1.9.0rc1/cordova/contacts/parameters/contactSuccess.md b/docs/en/1.9.0rc1/cordova/contacts/parameters/contactSuccess.md new file mode 100644 index 0000000..9068218 --- /dev/null +++ b/docs/en/1.9.0rc1/cordova/contacts/parameters/contactSuccess.md @@ -0,0 +1,40 @@ +--- +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. +--- + +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 + + + Device Properties Example + + + + + +

Loading device properties...

+ + +