ColdFusion Development

The ColdFusion Components are a very important piece of the puzzle. The CF (ColdFusion) code will be invisible to the user and is responsible for serving up email contents to Flash. It is also responsible for relayingSimpleton's outgoing mail to the mail server for delivery.

When building this email application, two common protocols will be utilized: POP (Post Office Protocol) and SMTP (Simple Mail Transfer Protocol). POP allows the user to receive messages from the server, and SMTP allows the user to send messages. Given that there will be times when email is only read and not sent, it still makes sense to provide a two-way communication process.

Components (CFCs)

Since ColdFusion MX is the application server of choice, FlashFusion will be developing the code using an exciting new feature: ColdFusion Components (CFCs). CFCs enable the developer to write modular code that can be used again and again. A CFC can contain many methods or functions that handle certain tasks. In the email application, some of these methods will include logging in to the mail server, retrieving email, and sending email. The CFCs will serve as the middleware between Flash and the email server.

FlashFusion has decided to develop a POP and SMTP component, which can be used in future applications. Since Simpleton will be developing interactive applications in the coming months, it makes sense to create reusable code that can be leveraged later. The POP component will be responsible for receiving the log-in request from Flash and returning the email results, through the Flash Gateway, back to the client. This will be a seamless process now that ColdFusion MX has the Flash Remoting service built right in.

CFCs consist of basic CF tags as well as a few new ones. Component templates end with a .cfc extension and are initialized with the <CFCOMPONENT> tag. All component code resides between the starting and ending <CFCOMPONENT> tags. To create a component method, the <CFFUNCTION> tag is used. This tag requires a name attribute, which corresponds to the name of the method that will be called from Flash or any other service. Methods are synonymous with functions in terms of development. If method arguments are necessary within a component, the <CFARGUMENT> tag can be used to set default values and state whether or not they are required.

To call a function from within a CF page, the <CFINVOKE> tag is used. This tag requires the component name and method as parameters, and results can be returned to the page with <CFRESULT>. This will be clearer when the POP and SMTP components are reviewed in detail below. It's also good to note that component methods can be called directly through the URL via myComponent.cfc?method=getTime. This will invoke the getTime method within the component and is very useful when it comes to debugging and testing CFCs. The code shown in Listing 3.1 demonstrates the structure of a CFC:

Listing 3.1

 <cfcomponentname="myComponent"> <cffunctionname="getTime"> //getTimecodegoeshere <cfreturntheTime> </cffunction> <cffunctionname="getTemp"> //getTempcodegoeshere <cfreturntheTemp/> </cffunction> </cfcomponent> 

FlashFusion believes in building component-based applications, and CFMX will allow the application to be built in a manner that is scalable and easy to update. The initial coding of the application will start with the development of the POP and SMTP CFCs. Figure III-3.1 shows the structure of a CFC.

Figure III-3.1. Structure of a ColdFusion MX CFC

Pop.cfc

Simpleton's clients will probably check their email more than doing any other task within the application. Therefore, the process needs to be simple and very efficient. ColdFusion MX has native support for POP via the <CFPOP> tag, and email will be retrieved and returned to CF. The email actually comes back as a WDDX object, which provides a structured way of parsing through the data and grabbing the necessary fields for display. Flash MX now has native support to handle WDDX as a Recordset object using the Flash Remoting classes. The Flash Recordset object has many methods that are accessible to the developer, which allow for better control and formatting of data.

The Pop component only needs to handle three tasks: logging in to the mail server, getting messages, and deleting messages. The <CFPOP> tag is extremely functional and allows for single messages to be retrieved. This will not be necessary in this application, though, since all messages will be retrieved and then stored on the local machine. Therefore, only a few trips will be made to the server instead of going to the server each time a message is selected for reading. This will reduce the amount of time it takes to retrieve the contents of an email, since it will be stored on the local machine. Server load will also be reduced by minimizing the number of connections made to the server.

Along with the three tasks of the Pop component come three corresponding methods:

• login Handles the server log-in

• getMessages Retrieves all email messages from the server

• deleteMessage Deletes a single message from the server specified by the user

The login method. The login method will be invoked from both the getMessages and deleteMessage methods. Whichever method invokes the login method will determine whether email messages are retrieved or a specific email message is deleted. Flash will store the log-in information in a shared object and send it to CF each time a request is made, so the process will be invisible to the user. The code shown in Listing 3.2 shows the CF code for the Pop method.

Listing 3.2

 <!---definetheloginmethod---> <cffunctionname="login"access="remote"return="query"> <!---requireparametersthatwillbepassedfromoneofthe componentmethods---> <cfargumentname="mailServer"required="true"/> <cfargumentname="userName"required="true"/> <cfargumentname="password"required="true"/> <cfargumentname="action"required="true"/> <cfargumentname="uid"required="false"default=0/> <!---callthepoptagandeitherretrieveallemailmessagesor deletethespecifiedmessage---> <cfpopname="email"server="#mailServer#"username="#userName#" password="#password#"action="#action#"u/> <!---querytogettheemailrecordsetfromthemailserver---> <cfquerydbtype="query"name="getEmail">   SELECTbody,subject,date,replyto,uidfromemail   orderbydatedesc; </cfquery> <!---returntheemailrecordsettothecaller---> <cfreturngetEmail/> </cffunction> 

The structure of the Pop component is very similar to the component example covered earlier. The method is declared, and a few arguments are then specified for the method to function properly. If an argument is required butisn't passed in, an error will be thrown and displayed to the page. Specifying an access type of "remote" allows the component method to be called from outside services such as Flash or through the URL.

