Home / DevNet / Macromedia Flash Development Center /

Macromedia Flash Article

Mike Chambers
mesh@macromedia.com

This articles shows how the DataGrid component was used to create a simple POP e-mail application that allows users to retrieve and read e-mail via a Macromedia Flash MX interface. It discusses the DataGrid, Loading Box, and Advanced Message Box components as well as the E-mail Services Library and sample application all of which are available on the Macromedia MX Developer Resource Kit (DRK).

What is the e-mail sample application?
The e-mail sample application is actually two sample applications:


•	POP e-mail application
•	SMTP e-mail application

As noted above, both are available on the DRK, and utilize a collection of reusable Macromedia Flash MX ActionScript classes and ColdFusion MX components to make it easy to send and retrieve e-mail from Macromedia Flash MX.

What is the DataGrid Component?
The DataGrid component is one of the most advanced Flash MX components created. It creates a grid that allows you to sort, organize, and control your data-rich applications with a powerful set of interfaces that help facilitate data visualization in a straightforward, less time-consuming way.

How is the DataGrid used within the e-mail application?
Within the e-mail application, the DataGrid component is used to display a list of e-mail that has been retrieved from the server. This is very similar to the way that traditional e-mail application work, and allows the user to easily view and sort large amount of e-mail.

Only certain information about each e-mail message is displayed. The displayed fields are:

•	From
•	Date
•	Subject

When the user selects an e-mail from the DataGrid, the entire message is retrieved from the server and displayed in a text field within the application.

Using the DataGrid

Using the DataGrid in the application is surprisingly simple. We have to first drag the component from the components panel, into our Macromedia Flash MX application. Once we have done this, we need to give it an instance name. This is done by selecting the component instance in your application and then giving it an instance name in the Property inspector. The instance name used in the sample application is “mailList”.

Once this is done, there are only a few more steps:

1	Pre-populate the column names, so that they appear before the user retrieves the e-mail.
2	Populate the DataGrid with e-mail information from the server.
3	Specify which function (Change Handler) will be called when the user selects an item within the DataGrid.
4	Write the code within the Change Handler that responds to user’s interaction with the DataGrid.

Pre-Populating the Column Names

By default, the DataGrid does not have pre-set column names. Because of this, it will appear as a big empty square before any data is loaded into it. Not only is this unattractive for users, but also confusing, as they have no idea what the big square is for.

This is easily solved by pre-populating the column names for the DataGrid before data is loaded into it. In our case, we want to display three columns:

•	From
•	Date
•	Subject

These are the fields that will be displayed when e-mail is loaded. This is done via the DataGrid’s setColumns method, which takes a comma separated list of column names.

mailList.setColumns("from" ,"date", "subject");

As you can see, that makes it a little more clear as to what the DataGrid is used for in the application.

Fortunately, by default, the columns are not all resized evenly. And thus, the subject column is wider than the from and date columns. This is useful since the subject column will contain a larger amount of data that is more likely to be relevant to the user.

If you wanted to manually size the columns, you could so using the following methods:

FDataGrid.spaceColumnsEqually();
FGridColumn.setWidth();

You can find more information on these methods in the documentation for the DataGrid.

Populating the DataGrid with e-mail

Actually, populating the DataGrid with e-mail from the server is surprisingly simple.

When mail is received from the server via the PopServices library (included on the DRK and used in the sample application to retrieve the e-mail), the onMail method is called and passed an EmailCollection object which contains Email objects each of which represents an e-mail message.

Couple of quick points:

1	An `EmailCollection` extends the `RecordSet` class, and is thus a `DataProvider` Class. This means that it can be passed directly to the DataGrid component via the `setDataProvider` method.
2	The `EmailCollection` contains `Email` objects. However, in the sample application, the entire e-mail message is not retrieved by default. Only the from, subject and date fields are retrieved by default. The e-mail body is retrieved when the user selects an individual e-mail to view. This decreases the amount of data that has to be loaded.
3	You can find more information on the `EmailCollection`, `Email` objects and other classes includes in the Email Services Library by viewing the documentation on the DRK.

Here is the onMail function which is called once the e-mail is loaded from the server.

p.onMail = function(ec)
{
           //code snipped

           var mailCount = ec.getLength();
           setEmailCount(mailCount);

           if(mailCount < 1)
           {
                       mBox.setMessage("There is no mail on the server.");
                       mBox.setTitle("No Mail.");
                       mBox.setIcon("famb_infoIcon");
                       mBox.setActiveState(true);
                       return;
           }
                       
           //code snipped

           mailList.setDataProvider(ec);
}

Looking at the code, there is really not much to do. First, we find out how many e-mails were returned by getting the length of the EmailCollection. We then display the number to the user.

var mailCount = ec.getLength();
setEmailCount(mailCount);

If there is no e-mail returned from the server, then we use the Advanced Message Box component (also available on the DRK) to display a message to the user notifying them that there was no mail on the server. We then exit the method.

mBox.setMessage("There is no mail on the server.");
mBox.setTitle("No Mail.");
mBox.setIcon("famb_infoIcon");
mBox.setActiveState(true);
return;

