isabella232 / cordova-plugin-intel-xdk-contacts

DISCONTINUATION OF PROJECT. This project will no longer be maintained by Intel. Intel will not provide or guarantee development of or support for this project, including but not limited to, maintenance, bug fixes, new releases or updates. Patches to this project are no longer accepted by Intel. In an effort to support the developer community, Intel has made this project available under the terms of the Apache License, Version 2. If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the community, please create your own fork of the project.

intel.xdk.contacts

For access to the on-device contacts database.

Description

The contacts plugin gives programmers access to the default contacts database on the native device. The application must be built with appropriate permissions in order for this capability to work.

Contact Objects

The plugin vends “contact objects” which represent entries in the native contacts database. Each contact object has the following properties:

• id: An identifier which is unique to this contact, and which can be used to refer to it in plugin method calls. It may be either a number or a string, depending on the platform.
• last: A string containing the last name of the person.
• first: A string containing the first name of the person.
• name: A string containing the entire name of the person. (Not necessarily just the concatenation of the first and last names.)
• emails: An array of strings containing email addresses.
• phones: An array of strings containing phone numbers.
• addresses: An array of objects representing addresses.

An address object has the following properties:

• street: A string containing the street address. (May contain multiple lines separated by line-feed characters.)
• city: A string containing the city name.
• state: A string containing a state or province name or abbreviation.
• zip: A string containing a zip or postal code.
• country: A string containing a country name or abbreviation.

The Internal Contact List

The plugin keeps an internal contact list, which is a cached copy of the device contacts database. The internal contact list is not initialized automatically, and a call to getContactList or getContactData will return null if it has not been initialized.

The internal contact list may be explicitly initialized by a call to getContacts, or implicitly initialized or updated by a successful call to addContact, chooseContact, editContact, or removeContact.

Note that a change to the device contacts database made other than through the plugin will not be reflected in the internal contact list until it is initialized or updated.

Methods

Note that methods that access or manipulate the contacts database may present the platform native interface for that functionality.

• addContact — Allow the user to add a contact.
• chooseContact — Allow the user to choose a contact.
• editContact — Allow the user to edit a contact.
• getContactData — Return the contact object with a particular identifier.
• getContactList — Return an array of the identifiers of all contacts in the database.
• getContacts — Fetch the device contact database into the plugin.
• removeContact — Remove a specified contact.

Events

• intel.xdk.contacts.add — The user has added a contact.
• intel.xdk.contacts.busy — An operation was requested when another operation was already in progress.
• intel.xdk.contacts.choose — The user has selected a contact.
• intel.xdk.contacts.edit — The user has finished editing a contact.
• intel.xdk.contacts.get — The device contact database has been fetched into the plugin.
• intel.xdk.contacts.remove — A contact has been removed.

Methods

addContact

Invokes the system “add contact” dialog.

intel.xdk.contacts.addContact();

Description

This method displays the native device’s UI to allow the user to add a new contact.

Platforms

• Apple iOS
• Google Android

Events

• intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database.
• intel.xdk.contacts.busy: Some other contacts action has been initiated and is not yet complete.
• intel.xdk.contacts.add(success, contactid): If success is true, then the user added a new contact whose id is contactid. If success is false, the user cancelled the dialog, and contactid is undefined.

Note: If the internal contact list was uninitialized before the call and the user canceled the add operation (i.e., success was false), then the internal contact list is still uninitialized.

Example

document.addEventListener('intel.xdk.contacts.add', onContactAdded);

intel.xdk.contacts.addContact();