NOTE For more information on the different component access methods, be sure to view the CF documentation.

Once the arguments are supplied, CF logs in to the mail server and performs the necessary action supplied by the caller. The caller, in this case, is another method from within the component.

The getMessages method. The code in Listing 3.3 shows how two methods from one component can work together to achieve the necessary results. The getMessages method is used to grab all messages from the server. Once it's called, it will invoke the login method and make a request for all messages from the mail server. The login method, shown previously in Listing 3.2, will return the email results to the getMessages method.

Listing 3.3

 <!---definethegetMessagesmethod---> <cffunctionname="getMessages"access="remote"return= "query"> <!---requireargumentsthatwillbepassedfromFlash---> <cfargumentname="mailServer"required="true"/> <cfargumentname="userName"required="true"/> <cfargumentname="password"required="true"/> <!---settheactiontogetALLwhichwillretrieveallemailsfor theuser---> <cfargumentname="action"required="true"default="getAll"/> <!---invoketheloginmethod,passthearguments,andreceive theresults---> <cfinvokecomponent="Pop"method="login"returnVariable=  "emailQuery"argumentCollection="#arguments#"/> <!---returntheemailresultstoFlash---> <cfreturnemailQuery/> </cffunction> 

The getMessages method is fairly straightforward and requires login arguments to be passed from Flash. The action argument is defaulted to getAll so all messages will be retrieved from the mail server. The login method is called using the <CFINVOKE> tag, and the list of arguments is passed into the tag using the argumentCollection attribute. This also makes it easier to manage arguments, since they can be passed into the method as an object and handled accordingly.

This is a daisy chain of events where Flash or any other service can make a call to the getMessages method. The login method is then invoked and returns the email query to getMessages, which in turn hands this information to Flash. This is where the power of components really comes into play. The login method is invoked from other methods in the component, which prevents the need to write redundant code.

The deleteMessage method. The deleteMessage method also interacts with the login method to handle deleting a specific message from the server. The user can select a message in Flash and click the Delete button, and the request is sent through the Flash Gateway to CF. Listing 3.4 shows the deleteMessage method.

Listing 3.4

 <!---definethedeleteMessagemethod---> <cffunctionname="deleteMessage"access="remote"return= "query"> <!---requireargumentsthatwillbepassedfromFlash---> <cfargumentname="mailServer"required="true"/> <cfargumentname="userName"required="true"/> <cfargumentname="password"required="true"/> <!---settheactiontodelete---> <cfargumentname="action"required="true"default="delete"/> <!---theuidoftheemailmessagethatwillbepassedfrom Flash---> <cfargumentname="uid"required="true"/> <!---invoketheloginmethod,passthearguments,anddeletethe message---> <cfinvokecomponent="Pop"method="login"argumentCollection=  "#arguments#"/> </cffunction> <cfinvokecomponent="Pop"method="pop"argumentCollection= "#arguments#"/> </cffunction> 

The deleteMessage method is similar to the getMessages method except for the uid argument. This uid is the unique ID of the email message and tells CF exactly which message to delete from the server. When the application is developed, Flash will pass the uid to the deleteMessage method through the Gateway. Figure III-3.2 shows the CFC methods interacting with each other.

Figure III-3.2. Pop.cfc Method Interaction.

Smtp.cfc

The email application would not be functional just by allowing Simpleton's clients to receive and delete email; they also need to be able to send mail. A completely different component will handle any outgoing messages from the application. The user will be able to compose a new message and send it to the SMTP component to handle delivery. Listing 3.5 shows the necessary code to handle email being sent via SMTP.

Listing 3.5

 <cfcomponentname="smtp"> <!-----------------------------------------sendmethod---- -----------------------------------> <!---ComponentmethodthatreceivestheinformationfromFlash andpassesittothecfmailtag---> <!---definethesendmethod---> <cffunctionname="send"access="remote"> <!---requireargumentsthatwillbepassedfromFlash---> <cfargumentname="to"required="true"/> <cfargumentname="from"required="true"/> <cfargumentname="cc"required="false"default=""/> <cfargumentname="subject"required="true"/> <cfargumentname="mailServer"required="true"/> <cfargumentname="message"required="true"/> <!---usethecfmailtagtosendtheemailtothemailserver---> <cfmailto="#to#"from="#from#"cc="#cc#" subject="#subject#"server="#mailServer#"> #message# </cfmail> </cffunction> </cfcomponent> 

The Smtp component has only one method: send. The send method is similar in structure to our Pop method mentioned earlier but has only one method. It handles the delivery of email by receiving the necessary arguments from Flash and calling the <CFMAIL> tag. The arguments are passed to this tag, and the email is sent to the mail server for delivery. Whenever an email is sent from the application, the Smtp component will be called and the delivery process will begin. The Smtp component structure is very straightforward and will be a perfect fit for sending emails from Flash. Figure III-3.3 shows a diagram of the Smtp CFC.

Figure III-3.3. Smtp.cfc Component Structure.

The server-side components were quick and easy for FlashFusion to develop and will allow for scalability within the application. Not only will this application be able to scale, but also the POP and SMTP components will come in very handy in the future when building new applications. FlashFusion is stressing code reuse to Simpleton as well as keeping code well structured. Now that the ColdFusion components have been put into place, FlashFusion is ready to start the Flash UI development and programming.