Today’s e-mails are often much more complex than the simple text messages used in the previous examples. Particularly, e-mails today may contain attachments. Luckily, the CFPOP tag can also be used to handle MIME attachments-the standard for mail attachments-with relative ease. This is done by using the ATTACHMENTPATH attribute. This attribute specifies a path where the attachments for a message can be saved.
For instance, in the preceding example of displaying message 2, you could adjust the CFPOP tag to be the following:
<CFPOP SERVER=’mail.domain.name’ USERNAME-‘user 1’ PASSWORD-‘passl’ ACTION-‘GetAll’
MESSAGENUMBER-2 ATTACHME~TPATH-‘c:\temp’ NAME-‘mail’)
There is only one point of concern regarding downloading attachments. A simple, automated way does not exist to remove the attachments that have been downloaded to the Web server once a user is finished with them. Instead, the CFFILE tag must be used to delete the attachments. For instance, you could combine CFLOOP with CFFILE to delete all the downloaded attachments from trus example:
<CFLooP INDEX-‘ListElement’ LIST-‘lmail.ATTACHMENTFILES’)
<CFFILE ACTION-‘Delete’ FILE-‘c:\temp\IListElementl’)
This adjustment now indicates that any attachments should be downloaded with the message and saved in the directory c :\ temp. Of course, this change isn’t much good if the files are saved, but the user has no way of knowing the names of.the files or of retrieving them through their Web browser. The answer lies in two additional fields that are provided in the query result when the ATIACHMENTPATH attribute is used:
ATTACHMENTS A tab-separated list of the original names of all attachments .
ATTACHMENTFIlES A comma-separated list of the temporary filenames used to save the files in the ATIACHMENTPATH directory These two fields are useful because they enable users to download attachments after reading a message. Consider the sample CFPOP tag in the preceding example. If c: \ temp is accessible on the Web site in question as /temp, then attachments can be downloaded by providing links to /temp/<attachmentfi 1ename>. Because it is possible to loop over comma-separated lists, providing a clickable list of links to attachments becomes a simple task:
There is only one point of concern regarding downloading attachments. A simple, automated way does not exist to remove the attachments that have been downloaded to the Web server once a user is finished with them. Instead, the CFFILE tag must be used to delete the attachments. For instance, you could combine CFLOOP with CFFILE to delete all the downloaded attachments.
Using Other Attributes
Some other attributes of the CFPOP tag are important to be aware of, even if you may only rarely have cause to use them. These are &ttlined in the following list:
TIMEOUT Specifies the length of time to wait for the server to return the requested data before giving up. The default is 60 seconds, but for poor connections or slow servers, it may be necessary to increase this value.
MAXROWS Specifies the maximum number of messages to return in a single CFPOP query. This can be useful, for instance, if a user has a large inbox and only a specified number of messages should be retrieved at once.
STARTROW Specifies the first message to start retrieving. Used in combination with MAXROWS, it is possible to,·for instance, display aninbox 100 messages at a time. Also, MAXROWS and START ROWcan be combined to have the same effect as MESSAGENUMBER .
A For instance, STARTROW-10 MAXROWS-l retrieves the same message as MESSAGENUM.
Building are web based E-Mail System.
Now it is time to put together a complete e-mail client application. This client is designed to provide a generic interface by which a Web u~er can access their mail on any Intemet-connected POP mail server. That is, anyone with a POP mailbox can provide their username, password, and mail server name and then view their inbox, read messages, and send messages.
First let’s look at the necessary pieces of the puzzle. Our application consists of six ColdFusion templates, as outlined in the following list: . cfm Provides a form in which the user can provide their usernarne, password, server name, and e-mail address for their mail account ; nbox . cfll Displays the box for the user readmessage. cfm Displays a specific complete message
compose, cfm Used to compose messages (including replies and forwarded messages) send, cfm Sends a composed message and returns-the user to their inbox de 1ete, cfm Deletes a specified message and returns the user to their inbox
Taken together, these six files provide the following functionality:
• Viewing an inbox
• Reading messages
• Replying to messages
• Forwarding messages
• Deleting messages
• Composing new messages
To analyze the way in which this e-rnail client works, you will look a; each of these files in turn.
The ; index , cfm file is where the application begins. This template is presented to the user the first time they access the application. It simply displays a form asking the user for the following information: Username The username for the mail account being accessed.- Password The password for the mail account being accessed. Server name The host name of the POP server on which the mail account is located. E-mail address The user’s e-mail address. This is used to construct From lines on all outgoing messages the user composes. When the user submits the form, the information is sent to the ; nbox , cfm template. The result is a template file shown in Listing 22.3
This template creates a simple form
Technically, there is little to note in this template beyond the names of the form fields (which, logically, are named user, password, server, and etPail) and the fact that the data is submitted ro the template i”box. cfm,
The inbox template is where the real work begins, and it is here that the process gets a little more complicated. The goal is to connect to the specified server, open the specified inbox, and retrieve all message headers.
These headers then need to be displayed in reverse chronol~ca1 order, and links need to be provided to enable the user to compose a new message, delete any specific message. read any specific message, and forward or reply to any specific·message.
This is done with the template in Listing 22.4 (the lines have been numbered for ease of reference).
At first this may seem daunting, but in reality it is quite a simple template that happens to need a lot of code. The end result is an inbox that looks like the one shown in Figure 22.4.
The template can easily be divided into three distinct components where the work is being done. You will look at each of these in turn.
Lines 4 to 16
This section has the job of setting some variables that will be needed throughout the rest of the template file.
Setting the variables starts with the CFIF clause (lines 4 to 14). This clause determines whether the input data (username, password, and so on) is being provided from a form (in other words, from the ; ndex. efm template) or as URL parameters. You set these variables so that once the user has logged in, the four pieces of information provided are passed through the rest of the application by the use of URL parameters. You pass along these. variables from page to page by setting variables purely for ease of programming. Several other options exist to achieve the same result, including the following:
• Using cookies
• Using client variables
• Using hidden form fields .
However, the purpose of this example is mail-related programming, so the programmatically simplest option has been chosen.
The CFIF clause is used to check whether any form data exists (by checking for the existence of one of the form fields). If the form data exists, then it is assigned to the variables user, password, server, and ema; 1.If the form data doesn’t exist, then the information is extracted from the URL and is stored in the same variables.
The final step in this segment of code is to create a token (line 16). The token is used to create the portion of a URL that would be used to pass these four pieces of information to another template through a link. This URL segment is stored in the variable token, which can then be used to quickly build all URLs for links throughout the rest of the template .
.Lines 20 to 22
This segment of the template consists of the CFPOP tag, which retrieves all the message headers. Although it is a small section of the template, it is the second major piece of programming logic in the template.
In the CFPOP tag, three of the four variables created earlier (user, password, and server) are used to open the user’s inbox and access the list of headers.
Unes 48 to 103
Although this segment is the longest of the three by far, in terms of the logic of the program, it is a single unit. In this segment, each header is displayed as a single row of a table to create the inbox you saw earlier in Figure 22.4. This entire section consists of a single CFUlOP clause, which is used to iterate over each row in the query result. It is important to notice that the FROM and TO attributes are used to loop baclcward from the last row to the first in order to display the messages in reverse chronological order. You use inbox. RecordCoUntto specify the last row in the query result.
Next, each of the four columns of the row is output in turn. The first (lines 51 to 59) consist of three single-letter links that provide the capability to reply to, forward, or delete the specified message. Notice how the links are built: They include the value of the token variable, plus a parameter providing the number of the message that is to be affected. In the caseof the Reply To and Forward options, the links are to the COlllPOse.cfln template, and an act; on attribute is set. As you will see later when you look at the compose. cfm template, this action determines the initial appearance of the message composition form.
The three columns are all processed inside a single CFOUTPUT clause. This CFOUTPUT secOOnis used to provide access to the fields in the row specified by each iteration of the loop. ‘The CFLOOP tag itself is not providing access to the fields in the row, but simply providing a counter pointing to the appropriate row. The STARTROW attribute of the CFOUTPUT tag specifies which row is currently being worked with, and MAXROtVS-l ensures that only one row at a time is processed by the CFOUTPUT tag. In the second column of the row, the subject is displayed (Lines 62 to SO).The subject is used as a link so that the user can dick the Subject line to read a specific message. However, displaying the subject requires a bit of thinking. First, what happens if the Subject line is blank? How can the necessary link be displayed? Second, what happens with an extremely long Subject line? This can make the layout of the table unattractive and difficult to use.
This problem is addressed by the following logic, which is represented by the embedded CFIF clauses in lines 63 through 78:
1. Check whether the Subject line is blank. If it is not blank, proceed to the next step; otherwise, display the Subject line as NO SUBJECT.
2. Because the Subject line is not blank, it can be displayed. Therefore, check the length of the Sut)ject line. If it is longer than 27 characters~ then display the first 25 characters of the Subject line followed by an ellipsis; otherwise, lay the cornplete Subject line.
The choice of 27 characters as the cutoff length for shortening a Subject line is purely arbitrary and can be adjusted by the dictates of a specific design. Each Subject line is,displayed as a link to the readmessage. efm template, and the token and message number are passed to this template so that it can retrieve and display the appropriate message.
Displaying the next column, the message’s From line, is a little bit simpler (lines 81 to 89). The only decision that needs to be made here is regarding the length of the From line, because, as with the Subject line, it is possible to have an extremely long From line. Here, you use the arbitrary cutoff of 18 characters to decide when to cut short the From line.
Notice that no provisions are being made for blank From lines. This is because the From line is not being used as a link and, therefore, a blank From line does not affect the functionality of the application. Finally, the last column is displayed (lines 90 to 100). This column is used to display the date of the message.