This chapter is from the book
This chapter is from the book
This chapter is from the book
Building Peachmail: Address Book Services
Now that Joe has logged in, he needs to add some friends to his address book. Peachmail's Address Book allows a user to add contacts, remove contacts, and send emails to contacts. Let's look at how Flash MX works with the server to provide Peachmail's address book services.
The Front-End: Flash MX
)
Figure 7.11 The Peachmail application's main email screen.
Each button on the screen is handled in much the same way as the buttons in the login and registration section—that is, each button executes a handler when it's clicked. Joe wants to add some friends to his address book, so he clicks the Address Book button. This triggers the addressBookHandler(), which simply opens a pop-up browser window to show the Address Book screen.
global.openBrowserWindow = function (url, name, width,height) { getURL("javascript:void(window.open('" + url + "', '" +
The Address Book screen (Figure 7.12) contains three buttons that enable Joe to add a new address, delete an address, or send an email to a selected email address.
)
Figure 7.12 Add a new delete an address, or email from the Address .
Adding a New Address
Clicking the New Address button triggers newAddressHandler(), which opens the New Address screen (Figure 7.13) for adding a new address:
)
Figure 7.13 The New Address screen.
When the New Address screen is loaded, it creates a local connection to the Address Book screen so that it can pass back the newly added address. Local connections allow data to be passed between two external .swf files. We'll discuss local connections in more detail at the end of this chapter. For now, let's look at what happens when the Create button is clicked:
createHandler = function () {
// change the address
newAddressConnection.send("newAddress", name.text,
email.text);
// close this window
getURL("javascript:void(window.close());");
}
The handler takes the text from the name and email textfields and sends them to the local connection's newAddress() function – the local connection being the Address Book window – and then it closes itself i.e. the New Address window. The Address Book's newAddress() function looks like this:
newAddressConnection.newAddress = function (name, email) {
// create the new address
addAddress(name, email);
}
The newAddress() function takes the name and email and sends them to addAddress():
addAddress = function (name, email) {
// make the xml
addAddressXml = buildAddAddressBookEntryRequest(name,
email);
// make the callback
addAddressCallback = function (name, email) {
// check for success
if (wasSuccessful(this.getDocIn())) {
// get the dataNode
var dataNode = findDataNode(this.getDocIn());
// get the id
var id = dataNode.firstChild.attributes.ID;
// add the entry addressBook.
addAddress(name, email, id);
}
}
// send to server with name and email supplied as arguments
sendToServer(addAddressXml, addAddressCallback, name,
email);
}
In this code, the buildAddAddressBookEntryRequest() function creates the XML request for the new entry and the sendToServer() function passes the request to the server for processing. You'll recall this mirrors the create-send-callback method discussed earlier in the login and registration section. What is interesting here is the callback function: it takes the XML result from the server and parses it, and then it calls addressBook. addAddress() to add the new address details to the Address Book's listbox:
addressBook.prototype.addAddress = function (name, email, id) {
// create a temp object to hold values
var tempObject = {};
// store the name
tempObject.name = name;
// store the email
tempObject.email = email;
// store the id
tempObject.id = id;
// add the the addresses array
this.addresses.push(tempObject);
// add to the listbox
this.listbox.addItem(tempObject.name + "(" + tempObject.
email + ")", this.address.length);
// store in the ids object
this.ids[id] = this.listbox.getLength() - 1;
}
Note how the code calls the addItem() method of Macromedia's listbox component to add the new address to the listbox.
Deleting an Address
Deleting an address involves selecting an address from the listbox and then clicking the Delete Address button. When an item is selected from the listbox, it is marked in the listbox so that it can be retrieved later by the listbox.getSelectedIndex() function. When the Delete Address button handler is called it does the following:
deleteAddressHandler = function () {
// get the id from the selected address
var id = addressBook.getSelectedAddress().id;
// delete the address
deleteAddress(id);
}
The addressBook.getSelectedAddress() function returns a record containing the name, text, and id fields of the selected address, using the listbox.getSelectedIndex() function mentioned previously.
addressBook.prototype.getSelectedAddress = function () {
// get the selected item
var selected = this.listbox.getSelectedIndex();
// return the object with the item info
return this.addresses[selected];
}
The deleteAddress() function creates an XML request for deleting the address, sends it to the server via sendToServer(), and removes the selected address from the Address Book:
deleteAddress = function (id) {
// make the xml
deleteAddressXml = buildDeleteAddressBookEntryRequest(id);
// send the xml
sendToServer(deleteAddressXml);
// delete from the address book
addressBook.deleteAddress(id);
}
The final step of the delete address method is addressBook.deleteAddress(), which removes the address from the Address Book's listbox:
addressBook.prototype.deleteAddress = function (id) {
// get the index from the ids object
var index = this.ids[id];
// remove from the listbox
this.listbox.removeItemAt(index);
}
Sending Email
To send email, the user must first select an address from the Address Book listbox and then click the Send Email button.
sendEmailHandler = function () {
// get the current email
var email = addressBook.getSelectedAddress().email;
// open the compose window
openCompose(email);
}
sendEmailHandler() passes the selected address to openCompose(), which handles the creation of the local connection to the Compose screen and the opening of the Compose screen with the selected email address.
openCompose = function (to, subject, message) {
// create a connection to the compose window
composeConnection = new popupConnection("compose", false);
// set the email text fiels contents
composeConnection.send("setVariable", "to", "text", to);
// set the subject contents
composeConnection.send("setVariable", "subject", "text",
subject);
// set the message contents
composeConnection.send("setVariable", "message", "text",
message);
// close the connection after everything is sent
composeConnection.onFinishQueue = function () {
// close the connection
this.close();
}
// open the compose window
openBrowserWindow("compose.html", "compose", 550, 400);
}
The Compose screen (Figure 7.14) appears and the user is given the capability to fill in the textfields and click Send (or Cancel, if he changes his mind).
)
Figure 7.14 The Peachmail Compose screen.
The Send button's handler looks like this:
sendHandler = function () {
// make the xml doc
var sendMsgXml = buildSendMessageRequest(to.text,
subject.text, message.text);
// create the callback
sendMsgCallback = function () {
// close the window
getURL("javascript: void(window.close());");
}
// send it to the server
sendToServer(sendMsgXml, sendMsgCallback);
}
You'll notice this handler does nothing more than create and send the XML request to the server, and then its callback closes the window. The server handles the work of sending the message to the specified recipient.
The Back-End: Java
Similar to the server handling in the login and registration, the server handling for the address book services consists of taking an XML document, processing the respective request, and firing back a response indicating whether the processing was successful. In adding an address, the processing includes updating the database with the new address. In deleting an address the processing includes removing an address from the database. Finally, in sending the email, the server is responsible for delivering the message to the recipient.
Processing the Add Address Request
When Joe adds an address to his Address Book, this is an example of what he would send to the server:
<Request>
<TransactionType>AddAddressBookEntry</TransactionType>
<Data>
<Entry>
<Name>Lara</Name>
<Email>lara@iamlara.com</Email>
</Entry>
</Data>
</Request>
This is a typical response returned by the server if the server were added the address to the database successfully:
<Response>
<Status>Success</Status>
<Data>
<Entry ID="456" />
</Data>
</Response>
and unsuccessfully:
<Response>
<Status>Error</Status>
<Data>
<Message>The address did not add successfully</Message>
</Data>
</Response>
Processing the Delete Address Request
Let's say Joe successfully added a friend to his Address Book, but realizing he made an error in the email address, he decides to delete the address. The XML request would look like this:
<Request>
<TransactionType>DeleteAddressBookEntry</TransactionType>
<Data>
<Entry ID="56" />
</Data>
</Request>
On a successful deletion of the address from the database, the server would return this to Flash:
<Response>
<Status>Success</Status>
<Data>
<Message>The transaction completed successfully
</Message>
</Data>
</Response>
And on an unsuccessful deletion:
<Response>
<Status>Error</Status>
<Data>
<Message>The address did not delete successfully
</Message>
</Data>
</Response>
Processing the Send Email Request
When Joe decides to send an email, the XML request looks like this:
<Request>
<TransactionType>SendMsg</TransactionType>
<Data>
<Addressee>lara@iamlara.com</Addressee>
<Subject>curious</Subject>
<Body>Lara, do you miss me? Curious, Joe</Body>
</Data>
</Request>
The following is an example of the XML response if the server successfully delivers the message to the recipient:
<Response>
<Status>Success</Status>
<Data>
<Message>The transaction completed successfully
</Message>
</Data>
</Response>
And unsuccessfully:
<Response>
<Status>Error</Status>
<Data>
<Message>The email failed to send</Message>
</Data>
</Response>
The Database
On Joe's add address request, the server adds a record to the AddressBookEntries table containing Joe's userID, the new name, and the new email address. The delete address request removes the specified record from the Address-BookEntries table. Finally, the send email request saves the message into the Messages table.