cordova-plugin-contacts - npm Package Compare versions

Comparing version 0.2.10 to 0.2.11

doc/index.md

@@ -61,2 +61,7 @@ <!---
 
+### Windows 8 Quirks
+
+Windows 8 Contacts are readonly. Via the Cordova API Contacts are not queryable/searchable, you should inform the user to pick a contact as a call to contacts.pickContact which will open the 'People' app where the user must choose a contact.
+Any contacts returned are readonly, so your application cannot modify them.
+
 ## navigator.contacts
@@ -68,2 +73,3 @@
 - navigator.contacts.find
+- navigator.contacts.pickContact
 
@@ -79,2 +85,3 @@ ### Objects
 - ContactError
+- ContactFieldType
 
@@ -95,5 +102,2 @@ ## navigator.contacts.create
 - Windows Phone 7 and 8
-- Windows 8 ( Note: Windows 8 Contacts are readonly via the Cordova API
-Contacts are not queryable/searchable, you should inform the user to pick a contact as a call to contacts.find will open the 'People' app where the user must choose a contact.
-Any contacts returned are readonly, so your application cannot modify them. )
 
@@ -112,5 +116,3 @@ ### Example
 The __contactFields__ parameter specifies the fields to be used as a
-search qualifier, and only those results are passed to the
-__contactSuccess__ callback function.  A zero-length __contactFields__
-parameter is invalid and results in
+search qualifier.  A zero-length __contactFields__ parameter is invalid and results in
 `ContactError.INVALID_ARGUMENT_ERROR`. A __contactFields__ value of
@@ -123,8 +125,7 @@ `"*"` returns all contact fields.
 specified in the __contactFields__ parameter.  If there's a match for
-_any_ of the specified fields, the contact is returned.
+_any_ of the specified fields, the contact is returned. Use __contactFindOptions.desiredFields__
+parameter to control which contact properties must be returned back.
 
 ### Parameters
 
-- __contactFields__: Contact fields to use as a search qualifier. The resulting `Contact` object only features values for these fields. _(DOMString[])_ [Required]
-
 - __contactSuccess__: Success callback function invoked with the array of Contact objects returned from the database. [Required]
@@ -134,2 +135,4 @@
 
+- __contactFields__: Contact fields to use as a search qualifier. _(DOMString[])_ [Required]
+
 - __contactFindOptions__: Search options to filter navigator.contacts. [Optional] Keys include:
@@ -141,2 +144,4 @@
 
+    - __desiredFields__: Contact fields to be returned back. If specified, the resulting `Contact` object only features values for these fields. _(DOMString[])_ [Optional]
+
 ### Supported Platforms
@@ -149,3 +154,2 @@
 - Windows Phone 7 and 8
-- Windows 8 ( read-only support, search requires user interaction, contactFields are ignored, only contactFindOptions.multiple is used to enable the user to select 1 or many contacts. )
 
@@ -166,6 +170,33 @@ ### Example
     options.multiple = true;
-    var fields       = ["displayName", "name"];
-    navigator.contacts.find(fields, onSuccess, onError, options);
+    options.desiredFields = [navigator.contacts.fieldType.id];
+    var fields       = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
+    navigator.contacts.find(onSuccess, onError, fields, options);
 
+## navigator.contacts.pickContact
 
+The `navigator.contacts.pickContact` method launches the Contact Picker to select a single contact.
+The resulting object is passed to the `contactSuccess` callback
+function specified by the __contactSuccess__ parameter.
+
+### Parameters
+
+- __contactSuccess__: Success callback function invoked with the single Contact object. [Required]
+
+- __contactError__: Error callback function, invoked when an error occurs. [Optional]
+
+### Supported Platforms
+
+- Android
+- iOS
+- Windows Phone 8
+- Windows 8
+
+### Example
+
+    navigator.contacts.pickContact(function(contact){
+            console.log('The following contact has been selected:' + JSON.stringify(contact));
+        },function(err){
+            console.log('Error: ' + err);
+        });
+
 ## Contact
@@ -229,2 +260,3 @@
 - Windows Phone 7 and 8
+- Windows 8
 