If there is e-mail, then we simply pass the EmailCollection instance to the DataGrid component via the setDataProvider method.

mailList.setDataProvider(ec);

This will automatically populate the DataGrid with the e-mail information. Again, you can do this because the EmailCollection class is a DataProvider class, which the DataGrid component can recognize.

Setting the Change Handler

The Change Handler is the function that is called when the user selects an item within the DataGrid. First we have to tell the DataGrid which function to use as the Change Handler. Then, we need to actually create the Change Handler.

Setting the change handler can be done in two ways:

1	Through the Property inspector.
2	Via ActionScript.

If you look at the sample application, you should notice that the Change Handler is set in the Property inspector and points to a function named “subjectSelectHandler”.

When setting the change handler through the Property Inspector, the DataGrid will assume that the function exists on the main timeline as the DataGrid. If it exists within an object, or on another timeline, you will have to set the change handler through ActionScript.

Doing it via ActionScript is just as easy, and is done through the setChangeHandler method of the DataGrid component.

mailList.setChangeHandler(“subjectSelectHandler”);

Notice that the method takes a string name, and not a direct reference to a function. If you look at the documentation for the setChangeHandler method, you will notice that it actually takes two arguments. The first is the name of the function, and the second is the scope / object / timeline within which the function exists. If you leave out the second argument, the DataGrid assumes that the function exists on the same timeline as the DataGrid. This is the same as setting the change handler via the Property inspector.

However, perhaps your DataGrid is contained within a movie clip, but you want to keep all of your ActionScript code, including the change handler, on the main timeline. In that case, you would specify the timeline as the second argument:

mailList.setChangeHandler(“subjectSelectHandler”, _parent);

This tells the DataGrid to call the _parent. subjectSelectHandler method whenever the user selects an item in the component.

Creating the Change Handler

Now that we have set up the DataGrid, all that is left is to create the change handler that will be called when the user selects an e-mail message from the DataGrid.

Our handler will do the following:

1	Figure out which e-mail was selected.
2	See if it has already been viewed by the user. If it has, retrieve it from the `Email` cache, and display it.
3	If it hasn’t retrieve the e-mail from the server, open a Loading Box telling the user that the e-mail is being retrieved.

Here is the entire function:

subjectSelectHandler = function(uidPointer)
{
       var uid = uidPointer.getSelectedItem().uid;
 
       if(uidPointer != null)
       {
             var cachedData = emailCache[uid];
 
             if(cachedData != null)
             {
                 _root.body.text = cachedData;
                 return;
             }
             else
             {
                 lBox.setActiveState(true);
                 lBox.setMessage("Retrieving Message");
                 //we will set the timeout to 10 in case it is a large e-mail.
                 lBox.setTimeout(10000);
                 p.retrieveMessage(uid);
              }
        }
}

First, notice that the change handler takes a single argument. This is a reference to the instance of the DataGrid that the change handler is being called on. This is useful if you have multiple DataGrids in an application, but want to use the same change handler.

Once we know which DataGrid the event is from, we get the object associated with that item (which in the case, is actually an Email object).

var uid = uidPointer.getSelectedItem().uid;

The object contains a field called “uid” which is a unique identified for the e-mail.

Once we have the UID, we can see if the e-mail is stored in the Email cache. Since we store the e-mails in the cache by the UID, we simply see if any information is stored under the current UID.

var cachedData = emailCache[uid];

If cachedData is not null, it means that we have already retrieved the e-mail from the server, and thus can use the local copy. In that case, we simply display it in the main text field and exit the method.

if(cachedData != null)
{
        _root.body.text = cachedData;
        return;
}

If it is null, it means that the message has not been retrieved from the server. Thus, we need to first display the

Loading 
                    Box

component to the user and tell them that we are retrieving their message.

lBox.setActiveState(true);
lBox.setMessage("Retrieving Message");

Next, we set a timeout on the Loading Box equal to 10 seconds. This way, if the connection with the mail server dies, we can display an error message to the user.

Finally, we call the retrieveMessage method of the PopServices library, in order to retrieve the message from the server.

p.retrieveMessage(uid);

Notice that we pass the UID to the method, which specifies which e-mail message to retrieve.

Once the e-mail comes back from the server, it is displayed in the main text field.

Of course, there is a lot more going on in the e-mail application than what is covered here. However, the application shows how useful the DataGrid can be, while at the same time be surprisingly simple to use.

Again, all of the files, samples, components and libraries discussed in this article are available of the Macromedia MX DevNet Resource Kit, which can be purchased from the Macromedia store.

About the author
Mike Chambers has been creating applications using primarily Macromedia Flash, Generator and Java for the past three years. He also has experience working with ASP, JSP, PHP and ColdFusion. Recently he has been working with Macromedia Flash and embedded devices, contributing to the “Macromedia Flash Pocket PC Player Authoring Kit.” He is co-author of "Flash Enabled" and “Generator and Flash Demystified."
Mike received his Masters in International Economics and European Studies from the John Hopkins School of Advanced International Studies (SAIS) in 1998.