PhoneGap 3 – Contacts API Tutorial

Tweet about this on TwitterShare on LinkedIn0Share on Google+0Share on Reddit0Buffer this pageFlattr the authorEmail this to someonePrint this page

PhoneGap 3 – Contacts API Tutorial

This is a quick start tutorial using PhoneGap 3’s contact API. I have written another post here explaining what PhoneGap 3 is, how is to set it up & what are the key differences between PhoneGap 2.x & PhoneGap 3.x. I recommend checking that out before continuing.


  • Step 1: Create a new GitHub repo (How to? – Here).
  • Step 2: Clone the repo to local
  • Step 3: Create new PhoneGap 3 project (assuming you have completed the setup from here)
  • Step 4: Update the newly created app & test in local.
  • Step 5: Commit Changes to GitHub repo
  • Step 6: Run PhoneGap Build, Install the app & validate(How to? – Here)
  • Step 7: Make changes to our project – add jQuery Mobile Framework (Must read) & Contacts API plugin.
  • Step 8: Commit changes back to the repo
  • Step 9: Issue a PhoneGap Build & BOOOOMMM!!! Install the app & validate

So lets get started!

PS:We are going to follow Mac/Windows – Android ADT based development.

Step 1: Create a new GitHub repo

Head to GitHub & create a new repo. If you are new to GitHub or Git, I recommend reading this post. Lets create a new Repo and Name it PhoneGap3ContactsAPI, add a small description & MIT license.

Step 2: Clone the repo to local

Create a folder, where you want to manage this project. I will create a folder called PG3ContactsAPI. Open Terminal/Git Bash here. CD inside the PG3ContactsAPI  folder. Clone the repo by copy pasting the git URL from the bottom right side of the repo home page. And then run

git clone

CD inside the PhoneGap3ContactsAPI folder. You should see a License & a Readme file.

Step 3: Create new PhoneGap 3 project

Once you are inside the folder, run

phonegap create PhoneGap3ContactsAPI

This should create 4 new folders. And your folder structure should be something like this

Screen Shot 2014-03-02 at 12.37.59 PMIgnore the .git, .cordova & .DS_Store folders.

www – This is the heart of the complete application. And this is where our config.xml resides. This folder hosts the js/css & html files. When you add a new environment like android or windows all the resources will be copied from here. We will do ALL our development here.

platforms – This folder will hold all the environment specific development directories. AFAIK, this directory is for device dependent development only & of course local debugging.

plugins – This will hold all the plugins you need to develop your app. As of PhoneGap 3.x, even the device native APIs like contacts and cameras need to be listed here.

merges – This folder tell PhoneGap build to take device dependent overrides from here.

Step 4: Update the newly created app

Now, we will configure the new app to reflect our details. navigate to PG3ContactsAPI/PhoneGap3ContactsAPI/www & open config.xml in your favorite text editor. This file holds our meta data, which will contain information about our app, what are the defaults etc. You can read more about config.xml here.

First lets update the Widget Id (line no 2) to Next, update the name (on line 3) to SearchContactsAPI. Update the description (line no 5) to ‘A Tutorial Repo for PhoneGap 3 Contacts API.’ & finally update autor tag (line nos 7-8) with your details. Save the file.

Don’t ask me why, but as of today when you use a PhoneGap command to create a new project, your project (index.html) file will reference phonegap.js. But when you build an Android or iOS project, they will generate a cordova.js.

So, to work around this, we will open our index.html inside the www folder & update line no 37 from  <script type="text/javascript" src="phonegap.js"></script> to  <script type="text/javascript" src="cordova.js"></script>. PhoneGap build doesn’t really mind if you use phonegap.js or cordova.js.

Thats it save the file. Now back to Terminal. Let create a local dev setup for this app. (If you have not already done, set up a Mac/Windows Android development environment following this post.) Run

cordova platforms add android

This will add Android platform to our platforms folder. Next, lets build the project. Run

cordova build android

You should see a build successful message. Now lets load this Android project to our ADT. Then we will test the app locally & then execute a phonegap build.

