Bring Your Own Contacts

This example demonstrates how you can populate the widget with your own contact data. This is useful when you want to make alterations to the contacts that are returned and still use the widget to allow the customer to select their contacts.

For example, you might want to change the order of the contacts or modify the contact data before loading it.

Whatever the reason, it’s possible when you invoke a few of our options together.

There are two new Javascript APIs that make the BYOC feature possible:

  • cloudsponge.showProgress(source) lets you display our progress animation with a source icon at your discression.
  • cloudsponge.showContacts(contacts, source, owner) lets you force the widget to display the contacts that you give it in our address book UI. By default, the widget will still sort and filter the contacts. You can disable the sorting with the compare option. You can disable the filtering with the filter option. Both options are demonstrated below.

Add from Address Book 

<style type="text/css" media="screen">
    We're hiding the dictionary elements because they look strange when the
      contacts are out of order
  #cloudsponge-address-book .cloudsponge-dictionary#cloudsponge-dictionary,
  #cloudsponge-address-book .cloudsponge-letter {
    display: none;

<!-- TODO: Update this script with your own CloudSponge key -->
<script src="https://api.cloudsponge.com/widget/localhost-only.js"></script>
  // this will prevent the widget from sorting the contacts and ruining our explicit sorting
  compare: false,
  filter: function() { return true },
  skipContactsDisplay: true,
  beforeDisplayContacts: function(contacts, source, owner) {
    // since we're skipping the contacts display, the widget will disappear after
    //  this function returns so let's force a progress animation for continuity
    // I'm using a setTimeout here to simulate some asynchronous activity that
    //  you might choose to do in a real application. You might, say, make an
    //  ajax request to your app instead.
    setTimeout(function() {
      // do something to the contacts. I'm just grabbing the first 10 and 
      //  reordering them in order to demonstrate that the UI will now show
      //  what I tell it.
      contacts = contacts.splice(0, 10).reverse().map(function(contact, i) {
        contact.name = contact.fullName() || contact.primaryEmail()
        if (i % 2 == 0) {
          contact.name = '<span title="This user is a member of our platform.">' + contact.name + ' (member)</span>';
        return contact;
      // remove any emails from the first contact to demonstrate that the
      //  default filtering has been disabled
      contacts[0].email = [];
      // now that we've finished processing the contacts, we're going to display
      //  them to the user at last
      cloudsponge.showContacts(contacts, source, owner);
    }, 1000);
    // returning false has a subtle effect of not populating the
    //  .cloudsponge-contacts elements on the page. We'll allow 
    //  them to be populated after the user picks their contacts
    //  in the widget.
    return false;

Try CloudSponge for free in your
testing environment

Get Started

Have a questions or prefer a guided tour?
Schedule a consultation with our Founder.