Projects
Classes
About
CV
 
 


 
 

 

produceconsumerobot


 
 


 


 
 

Week 5:

Contacts

The PhoneGap Contacts API is the way you can search through your phone's contacts and add new contacts to your list.

The following code example uses several aspects of this functionality.


<!DOCTYPE HTML>
<html>
<head>
  <meta name="viewport" content="width=320; user-scalable=no" />
  <meta http-equiv="Content-type" content="text/html; charset=utf-8">
  <title>Minimal AppLaud App</title>
  <script type="text/javascript" charset="utf-8" src="phonegap-1.3.0.js"></script>
  <script type="text/javascript" charset="utf-8">
  
    var onDeviceReady = function() {
      document.getElementById("devready").innerHTML = "OnDeviceReady fired.";
    }
    
    function init() {
      document.addEventListener("deviceready", onDeviceReady, true);
    }
    
    // searches the current contacts
    function searchContacts() {
      console.log("searchContacts()");
      var name = document.getElementById("nameSearch").value;
      console.log(name);
      var options = new ContactFindOptions();
      options.filter = name;
      options.multiple = true;
      var fields = [ "displayName", "name", "phoneNumbers" ];
      navigator.contacts.find(fields, onSuccess, onError, options);
    }
    
    // successful contact search
    function onSuccess(contacts) {
      var innerHtml = "";
      console.log(contacts.length + " contacts found");
      for ( var i = 0; i < contacts.length; i++) {
        console.log("Display Name = " + contacts[i].displayName);
        var contact = contacts[i];
        for (c in contact) {
          console.log(c + ": " + contact[c]);
        }
        if (contacts[i].phoneNumbers && contacts[i].phoneNumbers[0]
            && contacts[i].phoneNumbers[0].value) {
          console.log("Phone Number [0] = "
            + contacts[i].phoneNumbers[0].value);
          innerHtml = innerHtml
            + "<a href='tel:+" + contacts[i].phoneNumbers[0].value + "'>"
            + contacts[i].name.formatted + " ("
            + contacts[i].phoneNumbers[0].value + ")" + "<a/><br/>";
        }
      }
      var selectList = document.getElementById("contactList");
      selectList.innerHTML = innerHtml;
    }
    
    //error in contact search
    function onError(contactError) {
      alert('onError!');
    }
  
    // adds a contact
    function addContact() {
      console.log("addContact()");
      var dispName = document.getElementById("newDisplayName").value;
      var number = document.getElementById("newPhoneNumber").value;
      var myContact = navigator.contacts.create();
      myContact.displayName = dispName;
      var name = new ContactName();
      name.familyName = dispName;
      name.givenName = dispName;
      name.formatted = dispName;
      myContact.name = name;
      var phoneNumbers = [ 1 ];
      phoneNumbers[0] = new ContactField("home", number, true);
      myContact.phoneNumbers = phoneNumbers;
      myContact.save();
      console.log("The contact, " + myContact.displayName + ", has pn "
      + myContact.phoneNumbers[0].value);
    }
  </script>
</head>
<body onload="init();" id="stage" class="theme">
  <h2>Minimal AppLaud App</h2>
  <p>Your app goes here.</p>
  <p>
  	<span id="devready">onDeviceReady not fired.</span>
  </p>
  <input id="nameSearch" type="text" value="Enter Name"
  	style="width: 200px" />
  <button onclick="searchContacts();">Search</button>
  <br/>
  <p id="contactList">
  	<a href="tel:+1800229933">test 1800229933</a>
  </p>
  <input id="newDisplayName" type="text" value="Enter Name"
  	style="width: 200px" />
  <input id="newPhoneNumber" type="text" value="Enter Number"
  	style="width: 200px" />
  <button onclick="addContact();">Add</button>
</body>
</html>

Plugins

While the PhoneGap API has an increasing number of hooks into native phone functions, not all of the functions you might want to access are available through the PhoneGap API yet. To fill that gap, the architects of PhoneGap have created a plugin system that allows PhoneGap to be extended to include any native phone functions you want.

Plugins can be found in many places in the web including here - https://github.com/phonegap/phonegap-plugins

To use a new plugin that you find to you Android PhoneGap project, you need to do the following steps:

  • Copy the plugin.js file to your assets/www directory
  • Add a reference to the js file in your html
    e.g. <Script src="smsplugin.js" type="text/javascript" ></script>
  • Copy the directory tree including the plugin.java file
  • Add the plugin to res/plugins/plugins.xml
    e.g. <plugin name="SmsPlugin" value="net.practicaldeveloper.phonegap.plugins.SmsPlugin"/>
  • Add any necessary permissions to your AndroidManifest.xml
    e.g. <uses-permission android:name="android.permission.SEND_SMS"/>

Once you have the .js, .java and permissions set up correctly you can try out the new plugin. For the SMS plugin, you can add this to your javascript:


// sends an sms
function sendSMS() {
  console.log('sendSMS()');
  smsNumber = document.getElementById("smsNumber").value;
  smsMessage = document.getElementById("smsMessage").value;
  console.log('SMS attempt: ' + smsNumber + ', message=' + smsMessage);
  window.plugins.sms.send(smsNumber, smsMessage, function() {
      alert('SMS sent to: ' + smsNumber + ', message=' + smsMessage); }, 
      function(e) { alert('Message Failed:' + e); }
    );
}

And add this to your HTML:


<input id="smsMessage" type="text" value="Enter Message"
  style="width: 200px" />
<input id="smsNumber" type="text" value="Enter Number"
  style="width: 200px" />
<button onclick="sendSMS();">Send SMS</button>

Et voila, you can now send SMS from within your Android PhoneGap app.

Now what if you want to send SMS from your app on iPhone as well as Android?
At that point, you would need to find or write an SMS pluging for iPhone, e.g. https://github.com/phonegap/phonegap-plugins/tree/master/iPhone/SMSComposer and call the appropriate plugin depending on which device platform your app is running - http://docs.phonegap.com/en/1.4.1/phonegap_device_device.md.html#device.platform

 
produceconsumerobot