Open ADT, File > Import > Android > Existing Project. Browse the path to /<<path till here>>/PG3ContactsAPI/PhoneGap3ContactsAPI/platforms/android. Import both the projects. This will take a couple of mins for the projects to set up. We will NOT make any changes here! Right click on SeacrchContactsAPI in the project explorer and run as Andorid Application. Depending on your machine config, it will take up to 10 mins to launch the emulator.

Once the emulator is launched, you should see your installed app. If the emulator does not show up your app, be a lad, unlock the screen, go to apps menu and launch your app. You should see something like this

Screen Shot 2014-03-02 at 2.06.13 PM

You should see a flashing message – “Device is ready”. (Yeah it is!!). Now we have successfully tested our app locally.

Step 5: Commit Changes to GitHub repo

Back to Terminal/Git Bash. You should be at this path PG3ContactsAPI/PhoneGap3ContactsAPI. Now lets see what all files have changed. If you want to you can add a gitignore file to avoid pushing unnecessary data to GitHub like bin folders etc. I have found a comprehensive list here. You can create a new .gitignore file and add the contents.

Windows Mac/*nix
Root folder (PG3ContactsAPI/PhoneGap3ContactsAPI) – Right click > New text file. Name it .gitignore. Root folder (PG3ContactsAPI/PhoneGap3ContactsAPI) –  touch .gitignore

Copy the below contents to that file

Now, lets run git status  to check the files that have changed. Then run  git add . to stage the files. Next let commit the changes. Run git commit -m "Initial Commit" . Next lets push these changes to our GitHub repo, Run  git push origin master.

You can check your changes by navigating to your GitHub repo in your browser. This should list all the files we have checked in.

Step 6: Run PhoneGap Build, Install the app & validate

I would highly recommend reading this post before continuing.

Lets head to PhoneGap Build. Create a new App & provide the git URL we have used to clone the app to our local. (PS : PhoneGap Build takes only https urls. You can switch between ssh and https below the URL textbox field in your repo home page)

If you see any errors related to android like

No such file or directory - /var/rails/

Then we may need to remove the android platform from the GitHub repo. Lets run  git rm -r platforms/android then run  git commit -a -m "removed android folder". Now lets push the changes. Run  git push origin master. Refresh your repo home page & you should see that platforms folder is gone.

Now, back to PhoneGap build, resubmit the Git URL. Hopefully that should do the trick & you will see a new project created. If you cannot see the Ready to Build button like this,

Screen Shot 2014-03-02 at 2.51.53 PMRefresh the page. And then Click on Ready to Build. This will create iOS (if the dev key is provided), Android & Windows phone installers. Download the app installer & test if you see the Device Ready message in the installed app on your device.

Step 7: Make changes to our project

We will interact with PhoneGap’s Contacts API. For the User Interface, we will use jQuery Mobile (read this before continuing). You can download the latest copy of jQuery mobile from here. Download the latest stable version. After you unzip it to any location copy the *.min.css to our www/css folder & *.min.js to our www/js folder. Download the latest version of jQuery from here, the minified version.

Your www folder structure should look something like

Screen Shot 2014-03-02 at 3.14.23 PM

Now we are all set to make changes. Open index.html.

Get rid of the div with class app in body section. We will write our markup here. Next, add reference jquery & jquery-mobile files. Open up www/index.css & delete all the contents inside it. Similarly clean up the contents of www/index.js.

Add reference to jQuery, jQuery-mobile js,css files in your index.html.

Our home page will consist of 2 Options Add a contact & Find contact. We will keep the fields as simple as possible.

We will add the below markup to our index.html file

The completed index.html will look like

Now, Remove www/img folder. Create another folder inside css & name it images. Back to jQuery mobile source file, copy the ajax-loader.gif present inside images folder to here.

Create 2 files add.html & find.html to the root of www. Your www folder structure will now look like this

Screen Shot 2014-03-02 at 4.58.56 PM

Next lets update find.html. This is the plan, we will go here to get an understanding of the contacts API. Next, we will add the contacts plugin to our project. Then, we will update the plugin details to our config file. Finally consume the API.

Back to Terminal/Git Bash. Run  cordova plugin add org.apache.cordova.contacts. If you face any issue while running this command, remove android platform, add it again & build by running the following commands

cordova platforms rm android

cordova platforms add android

cordova build android

Next, we need to add the plugin reference to our config.xml. Open www/config.xml. Just before the widget end tag, after the access tag add the following line

<gap:plugin name="org.apache.cordova.contacts" />

more info here. Without this line, your phonegap build will not know what plugins are used. Complete config.xml

Now lets update our find.html We are going to use a searchable list view. You can checkout the jQuery mobile docs here. Our final find.html will look like this

and index.css like this

The Contacts API – Open up index.js. The first thing we will do is clean up the old content (if not already done). Then add a Device Ready event listener. This will be triggered by PhoneGap to let us know that the DOM is ready and we can make changes to it.

Add  document.addEventListener("deviceready", onDeviceReady, false);  to index.js. Next, lets write the handler for deviceReady. We will not do anything for now, as we are just displaying 2 list items. We will create a new pageshow event & then check if there is only one of contactsList element. Then we will trigger the Contacts API to fetch all the contacts by specifying   options.filter = "" and  filter = ["displayName", "phoneNumbers"]; to specify the fields which we want to retrieve. This is what we will end up with

Next, lets add the success and error callback functions.

In the success callback, we will receive a list of contacts. we will iterate through each of them get the display name property. Next we will fetch a list of numbers associated with it. Built a list item by injecting these values in between markup. Finally append this list to the contactsList ul.

Error callback

The completed index.js with a simple loader widget will look this

Next, we’ll add the functionality to Add a new contact. We will keep things simple & add only 2 fields. The name & number.

Open add.html in a text editor and add the following code to it.

We will create a new contact with the 2 input fields. Back to contacts API, we will use the below logic

Our completed index.js will look like this

Pheeewwww… We are done with all our changes to the app. You can get the completed code at this repo.

You can test your app with the Android setup as we have done earlier. Run  cordova build android for the new changes we have made to www folder to sync in to Android platform. In ADT, refresh the projects before you run it in the emulator.

Incase you face issues, clean up the android folder and run build again

cordova platforms rm android

cordova platforms add android

cordova build android


Screen Shot 2014-03-02 at 8.09.00 PM    Screen Shot 2014-03-02 at 8.09.23 PM

Screen Shot 2014-03-02 at 8.09.36 PM    Screen Shot 2014-03-02 at 8.10.11 PM

Step 8: Commit changes back to the repo

Back to Terminal/Git Bash. Lets run  git status. Then  git add . -A to update and delete files as required. Next run git commit -m "Added Contacts API". Push changes to GitHub  git push origin master.

Step 9: Issue a PhoneGap Build & Validate

Navigate to PhoneGap build, click on your app name. This will take you to the builds. Click on Update Code & Pull latest  

Screen Shot 2014-03-02 at 8.15.24 PMIf there are any errors, read the message, you may understand it & fix it. Else, do drop a comment. Thats it!! Once the build is completed, you can download the installer and test the app.

PS: If your contacts list is huge, expect a delay.  You can use this code base as a template if you need.

Thanks for reading! Do comment.

Tweet about this on TwitterShare on LinkedIn0Share on Google+0Share on Reddit0Buffer this pageFlattr the authorEmail this to someonePrint this page
  • Saneesh

    Hello Arvind,

    This is really nice tutorial! I have successfully created the .apk and installed in my mobile.
    I have a question. I want to store/save the contacts from PhoneGap to DrupalGap. How can I do it?


  • Palani

    Good job Aravid. Very useful. Thanks

    • / Arvind Ravulavaru

      Thanks Palani.

  • Roozbeh


    How I can call contact.find multiple times? I have problem with threads. Thanks.

    This is my code and I want to modify the contacts:

    for(var n = 0; n < oldCodes.length; n++) {

    options.filter = oldCodes[n];

    options.multiple = true;

    var fields = ["phoneNumbers"];

    navigator.contacts.find(fields, onSuccess, onError, options);


    • / Arvind Ravulavaru

      Hello Roozbeh, not sure how I missed this comment but here is the solution, hope I am not late.

      I am not sure why you are querying it so many times. You can query for all contacts, keep a local variable and use it from that array. This way you query the device one (performance) at the same time keep querying the local variable again and again.