Building an Address Book > Creating the Application Functions > The populateListBox() Function

The populateListBox() Function

The bulk of the visual work in the address book is performed by two functions: populateListBox() and populateDetailsPane(). These two functions display the user's data on screen. The populateListBox() function inserts items into the contactListBox_lb component.

Every time we need to refresh the address book display we call the populateListBox() function. For example, when the movie starts, init() calls populateListBox() so the user can immediately see the contacts in the address book. Similarly, when the list of contacts changes due to a doAddContact(), doUpdateContact(), or doRemoveContact(), we call populateListBox(). Note that every time populateListBox() runs, it actually removes and then recreates the entire contents of contactListBox_lb. In our application, this slightly inefficient approach does not discernably affect performance. In more demanding scenarios, it may be more efficient to make changes to the ListBox with the various ListBox update methods: addItemAt(), removeItemAt(), replaceItemAt().

The populateListBox() function performs the following tasks:

	Retrieves a list of contacts from the ContactMgr object.
	Formats each contact as a ListBox item.
	For every contact, inserts an item into contactListBox_lb.
	Sets the selected item of contactListBox_lb (if one was provided).

Take a look at the complete listing for populateListBox(), then we'll consider the interesting parts in more detail.

/*
 * Function: populateListBox()
 *   Desc: Fills the onscreen listbox with people in the address book.
 *   Parameters:
 *     selectedIndex     The index to select once the listbox is filled.
 */

function populateListBox (selectedIndex) 
{
  // Store a convenient reference to the contacts hash.
  var contacts = contactMgr.so.data.contacts;

  // The onscreen display of a contact in the listbox.
  var contactItem;

  // First, clear the listbox.
  contactListBox_lb.removeAll();


  // For every item in the hash, add a corresponding list item.
  for (var record in contacts) {
      // Assemble the contact information use as the listbox item.
      contactItem = contacts[record].firstName
                        + ", " + contacts[record].lastName
                        + ", " + contacts[record].email
                        + ", " + contacts[record].phone;

      // Add the contact to the listbox. Use the record id as
      // the listbox data so we can identify records later.
      contactListBox_lb.addItem(contactItem, contacts[record].id);
  }

  // Done filling the listbox. Now set the selected item.

  // If a valid integer greater than or equal to zero was supplied
  // for selectedIndex, use it to set the selected item in the
  // listbox.
  if (typeof selectedIndex == "number" 
      && Math.floor(selectedIndex) == selectedIndex
      && selectedIndex >= 0) {
    contactListBox_lb.setSelectedIndex(selectedIndex);
  }
}

The first line of the function stores a reference to the contacts property of the ContactMgr's SharedObject:

  var contacts = contactMgr.so.data.contacts;

This reference points to our list of contacts, and is used purely for convenience and readability.

Now we have to remove all the current items in contactListBox_lb via the removeAll() ListBox method. This clears the contactListBox_lb so we can refill it.

  contactListBox_lb.removeAll();

Next we use a for-in loop to access all the properties of contacts; each property is a Contact object representing a person in the address book. For each contact, we create a string to insert into the contactListBox_lb as an item label:

  contactItem = contacts[record].firstName
                    + ", " + contacts[record].lastName
                    + ", " + contacts[record].email
                    + ", " + contacts[record].phone;

To actually insert the new item into contactListBox_lb, we use the addItem() ListBox method, which accepts two parameters: the label to display, and the data associated with the item. We associate our item with the id number for the contact:

  contactListBox_lb.addItem(contactItem, contacts[record].id);

By setting the data to the contact id, we can later link any item in the contactListBox_lb back to a specific contact in our SharedObject. For example, to display the details for the selected item in the "addresss book" pane, we first retrieve the item's data, and then look up the contact by that id. The data retrieval code, which we'll see later in the populateDetailsPane() function, looks like this:

  var selectedID = contactListBox_lb.getValue();

Once our for-in loop is done, the contactListBox_lb is filled. All that's left to do is set the selected item in the list by using the setSelectedIndex() method. The method accepts a single argument: the zero-based index number of the item to select:

  contactListBox_lb.setSelectedIndex(selectedIndex);

We now know how populateListBox() fills contactListBox_lb with contacts. Next we'll examine how the "contact details" pane is filled with an single contact's information.