@@ -367,3 +399,3 @@ ### Save Example
     function onSuccess(contacts) {
-        for (var i = 0; i < navigator.contacts.length; i++) {
+        for (var i = 0; i < contacts.length; i++) {
             for (var j = 0; j < contacts[i].addresses.length; j++) {
@@ -440,9 +472,9 @@ alert("Pref: "         + contacts[i].addresses[j].pref          + "\n" +
 
-- `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`
+- `ContactError.UNKNOWN_ERROR` (code 0)
+- `ContactError.INVALID_ARGUMENT_ERROR` (code 1)
+- `ContactError.TIMEOUT_ERROR` (code 2)
+- `ContactError.PENDING_OPERATION_ERROR` (code 3)
+- `ContactError.IO_ERROR` (code 4)
+- `ContactError.NOT_SUPPORTED_ERROR` (code 5)
+- `ContactError.PERMISSION_DENIED_ERROR` (code 20)
 
@@ -553,3 +585,3 @@
     function onSuccess(contacts) {
-        for (var i = 0; i < navigator.contacts.length; i++) {
+        for (var i = 0; i < contacts.length; i++) {
             alert("Formatted: "  + contacts[i].name.formatted       + "\n" +
@@ -645,3 +677,3 @@ "Family Name: "  + contacts[i].name.familyName      + "\n" +
     function onSuccess(contacts) {
-        for (var i = 0; i < navigator.contacts.length; i++) {
+        for (var i = 0; i < contacts.length; i++) {
             for (var j = 0; j < contacts[i].organizations.length; j++) {
@@ -648,0 +680,0 @@ alert("Pref: "      + contacts[i].organizations[j].pref       + "\n" +

package.json

 {
     "name": "cordova-plugin-contacts",
-    "version": "0.2.10",
+    "version": "0.2.11",
     "description": "Cordova Contacts Plugin",
@@ -5,0 +5,0 @@ "cordova": {

RELEASENOTES.md

@@ -85,1 +85,14 @@ <!--
 * Add NOTICE file
+
+### 0.2.11 (Jun 05, 2014)
+* CB-6127 Spanish and French Translations added. Github close #25
+* Remove deprecated symbols for iOS < 6
+* CB-6797 Add license
+* [wp8] now pupulates contact photos
+* Update license headers format
+* Add pickContact functionality to cordova contacts plugin
+* CB-5416 - Adding support for auto-managing permissions
+* CB-6682 move windows8 command proxy into it's missing platform tag. This closes #30
+* Add ContactError codes to index.md doc (closes #28)
+* CB-6491 add CONTRIBUTING.md
+* Docs typo: navigator.contacts.length -> contacts.length

src/windows8/ContactProxy.js

@@ -1,2 +0,1 @@
-//cordova.define("org.apache.cordova.contacts.ContactProxy", function (require, exports, module) {
 /*
@@ -20,118 +19,84 @@ *
  * under the License.
- *
-*/
+ * 
+ */
 
+var ContactField = require('./ContactField'),
+    ContactAddress = require('./ContactAddress'),
+    ContactName = require('./ContactName'),
+    Contact = require('./Contact');
 
-module.exports = {
-    search:function(win,fail,args){
-        var fields = args[0]; // ignored, always returns entire object
-        var options = args[1];
 
-        var filter = options.filter;   // ignored
-        var multiple = true;//options.multiple;
+function convertToContact(windowsContact) {
+    var contact = new Contact();
 
-        var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
-        picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.contacts;   // select entire contact
-        if (picker.pickContactAsync) {
-            // TODO: 8.1 has better contact support via the 'Contact' object
-        }
-        else {
-            // 8.0 use the ContactInformation class
-            // decide which function we will call
-            var pickerFunkName = multiple ? 'pickMultipleContactsAsync' : 'pickSingleContactAsync';
-            picker[pickerFunkName]().done(function (res) {
-                if (!res) {
-                    fail && setTimeout(function () {
-                        fail(new Error("User did not pick a contact."));
-                    }, 0);
-                    return;
-                }
+    // displayName & nickname
+    contact.displayName = windowsContact.name;
+    contact.nickname = windowsContact.name;
 
-                var contactResults = [];
+    // name
+    contact.name = new ContactName(windowsContact.name);
 
-                for (var i = 0; i < res.length; i++) {
+    // phoneNumbers
+    contact.phoneNumbers = [];
+    for (var i = 0; i < windowsContact.phoneNumbers.size; i++) {
+        var phone = new ContactField(windowsContact.phoneNumbers[i].category, windowsContact.phoneNumbers[i].value);
+        contact.phoneNumbers.push(phone);
+    }
 
+    // emails
+    contact.emails = [];
+    for (var i = 0; i < windowsContact.emails.size; i++) {
+        var email = new ContactField(windowsContact.emails[i].category, windowsContact.emails[i].value);
+        contact.emails.push(email);
+    }
 
-                    var index,
-                        contactResult = res[i],
-                        contact = {
-                            id: "",
-                            name: { formatted: contactResult.name },  // ContactName
-                            displayName: contactResult.name,          // DOMString
-                            nickname: contactResult.name,             // DOMString
-                            phoneNumbers: contactResult.phoneNumbers, // ContactField[]
-                            addresses: contactResult.locations,       // ContactAddress[]
-                            emails: [],                               // ContactField
-                            ims: contactResult.instantMessages,       // ContactField[]
-                            organizations: [],              // ContactOrganization[]
-                            birthday: null,                 // Date
-                            note: "",                       // DOMString
-                            photos: [],                     // ContactField[]
-                            categories: [],                 // ContactField[]
-                            urls: []                        // ContactField[]
-                        };
+    // addressres
+    contact.addresses = [];
+    for (var i = 0; i < windowsContact.locations.size; i++) {
+        var address = new ContactAddress(null, windowsContact.locations[i].category,
+            windowsContact.locations[i].unstructuredAddress, windowsContact.locations[i].street,
+            null, windowsContact.locations[i].region, windowsContact.locations[i].postalCode,
+            windowsContact.locations[i].country);
+        contact.addresses.push(address);
+    }
 
-                    // Win8-ContactField is {category, name, type, value};
-                    // Cordova ContactField is {type,value, pref:bool };
-                    // Win8 type means 'email' cordova type means 'work|home|...' so we convert them
-                    if (contact.emails && contact.emails.length) {
-                        contact.emails[0].pref = true; // add a preferred prop 
-                        for (index = 0; index < contacts.emails.length; index++) {
-                            contact.emails[index].type = contact.emails[index].category;
-                        }
-                    }
+    // ims
+    contact.ims = [];
+    for (var i = 0; i < windowsContact.instantMessages.size; i++) {
+        var im = new ContactField(windowsContact.instantMessages[i].category, windowsContact.instantMessages[i].userName);
+        contact.ims.push(im);
+    }
 
-                    if (contact.phoneNumbers && contact.phoneNumbers.length) {
-                        contact.phoneNumbers[0].pref = true; // cordova contact field needs a 'prefered' property on  a contact
-                        // change the meaning of type from 'telephonenumber' to 'work|home|...'
-                        for (index = 0; index < contact.phoneNumbers.length; index++) {
-                            contact.phoneNumbers[index].type = contact.phoneNumbers[index].category;
-                        }
-                    }
+    return contact;
+};
 
-                    if (contact.addresses && contact.addresses.length) {
+module.exports = {
+    pickContact: function(win, fail, args) {
 
-                        // convert addresses/locations to Cordova.ContactAddresses                    
-                        // constr: ContactAddress(pref, type, formatted, streetAddress, locality, region, postalCode, country)
-                        var address, formatted;
-                        for (index = 0; index < contact.addresses.length; index++) {
-                            address = contact.addresses[index];   // make an alias
-                            var formattedArray = [];
-                            // get rid of the empty fields.
-                            var fields = [address.street, address.city, address.region, address.country, address.postalCode];
-                            for (var n = 0; n < fields.length; n++) {
-                                if (fields[n].length > 0) {
-                                    formattedArray.push(fields[n]);
-                                }
-                            }
-                            formattedAddress = formattedArray.join(", ");
-                            console.log(contact.name.formatted + " formatted looks like " + formattedAddress);
-                            contact.addresses[index] = new ContactAddress(false,
-                                                                          address.name,
-                                                                          formattedAddress,
-                                                                          address.street,
-                                                                          address.city,
-                                                                          address.region,
-                                                                          address.postalCode,
-                                                                          address.country);
-                        }
+        var picker = new Windows.ApplicationModel.Contacts.ContactPicker();
+        picker.selectionMode = Windows.ApplicationModel.Contacts.ContactSelectionMode.contacts; // select entire contact
 
-                    }
+        // pickContactAsync is available on Windows 8.1 or later, instead of
+        // pickSingleContactAsync, which is deprecated after Windows 8,
+        // so try to use newer method, if available.
+        // see http://msdn.microsoft.com/en-us/library/windows/apps/windows.applicationmodel.contacts.contactpicker.picksinglecontactasync.aspx
+        if (picker.pickContactAsync) {
+            // TODO: 8.1 has better contact support via the 'Contact' object
+        } else {
 
-                    // convert ims to ContactField
-                    if (contact.ims && contact.ims.length) {
-                        // MS ContactInstantMessageField has : displayText, launchUri, service, userName, category, type
-                        contact.ims[0].pref = true;
-                        for (index = 0; index < contact.ims.length; index++) {
-                            contact.ims[index] = new ContactField(contact.ims[index].type, contact.ims[index].value, false);
-                        }
-                    }
+            function success(con) {
+                // if contact was not picked
+                if (!con) {
+                    fail && setTimeout(function() {
+                        fail(new Error("User did not pick a contact."));
+                    }, 0);
+                    return;
+                }
 
-                    contactResults.push(contact);
-
-                }
                 // send em back
-                win(contactResults);
+                win(convertToContact(con));
 
-            });
+            }
+
+            picker.pickSingleContactAsync().done(success, fail);
         }
@@ -145,3 +110,9 @@ },
         }, 0);
+    },
 
+    search: function(win, fail, args) {
+        console && console.error && console.error("Error : Windows 8 does not support searching contacts");
+        fail && setTimeout(function() {
+            fail(new Error("Contact search not supported on Windows 8"));
+        }, 0);
     }
@@ -153,2 +124,1 @@
 require("cordova/exec/proxy").add("Contacts", module.exports);
-// });

www/ContactFindOptions.js

@@ -29,7 +29,8 @@ /*
 
-var ContactFindOptions = function(filter, multiple) {
+var ContactFindOptions = function(filter, multiple, desiredFields) {
     this.filter = filter || '';
     this.multiple = (typeof multiple != 'undefined' ? multiple : false);
+    this.desiredFields = typeof desiredFields != 'undefined' ? desiredFields : [];
 };
 
 module.exports = ContactFindOptions;

www/contacts.js

@@ -26,3 +26,5 @@ /*
     utils = require('cordova/utils'),
-    Contact = require('./Contact');
+    Contact = require('./Contact'),
+    fieldType = require('./ContactFieldType');
+    
 
@@ -34,2 +36,3 @@ /**
 var contacts = {
+    fieldType: fieldType,
     /**
@@ -43,4 +46,4 @@ * Returns an array of Contacts matching the search criteria.
      */
-    find:function(fields, successCB, errorCB, options) {
-        argscheck.checkArgs('afFO', 'contacts.find', arguments);
+    find:function(successCB, errorCB, fields, options) {
+        argscheck.checkArgs('fFaO', 'contacts.find', arguments);
         if (!fields.length) {
@@ -59,3 +62,20 @@ errorCB && errorCB(new ContactError(ContactError.INVALID_ARGUMENT_ERROR));
     },
+    
+    /**
+     * This function picks contact from phone using contact picker UI
+     * @returns new Contact object
+     */
+    pickContact: function (successCB, errorCB) {
 
+        argscheck.checkArgs('fF', 'contacts.pick', arguments);
+
+        var win = function (result) {
+            // if Contacts.pickContact return instance of Contact object
+            // don't create new Contact object, use current
+            var contact = result instanceof Contact ? result : contacts.create(result);
+            successCB(contact);
+        };
+        exec(win, errorCB, "Contacts", "pickContact", []);
+    },
+
     /**
@@ -62,0 +82,0 @@ * This function creates a new contact, but it does not persist the contact

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

660677

increased by54.74%

Number of package files

57

increased by35.71%

Lines of code

2204

increased by1.8%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes