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

The doAddContact() Function

The doAddContact() function has two main duties. It adds a new contact to the our application's local SharedObject and it returns the address book to "browse" mode.

Here's the sequence of steps that lead to a doAddContact() call:

The doAddContact() function performs the following tasks:

	Disables the "contact details" pane and enables the "address book" pane.
	Adds a new contact to the local SharedObject.
	Refills the contactListBox_lb with the latest contact list.
	Selects the newly added contact in contactListBox_lb.
	Places the new contact information in the "contact details" pane.

The complete listing for doAddContact()() is shown below. Skim it first, then we'll examine key points in detail.

/*
 * Function: doAddContact()
 *   Desc: Stores a new contact in the local shared object and
 *         returns the app to regular "browse" mode.
 *   Parameters: None.
 */

function doAddContact () 
{
  // Return to the normal address book mode.
  exitEditMode();

  // Add the new contact, and store the returned contact
  // object in newContact. We'll use the reference to
  // determine which item to select in the contactListBox.
  newContact = contactMgr.addContact(firstNameField.text, 
                        lastNameField.text, 
                        emailField.text, 
                        phoneField.text,
                        phoneComboBox_cb.getSelectedIndex(),
                        companyField.text,
                        commentsField.text);

  // Refill the entries in the address book. This places
  // our newly added contact into the listbox. Note that we
  // could also use addItem() or addItemAt() to update the
  // listbox content, but we'll keep things simple by 
  // reusing our populateListBox() function. A functional
  // improvement would be to check the sort order of the
  // listbox and add the new item at the correct location.
  populateListBox();

  // Now we have to do a little work to select our newly
  // added contact. We can't guarantee where it will be added
  // so we hunt for it by id, and select it when we find it.

  // Get the number of items in the listbox.
  var numItems = contactListBox_lb.getLength();

  // Get the id of the item we want to select.
  var newContactID = newContact.id;

  // Cycle through each item checking to see if its id
  // matches the id we're looking for.
  for (var i = 0; i < numItems; i++) {
    // If there's a match...
    if (newContactID == contactListBox_lb.getItemAt(i).data) {
      // ...select it and stop looking (break the loop).
      contactListBox_lb.setSelectedIndex(i);
      break;
      // Note that setting the selected index also causes
      // the contactListBox's change handler to 
      // fire (populateDetailsPane).
      // Hence, the details pane automatically shows
      // a value in the date added and date modified text fields.
    }
  }
}

To add the new contact to the local SharedObject, we use our ContactMgr object's addContact() method. The addContact() method provides a clean, consistent interface to our local SharedObject, so we are spared the trouble of working with individual SharedObject properties every time we want to save new data.

As we saw earlier, addContact() expects to be passed the new contact's information (firstName, lastName, etc). We retrieve this information from the input text fields and ComboBox in the "contact details" pane, and pass it along to addContact():

  newContact = contactMgr.addContact(firstNameField.text, 
                        lastNameField.text, 
                        emailField.text, 
                        phoneField.text,
                        phoneComboBox_cb.getSelectedIndex(),
                        companyField.text,
                        commentsField.text);

The addContact() method returns a reference to the contact object we just created. We store the reference in newContact so we can later determine the id number it was automatically assigned.

Once we've finished refilling the contactListBox_lb, the new contact should be available to the user. As a convenience, we want to select the new contact. This requires some ListBox investigation. We know that all items in the contactListBox_lb have their "data" value set to a contact id. We want to find the index of the item with a data value matching our new contact's id. Once we know the index of that item, we can select it using setSelectedIndex().

Here's the relevant code from the listing above, with additional comments:

  // We have to loop through all the items in the
  // ListBox, looking for our contact id. So, first
  // we find out how many items are in the ListBox.
  var numItems = contactListBox_lb.getLength();

  // Then we get the id of the item we want to select.
  var newContactID = newContact.id;

  // Here's the loop. For each item in the ListBox, we
  // check if its data value matches our contact id.
  for (var i = 0; i < numItems; i++) {
    // If there's a match...
    if (newContactID == contactListBox_lb.getItemAt(i).data) {
      // ...we select it and stop looking (break the loop).
      contactListBox_lb.setSelectedIndex(i);
      break;
    }
  }

Notice that we can retrieve a reference to a ListBox item at any index using the getItemAt() method. We use that technique to check the data property of each item object in our loop.

Expert Note: When we populate the ListBox, we use a for-in loop to enumerate all the properties of our SharedObject's contacts object. In Flash, a for-in loop enumerates properties by date added, most recent to oldest. Hence, we could assume that the first item in our conactListBox_lb is always the newest, and just set it to be selected. While this would work, the order of enumeration in a for-in loop is not formally guaranteed. It's therefore safer and more extensible to select our new contact item only after finding a real match.