function onContactAdded(evt) {
   if (evt.success == true)
   {
      alert("Contact "+evt.contactid+" successfully added");
   }
   else
   {
      alert("Add Contact Cancelled");
   }

chooseContact

Invokes the system “choose contact” dialog.

intel.xdk.contacts.chooseContact();

Description

This method displays the native device’s UI to allow the user to choose a contact from the contact database.

Available Platforms

• Apple iOS
• Google Android
• Microsoft Windows 8 - BETA
• Microsoft Windows Phone 8 - BETA

Events

• intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database.
• intel.xdk.contacts.busy: Some other contacts action has been initiated and is not yet complete.
• intel.xdk.contacts.choose(success, contactid): If success is true, then the selected the contact whose id is contactid. If success is false, the user cancelled the dialog, and contactid is undefined.

Note: If the internal contact list was uninitialized before the call and the user canceled the choose operation (i.e., success was false), then the internal contact list is still uninitialized.

Example

document.addEventListener('intel.xdk.contacts.choose', onChooseContact);

intel.xdk.contacts.chooseContact();

function onChooseContact(evt) {
   if (evt.success == true)
   {
      intel.xdk.contacts.editContact(evt.contactid);
   }
   else
   {
      alert("Choose Contact Cancelled");
   }

editContact

Invokes the system “edit contact” dialog.

intel.xdk.contacts.editContact(contactID);

Description

This method displays the native device's contacts application to allow the user to edit a specified contact.

Platforms

• Apple iOS
• Google Android

Parameters

• contactID: The contact ID of the contact to be edited.

Events

• intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database.
• intel.xdk.contacts.busy: Some other contacts action has been initiated and is not yet complete.
• intel.xdk.contacts.edit(success, contactid): If success is true, then the edited the contact whose id is contactid. If success is false, the user cancelled the dialog. In either case, contactid is the same as the contactID from the edit call.

Note: If the internal contact list was uninitialized before the call and the user canceled the edit operation (i.e., success was false), then the internal contact list is still uninitialized.

Example

document.addEventListener('intel.xdk.contacts.edit', onContactEdit);

intel.xdk.contacts.editContact(contactID);

function onEditContact(evt) {
   if (evt.success == true)
   {
      alert("Contact "+evt.contactid+" successfully updated");
   }
   else
   {
      alert("Edit Contact Cancelled");
   }

getContactData

Get a specified contact object.

contactObj = intel.xdk.contacts.getContactData(contactID);

Description

This method gets the contact object with a specified contact id.

Available Platforms

• Apple iOS
• Google Android
• Microsoft Windows 8 - BETA
• Microsoft Windows Phone 8 - BETA

Parameters

• contactID: The contact ID of the contact to be fetched.

Returns

• The contact object in the internal contact list whose id property is contactID.
• null if the internal contact list has not been initialized, or does not contain a contact object with the specified contact ID.

Example

function contactsReceived() {
    var table = document.getElementById("contacts");
    table.innerHTML = '';

    var myContacts = intel.xdk.contacts.getContactList();

    for(var i=0;i<myContacts.length;i++) {
        //add row to table
        var contactInfo =
            intel.xdk.contacts.getContactData(myContacts[i]);
        var tr = document.createElement("tr");
        tr.setAttribute('id', 'pnid'+contactInfo.id);
        tr.setAttribute('onClick',
            'document.getElementById("iden").value =
            '+contactInfo.id+';');
        tr.setAttribute('style', 'background-color:#B8BFD8');
        var id = document.createElement("td");
        id.innerHTML = contactInfo.id;
        tr.appendChild(id);
        var msg = document.createElement("td");
        msg.innerHTML = contactInfo.name;
        tr.appendChild(msg);
        table.appendChild(tr);
    }
}

getContactList

Get all the contact IDs.

contactListArray = intel.xdk.contacts.getContactList();

Description

This method gets an array containing the contact ID property of every contact object.

Available Platforms

• Apple iOS
• Google Android
• Microsoft Windows 8 - BETA
• Microsoft Windows Phone 8 - BETA

Returns

• An array containing the contact ID property of every contact object.
• null if the internal contact list has not been initialized.

Example

document.addEventListener('intel.xdk.contacts.get', contactsReceived, false);

function contactsReceived() {
    var table = document.getElementById("contacts");
    table.innerHTML = '';

    var myContacts = intel.xdk.contacts.getContactList();

    for(var i=0;i<myContacts.length;i++) {
        //add row to table
        var contactInfo = intel.xdk.contacts.getContactData(myContacts[i]);
        var tr = document.createElement("tr");
        tr.setAttribute('id', 'pnid'+contactInfo.id);
        tr.setAttribute('onClick', 'document.getElementById("iden").value =
            '+contactInfo.id+';');
        tr.setAttribute('style', 'background-color:#B8BFD8');
        var id = document.createElement("td");
        id.innerHTML = contactInfo.id;
        tr.appendChild(id);
        var msg = document.createElement("td");
        msg.innerHTML = contactInfo.name;
        tr.appendChild(msg);
        table.appendChild(tr);
    }
}

getContacts

Initialize the plugin internal contact list from the device contacts database.

intel.xdk.contacts.getContacts();

Description

This plugin maintains an internal copy of the device contacts database. The getContactList and getContactData methods retrieve information from the internal contact list, not directly from the device database. Therefore, the internal copy must be initialized from the system database before getContactList or getContactData is called. That initialization can occur explicitly with a call to this method, or implicitly with a successful call to addContact, removeContact, chooseContact, or editContact.

Available Platforms

• Apple iOS
• Google Android
• Microsoft Windows 8 - BETA
• Microsoft Windows Phone 8 - BETA

Events

• intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database. The internal list has not been initialized.
• intel.xdk.contacts.get(success): The internal contact list has been initialized. success will always be true.

Example

document.addEventListener('intel.xdk.contacts.get', contactsReceived, false);

intel.xdk.contacts.getContacts();

removeContact

Remove a contact.

intel.xdk.contacts.removeContact(contactID);

Description

This method removes a specified contact.

Platforms

• Apple iOS
• Google Android

Parameters

• contactID: The contact ID of the contact to remove

Events

• intel.xdk.contacts.permissionDenied: The application does not have permission to access the system contacts database.
• intel.xdk.contacts.busy: Some other contacts action has been initiated and is not yet complete.
• intel.xdk.contacts.remove(success, contactid, error): If success is true, then the contact whose id is contactid has been removed. If success is false, the contacts database has not been changed, and error is a string describing the reason the contact was not removed.

Note: If the internal contact list was uninitialized before the call and the remove operation failed for any reason (i.e., success was false), then the internal contact list is still uninitialized.

Example

document.addEventListener('intel.xdk.contacts.remove', onContactRemoved);

intel.xdk.contacts.removeContact(contactID);

function onEditContact(evt) {
   if (evt.success == true)
   {
      alert("Contact "+evt.contactid+" has been removed");
   }
}

add

An addContact operation is complete.

Description

This event is fired in response to an addContact call when the user either finishes adding a contact or cancels the operation.

Properties

• success: true if the user added a contact; false if the user canceled the operation.
• contactid: The id property of the added contact if success is true; undefined if success is false.

busy

An operation could not be performed because another operation was already in progress.

Description

This event is fired when the addContact, chooseContact, editContact, or removeContact method is called, but one of those methods has previously been called and has not finished.

choose

A chooseContact operation is complete.

Description

This event is fired in response to a chooseContact call when the user either finishes choosing a contact or cancels the operation.

Properties

• success: true if the user chose a contact; false if the user canceled the operation.
• contactid: The id property of the chosen contact if success is true; undefined if success is false.

edit

An editContact operation is complete.

Description

This event is fired in response to an editContact call when the user either finishes editing the contact or cancels the operation.

Properties

• success: true if the user edited the contact; false if the user canceled the operation.
• contactid: The id property of the contact that was to be edited, whether or not it was actually edited.

get

The internal contact list has been initialized or updated from the device contacts database.

Description

This event is fired in response to a getContacts call when the initialization or update of the internal contacts list is complete.

Properties

permissionDenied

The application does not have permission to access the system contacts database.

Description

An operation that needs to access the device contacts database has failed, either because the application was not built with the privileges required to access the database, or because the user has refused to allow the application to access the database.

remove

A removeContact operation is complete.

Description

This event is fired in response to a removeContact call when the operation completes, either successfully or unsuccessfully.

Properties

• success: true if the contact was removed; false otherwise.
• contactid: The id property of the contact that was to be removed, whether or not it was actually removed.
• error: A string describing the reason the contact was not removed if success is false; undefined if success is true.