You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ni...@apache.org on 2016/05/09 17:14:26 UTC
cordova-plugin-contacts git commit: Add fenced code blocks - with
language hints
Repository: cordova-plugin-contacts
Updated Branches:
refs/heads/master e4d72c341 -> 9697d7912
Add fenced code blocks - with language hints
This closes #124
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts/commit/9697d791
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts/tree/9697d791
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts/diff/9697d791
Branch: refs/heads/master
Commit: 9697d791276e5991d44dee7b8d4505a80875a6ab
Parents: e4d72c3
Author: Nikhil Khandelwal <ni...@microsoft.com>
Authored: Thu Apr 28 13:42:32 2016 -0700
Committer: Nikhil Khandelwal <ni...@microsoft.com>
Committed: Mon May 9 10:13:15 2016 -0700
----------------------------------------------------------------------
README.md | 339 ++++++++++++++++++++++++++++++---------------------------
1 file changed, 181 insertions(+), 158 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts/blob/9697d791/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 921a14a..5f931ee 100644
--- a/README.md
+++ b/README.md
@@ -28,11 +28,12 @@ description: Manage the contacts on the device.
This plugin defines a global `navigator.contacts` object, which provides access to the device contacts database.
Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.
-
- document.addEventListener("deviceready", onDeviceReady, false);
- function onDeviceReady() {
- console.log(navigator.contacts);
- }
+```js
+document.addEventListener("deviceready", onDeviceReady, false);
+function onDeviceReady() {
+console.log(navigator.contacts);
+}
+```
__WARNING__: Collection and use of contact data raises
important privacy issues. Your app's privacy policy should discuss
@@ -74,14 +75,15 @@ Add relevant permisions.
There is also a need to change the webapp type to "privileged" - [Manifest Docs](https://developer.mozilla.org/en-US/Apps/Developing/Manifest#type).
__WARNING__: All privileged apps enforce [Content Security Policy](https://developer.mozilla.org/en-US/Apps/CSP) which forbids inline script. Initialize your application in another way.
- "type": "privileged",
- "permissions": {
- "contacts": {
- "access": "readwrite",
- "description": "Describe why there is a need for such permission"
- }
+```json
+"type": "privileged",
+"permissions": {
+ "contacts": {
+ "access": "readwrite",
+ "description": "Describe why there is a need for such permission"
}
-
+}
+```
### Windows Quirks
**Prior to Windows 10:** Any contacts returned from `find` and `pickContact` methods are readonly, so your application cannot modify them.
@@ -130,7 +132,9 @@ database, for which you need to invoke the `Contact.save` method.
### Example
+```js
var myContact = navigator.contacts.create({"displayName": "Test User"});
+```
## navigator.contacts.find
@@ -184,22 +188,24 @@ Supported values for both __contactFields__ and __contactFindOptions.desiredFiel
### 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";
- options.multiple = true;
- options.desiredFields = [navigator.contacts.fieldType.id];
- options.hasPhoneNumber = true;
- var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
- navigator.contacts.find(fields, onSuccess, onError, options);
+```js
+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";
+options.multiple = true;
+options.desiredFields = [navigator.contacts.fieldType.id];
+options.hasPhoneNumber = true;
+var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
+navigator.contacts.find(fields, onSuccess, onError, options);
+```
### Windows Quirks
@@ -226,11 +232,13 @@ function specified by the __contactSuccess__ parameter.
### Example
- navigator.contacts.pickContact(function(contact){
- console.log('The following contact has been selected:' + JSON.stringify(contact));
- },function(err){
- console.log('Error: ' + err);
- });
+```js
+navigator.contacts.pickContact(function(contact){
+ console.log('The following contact has been selected:' + JSON.stringify(contact));
+ },function(err){
+ console.log('Error: ' + err);
+ });
+```
### Android Quirks
@@ -315,75 +323,82 @@ for details.
### Save Example
- function onSuccess(contact) {
- alert("Save Success");
- };
+```js
+function onSuccess(contact) {
+ alert("Save Success");
+};
- function onError(contactError) {
- alert("Error = " + contactError.code);
- };
+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
+// 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;
+// populate some fields
+var name = new ContactName();
+name.givenName = "Jane";
+name.familyName = "Doe";
+contact.name = name;
- // save to device
- contact.save(onSuccess,onError);
+// save to device
+contact.save(onSuccess,onError);
+```
### Clone 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);
+```js
+// 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 Example
- function onSuccess() {
- alert("Removal Success");
- };
-
- function onError(contactError) {
- alert("Error = " + contactError.code);
- };
+```js
+function onSuccess() {
+ alert("Removal Success");
+};
- // remove the contact from the device
- contact.remove(onSuccess,onError);
+function onError(contactError) {
+ alert("Error = " + contactError.code);
+};
+// remove the contact from the device
+contact.remove(onSuccess,onError);
+```
### Removing phone number(s) from a saved contact
- // Example to create a contact with 3 phone numbers and then remove
- // 2 phone numbers. This example is for illustrative purpose only
- var myContact = navigator.contacts.create({"displayName": "Test User"});
- var phoneNumbers = [];
-
- phoneNumbers[0] = new ContactField('work', '768-555-1234', false);
- phoneNumbers[1] = new ContactField('mobile', '999-555-5432', true); // preferred number
- phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
-
- myContact.phoneNumbers = phoneNumbers;
- myContact.save(function (contact_obj) {
- var contactObjToModify = contact_obj.clone();
- contact_obj.remove(function(){
- var phoneNumbers = [contactObjToModify.phoneNumbers[0]];
- contactObjToModify.phoneNumbers = phoneNumbers;
- contactObjToModify.save(function(c_obj){
- console.log("All Done");
- }, function(error){
- console.log("Not able to save the cloned object: " + error);
- });
- }, function(contactError) {
- console.log("Contact Remove Operation failed: " + contactError);
+```js
+// Example to create a contact with 3 phone numbers and then remove
+// 2 phone numbers. This example is for illustrative purpose only
+var myContact = navigator.contacts.create({"displayName": "Test User"});
+var phoneNumbers = [];
+
+phoneNumbers[0] = new ContactField('work', '768-555-1234', false);
+phoneNumbers[1] = new ContactField('mobile', '999-555-5432', true); // preferred number
+phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
+
+myContact.phoneNumbers = phoneNumbers;
+myContact.save(function (contact_obj) {
+ var contactObjToModify = contact_obj.clone();
+ contact_obj.remove(function(){
+ var phoneNumbers = [contactObjToModify.phoneNumbers[0]];
+ contactObjToModify.phoneNumbers = phoneNumbers;
+ contactObjToModify.save(function(c_obj){
+ console.log("All Done");
+ }, function(error){
+ console.log("Not able to save the cloned object: " + error);
});
+ }, function(contactError) {
+ console.log("Contact Remove Operation failed: " + contactError);
});
+});
+```
### Android 2.X Quirks
@@ -483,33 +498,35 @@ a `ContactAddress[]` array.
### 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);
- }
+```js
+// 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 = "";
- options.multiple = true;
- var filter = ["displayName", "addresses"];
- navigator.contacts.find(filter, onSuccess, onError, options);
+ }
+};
+
+function onError(contactError) {
+ alert('onError!');
+};
+
+// find all contacts
+var options = new ContactFindOptions();
+options.filter = "";
+options.multiple = true;
+var filter = ["displayName", "addresses"];
+navigator.contacts.find(filter, onSuccess, onError, options);
+```
### Android 2.X Quirks
@@ -607,18 +624,20 @@ string.
### Example
- // create a new contact
- var contact = navigator.contacts.create();
+```js
+// 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;
+// 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();
+// save the contact
+contact.save();
+```
### Android Quirks
@@ -671,26 +690,28 @@ Contains different kinds of information about a `Contact` object's name.
### 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);
- }
- };
+```js
+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!');
- };
+function onError(contactError) {
+ alert('onError!');
+};
- var options = new ContactFindOptions();
- options.filter = "";
- options.multiple = true;
- filter = ["displayName", "name"];
- navigator.contacts.find(filter, onSuccess, onError, options);
+var options = new ContactFindOptions();
+options.filter = "";
+options.multiple = true;
+filter = ["displayName", "name"];
+navigator.contacts.find(filter, onSuccess, onError, options);
+```
### Android Quirks
@@ -764,27 +785,29 @@ properties. A `Contact` object stores one or more
### 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);
- }
+```js
+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!');
- };
+function onError(contactError) {
+ alert('onError!');
+};
- var options = new ContactFindOptions();
- options.filter = "";
- options.multiple = true;
- filter = ["displayName", "organizations"];
- navigator.contacts.find(filter, onSuccess, onError, options);
+var options = new ContactFindOptions();
+options.filter = "";
+options.multiple = true;
+filter = ["displayName", "organizations"];
+navigator.contacts.find(filter, onSuccess, onError, options);
+```
### Android 2.X Quirks
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org