addModifyMessage() This method is used to add or modify messages. It works as follows: ◆ First, it prepares the $params array with all the message field values from the user request. ◆ Then it creates an object of AccessControl to add or modify the access to the message. ◆ When the mode for the method is add, the $params array is fed into the addMessage() method of the Message class to add the new message. If the addition fails, the method shows a failure message and returns. ◆ If the addition operation is successful, the authorized IPs are added to the database using the addAccessIPs() method of the AccessControl class. And then a successful addition message is shown to the user. ◆ When the mode for the method is modify, the $params array is fed into the modifyMessage() method of Message class to update the given mes- sage. If the update fails, the method shows a failure message and returns. ◆ If the update operation is successful, the authorized IP addresses are added to the database using addAccessIPs() method of the AccessControl class after deleting the previous IPs. And then a successful update mes- sage is shown to the user. deleteMessage() This method is used for deleting messages. This works as follows: ◆ First, it checks whether the message ID has been supplied or not. If not, it shows an alert message and returns null. ◆ Then a new Message object $msgObj is created and the deleteMessage() method of $msgObj is used to delete the message. ◆ If deletion succeeds, the AccessControl class is used to delete the related IPs from the authorized table for the message. ◆ At the end, a status message is shown depending on the outcome of the deletion operation. 456 Part III: Developing E-mail Solutions 17 549669 ch13.qxd 4/4/03 9:26 AM Page 456 Creating a Tell-a-Friend Form Processor Application This application, taf.php, is the core part of the system that is responsible for han- dling the form submission requests from users. This application is included on the CD-ROM in the ch13/apps directory. It implements the following functionalities: ◆ Processes the form submitted by the users and updates the database accordingly. ◆ Sends appropriate mails to newly added friends and the originator of those friends. To achieve those functionalities, it uses the following methods. run() When the application is run, this method is called. It simply calls the processRequest() method to process the submit request from the user. processRequest() This method is responsible for handling the request and takes the action thereby. This is how it works: ◆ First, it checks whether the form ID is supplied or not. If not, it shows an alert message and returns null. ◆ Then it verifies if the originator e-mail has been provided from the form or not. If not, it returns null after showing an alert. ◆ Then it uses the AccessControl class to check whether the request IP address is banned from submitting friends for this form. If it is banned, then it shows the appropriate alert and returns null. ◆ Then an object of the Form class, named $frmObj, is created. ◆ $frmObj retrieves the activation date and termination date for the form and checks whether the current time falls into a valid time range. If not, it shows an alert message and returns null. Chapter 13: Tell-a-Friend System 457 17 549669 ch13.qxd 4/4/03 9:26 AM Page 457 ◆ Then the campaign message ID is retrieved (the one to be sent to the new friends for this form) and $msgObj, an object of Message class, is used to get and store the information on that message. ◆ For each friend supplied by the user request, the method first checks whether the friend e-mail is already unsubscribed. If not, the friend’s sub- mission data is added in to the submission table and the friend is sent the campaign message along with links for subscription and unsubscription. ◆ Then the message ID to be sent to the originator is retrieved using $frmObj and given to $msgObj for information on that message. That message along with information on the successfully submitted friends is sent to the originator. This also contains a link to the scorecard for the originator. ◆ At the end, a status message is shown to the user saying that her submis- sion has been granted and a mail has been sent to her with details. Creating a Tell-a-Friend Subscriber Application This application, taf_subscribe.php, is responsible for handling the subscription requests from friends. This application is included on the CD-ROM in the ch13/apps directory. It implements the following functionalities: ◆ Checks whether the request is valid via the authorize() method. ◆ Updates database according to the subscription request. To achieve those functionalities it uses the following methods. run() When the application is run, this method is called. It simply calls the processRequest() method to process the subscription request from the friend. authorize() This method is used to verify the authenticity of the request. This is how it works: ◆ Ideally, friends access this application through the link provided by the Form Handler application. And that link contains a check flag that is used here to verify. 458 Part III: Developing E-mail Solutions 17 549669 ch13.qxd 4/4/03 9:26 AM Page 458 ◆ The encrypted check flag is decrypted and matched with the other para- meters from the link. If the matching fails, the method returns false. ◆ Even after the matching succeeds, a second checking is done using the friend ID that was hidden in the check flag. This friend ID is matched with all the friend IDs of the database and checked to see whether the corre- sponding e-mail is same as the e-mail hidden in the check flag. The method returns TRUE or FALSE depending on this matching result. processRequest() This method is used to process the subscription data and update the database thereby. It works as follows: ◆ First it creates an array named $param with the form ID, friend e-mail, subscription status (sub or unsub), originator e-mail, and subscription time stamp. ◆ Then the array is passed into the addSubscriptionData() method of the Form class to add the subscription data. ◆ If the addition is successful and the subscription type is sub (which means the friend agreed to subscribe to the system), an e-mail is sent to the friend. ◆ The e-mail to be sent to the friend is decided from the subscription mes- sage ID specified while setting up the form. This ID is retrieved using the Form class and then fed into the Message class to get its details. ◆ At the end, the friend is shown a status message depending on the sub- scription data addition status. Creating a Tell-a-Friend Reporter Application This application, taf_reporter.php, is responsible for generating reports for the system. This application included on the CD-ROM in the ch13/apps directory. It implements the following functionalities: ◆ Produces a report for form creator with subscription ratio and other details. ◆ Produces a scorecard report for friend originator. These are the methods used by the application. Chapter 13: Tell-a-Friend System 459 17 549669 ch13.qxd 4/4/03 9:26 AM Page 459 run() This method is called when the application is run. It decides, from the cmd value of the request, which report to generate (form creator or originator). And then it either calls generateFormCreatorReport() for the form creator report or generateOriginReport() for the originator report. generateFormCreatorReport() This method is used for showing a report to the form creator for her form. It works as follows: ◆ First, it takes the form ID and checks whether the form is accessible by the request IP. If not, it shows an alert message and returns null. ◆ Then a creator report template (TAF_CREATOR_REPORT_TEMPLATE) is loaded in a template object called $template. ◆ On the top of the template, the form summary is displayed using the methods getFormInfo(), getFriendList(), getNumberOfSubscriber(), and getNumberOfUnsubscriber() of the Form class. ◆ In the lower part of the template, a block for top originators is set using the getOriginSubmissions() and getNumSubscriptionPerOrigin() methods of the Form class. ◆ At the end, the template is parsed and printed to the form creator to give her a complete report on the form. generateOriginReport() This method is used for showing the report to the friend originator for a given form. It works as follows: ◆ First, it validates the check flag from the user request that is given from the form handler application. It shows an alert message and returns null if the validation fails. ◆ Then an originator report template (TAF_ORIGIN_REPORT_TEMPLATE) is loaded in a template object called $template. ◆ Then the getFriendsByOrigin() method of the Form class is used to retrieve the list of friends originated by this user. ◆ Then the status of each friend is retrieved using the getSubscriptionStatus() method of the Form class. This status along with different scores (like score per subscription and score per submission) is used to set the score per friend for the originator. 460 Part III: Developing E-mail Solutions 17 549669 ch13.qxd 4/4/03 9:26 AM Page 460 . 4/4/03 9:26 AM Page 456 Creating a Tell-a-Friend Form Processor Application This application, taf .php, is the core part of the system that is responsible for han- dling the form submission requests. her with details. Creating a Tell-a-Friend Subscriber Application This application, taf_subscribe .php, is responsible for handling the subscription requests from friends. This application is included. data addition status. Creating a Tell-a-Friend Reporter Application This application, taf_reporter .php, is responsible for generating reports for the system. This application included on the CD-ROM