JavaScript Picker Sample For The Google Contacts Data API

This sample demonstrates displaying a list of contacts received from a user’s GMail contact list using the Google Data JavaScript client library in conjunction with the Google Contacts Data API.

After logging in to your Google account below, the JavaScript client library retrieves a Google Data feed describing the contact groups that are associated with an account. At a minimum, all users have an “All Contacts” group. Other groups will not exist unless they have been explicitly created by the user.

Once a group has been selected, the list of contacts who exist within that group will be downloaded by requesting a different Google Data feed. Clicking on a contact’s name will download and display relevant information about that contact.

By clicking the checkboxes next to each contact, you will be selecting those contacts for some future action. The action performed is determined by a callback function, specified by the application developer during initialization of the script. Contacts may be selected as desired from any mix of groups, the sample maintains internal state so that a contact's selection history is preserved during the course of individual sessions.

For the purposes of this sample, the contacts selected will be used to populate the To: header in email message. Since this sample does not have any supporting server-side logic, this message will be opened for sending using your local mail client, if any.

As this sample uses a JavaScript client library, JavaScript support must be enabled in your web browser. If this may be a concern in your application, you may wish to consider one of the other Google Data client libraries.

1Login and select contacts

2Compose & Send Message

To:

Reminder: This field is automatically populated based on selections in the previous step.
Subject:
Message:

Note: This message will be opened (unsent) in your primary mail client.

3Download And Customize

Now that you’ve gotten a taste for how the contact picker sample works, play around with it, take it apart, and adapt it to your own needs. Start by obtaining a copy of the contact picker source: picker.js.

Once you’ve downloaded this file, embed it in your HTML document along with the Google JavaScript API loader:

<script type="text/javascript"
  src="http://www.google.com/jsapi">
</script>
<script type="text/javascript"
  src="picker.js">
</script>

The next step is to load the Google Data client library. Since the JavaScript API loader is now embedded in your document, you can just call the gdata.load() function from within a <script> tag in the <head> of your HTML document:

google.load("gdata", "1.x");

Provide the contact picker with a unique name to identify your application when communicating with Google’s servers:

Picker.setServiceName('Google-PickerSample-1-0');

The contact picker will need to know about callback functions to be invoked when contacts are added or removed. These functions must accept one parameter, namely a reference to the ContactEntry that is being added or removed: 

var userAdded = function(contactEntry) {
  // Do something
}

var userRemoved = function(contactEntry) {
  // Do something else
}

Picker.setUserAddCallback(addContact);
Picker.setUserRemoveCallback(removeContact);

Detailed information about the ContactEntry class is available in the JavaScript client library reference guide.

Finally, create a <div> to hold the contact picker user interface, and add Picker.render() to your document’s onload event handler. Picker.render() takes as an argument the ID of the <div> that will be holding the contact picker.

Your finished HTML document should look like this:

<html>
<head>
...
<script type="text/javascript"
  src="http://www.google.com/jsapi">
</script>

<script type="text/javascript"
  src="picker.js">
</script>

<script>
  var userAdded = function(contactEntry) {
    // Do something
  }

  var userRemoved = function(contactEntry) {
    // Do something else
  }

  google.load("gdata", "1.x");
  Picker.setServiceName('Google-PickerSample-1-0');
  Picker.setUserAddCallback(addContact);
  Picker.setUserRemoveCallback(removeContact);
</script>
</head>
<body onload="Picker.render('picker_container')">
...
<div id="picker_container"></div>

At this point, you should be ready to begin development. Happy coding!

Resources