Christian Web Host, Java Programming - Cheap Web Hosting Blog

Chapter 13: Tell-a-Friend System 469 If the friend decides to subscribe by clicking on the subscription link, she will get another mail confirming that she has been subscribed. This message look like what you see in Figure 13-9. Figure 13-9: A message to friend who subscribes. Remember: This message is created in the message body contents you entered via the message manager application. Whenever a user (originator) submits friends via the Tell-a-Friend form, she gets a message as well. This message can look as shown in Figure 13-10. Figure 13-10: A message to the originator who referred friends.

468 Part III: Developing E-mail Solutions Figure 13-7: A Tell-a-Friend form received by a user. Figure 13-8: Message to a friend as referred by the originator.

Chapter 13: Tell-a-Friend System 467 Copy the information given in the textarea box; you need this for your actual HTML Tell-a-Friend form. The form action of your HTML Tell-a-Friend form has to be exactly as shown in this screen. Also, the hidden field set stores the formid needed in your form. Each Tell-a-Friend form must include . A valid form action that points to the Tell-a-Friend form processor application. . A hidden field that has the formid assigned during form setup. . An originator e-mail field. Typically, this will be a hidden field if the form is used in an e-mail campaign. It can be an input field as well if you want the user to enter his e-mail address or your e-mail campaign software cannot customize a message with e-mail fields. I ve provided two sample Tell-a-Friend forms in the taf directory. You can modify these forms to fit your requirements. For example, say you want to use sample_taf_form1.html in an e-mail campaign where the message will embed this form. In this case, you need to make sure that the following hidden field is set up correctly: Change the value to a personalization tag that your e-mail campaign software will replace with the e-mail address of the person who is receiving the campaign. For example: If your campaign software will personalize the message where {EMAIL} will be replaced with the e-mail address of the recipient of the campaign, then you can use this tag. For testing purposes, you can hardcode this value to your own e-mail address for now. After you have the messages and form set up, you re ready to test the Tell-a- Friend system. Send the Tell-a-Friend form via e-mail to yourself or use your web browser to load it on your browser. Figure 13-7 is a Tell-a-Friend form received by a user as part of an e-mail campaign. When the user fills out the form and clicks on the button to submit, she will be entering the friends into the Tell-a-Friend system. The friends she enters will receive an e-mail message that introduces the product or service to them. Such a message can look like the one shown in Figure 13-8. Remember: This message is created using the taf/apps/templates/ taf_frnd_msg.html file and the message body contents you entered via the message manager application. If the friend decides to subscribe, she can click on the subscription link; or she can choose to remove herself from any mailing in the future. By default, you should never include any of the friends who do not respond either way in any future mailing.

466 Part III: Developing E-mail Solutions Give a name to your form; select the date you want the data submission to be activated. This is the date when the Tell-a-Friend system will start accepting data requests for this form. Select a suitable termination date, which is when the Tell-a- Friend system will stop accepting data for this form. The termination date is very useful if you tie the Tell-a-Friend form with a limited-time promotional activity. Select the messages that you created earlier as appropriate. Enter the maximum number of submissions (friend referrals) that a person (the originator who received your e-mail campaign message) can make. This limit is needed to protect your system against people who would try to add many friends addresses if there is any promotion attached to the Tell-a-Friend campaign. For example, if you offered the top 100 people with the most friends submitted and/or friend subscriptions some prizes, some people would submit too many e-mail addresses. For each submission, assign a score for the originator by setting the Score Per Submission field. This score is given to the originator every time she fills out the Tell-a-Friend form received via an e-mail campaign or other means. Whenever a friend referred by the originator opts into become a subscriber by clicking on the subscription link in the e-mail she receives, the originator can get another score for delivering a new lead or customer. This score is set by Score Per Subscription field. If you have any reason to disallow one or more IP address or IP networks from submitting Tell-a-Friend referrals, you can ban them using the Disallow Submissions from IP field. Enter a single IP such as 192.168.1.123 or partial IP (network address) such as 192.168 per line. If you want to restrict access to the form setup or report scripts, use the Restrict Form Setup/Report to IP field. Click on the Add Form button and you ll see a screen similar to Figure 13-6. Figure 13-6: Form information.

Chapter 13: Tell-a-Friend System 465 Figure 13-4: Adding the message for friends. Figure 13-5: Setting up a Tell-a-Friend form.

464 Part III: Developing E-mail Solutions Creating Msg for Friend (Introduction Msg) The first step is to create an introductory message for the friends who would be referred by other friends filling out the Tell-a-Friend form. Run http://yourserver/taf/apps/taf_mngr.php, which should bring up a menu interface as shown in Figure 13-3. Figure 13-3: Tell-a-Friend system main menu. Click on the Add a New Message link, which will show the screen shown in Figure 13-4. Fill out this form and decide if you want to restrict access to this message by IP/network. For example, if you don t want anyone to modify or delete this message from somewhere else, and you have a static IP network (most offices do), you can enter the IP address of your PC or the network in the Restrict Message Setup to IP Networks field. For your convenience, your current IP address is shown on the top of the form. Similarly, add two other messages: one for the originator who refers friends via the Tell-a-Friend form and the other for the friend who decides to subscribe by clicking on the subscription link shown by the very first message she gets from your Tell-a-Friend system. When you have three messages set up, you re ready to set up a Tell-a-Friend form. From the main menu, click on the Setup a Tell-a-Friend Form link, which shows a screen similar to Figure 13-5.

Chapter 13: Tell-a-Friend System 463 To set up a Tell-a-Friend form, you need to do the following: . Create three messages using Tell-a-Friend message manager. One message is for friends who get e-mail because another friend gives their name and information to your Tell-a-Friend system. This e-mail should introduce the friend to what you have to offer. For example, if you re interested in signing up people for a newsletter, you should state what the newsletter has to offer in this message. This message is created using the taf_frnd_msg.html template file in the template directory. So if you want to control the look and feel of this message, you should modify this template. Make sure if you use any images in the template, the images are directly accessible from your Web site. In other words, use fully qualified path names for images. For example, instead of using use . Remember: This is a message template for all messages to friends, so don t customize it for a single campaign. Your actual content of the message is entered via the form manager application. The content is inserted dynamically into the message template by replacing the {FRND_MSG} tag in the template. The second message you need to set up is for the originator who submits the friend s name. This is usually a thank-you message for helping you market your product/services/information. This message is sent using the taf_frnd_msg.html template. The actual content of the message is entered via the form manager like the friend s message. The third message is the subscription message and it s sent when a friend actually clicks on the subscription link (in the introduction mail generated by taf_frnd_msg.html) and subscribes to your offer. Note that when a friend decides to unsubscribe, she does not receive an e-mail, but a confirmation of her unsubscription status is shown on the web browser when she clicks on the remove or unsubscription link from the introduction mail. . Create the form with a form action that runs the Tell-a-Friend form processor application. When you set up the form with the Tell-a-Friend form manager, the form action is given to you at the end of the process, so you can simply copy and paste the form action from there. After you ve set up the messages and the Tell-a-Friend form, you can use your form in e-mail campaigns. In the following section, I discuss a Tell-a-Friend campaign from setup to execution.

462 Part III: Developing E-mail Solutions Say your database server is called db.domain.com and the user name and password to access the TELL_A_FRIEND databases (which you will create during this installation process) are admin and db123. In such a case, you would modify the database access URLs throughout each configuration file as: define( TAF_DB_URL , mysql://admin:db132@db.domain.com/TELL_A _FRIEND ); If you change the database name from TELL_A_FRIEND to some other name make sure the database prefix in the following configuration lines are changed accordingly: /* —– DEFINE TABLE NAMES ———–*/ define( TAF_FRM_TBL , TELL_A_FRIEND.TAF_FORM ); define( TAF_FRM_OWNER_IP_TBL , TELL_A_FRIEND.TAF_FRM_OWNER_IP ); define( TAF_FRM_RESTRICT_IP_TBL , TELL_A_FRIEND.TAF_FRM_BANNED_IP ); define( TAF_MSG_OWNER_IP_TBL , TELL_A_FRIEND.TAF_MSG_OWNER_IP ); define( TAF_MSG_TBL , TELL_A_FRIEND.TAF_MESSAGE ); define( TAF_FRM_SUBMTN_TBL , TELL_A_FRIEND.TAF_SUBMISSION ); define( TAF_SUBSCRIPTION_TBL , TELL_A_FRIEND.TAF_SUBSCRIPTION ); 4. Set file/directory permissions. Make sure you ve changed the file and directory permissions such that your intranet web server can access (read) all the files. After you ve performed the preceding steps, you re ready to test your Tell-a- Friend applications. Testing the Tell-a-Friend System Now that you re ready to test your system, the very first step is to create a Tell-a- Friend form. I ve supplied two sample Tell-a-Friend forms called sample_taf_ form1.html and sample_taf_form2.html in the taf directory.

Chapter 13: Tell-a-Friend System 461 . After setting the score per each friend, the total score for the originator is calculated and set at the bottom of the template. . At the end, the template is parsed and printed to the user to give her a scorecard report. Installing a Tell-a-Friend System Here I assume that you re using a Linux system with MySQL and Apache server installed. Your Internet web server document root directory is /evoknow/ intranet/htdocs. Of course, if you have a different path, which is likely, you should change this path whenever you see it in a configuration file or instruction in this chapter. During the installation process, I refer to this directory as %DocumentRoot%. I also assume that you ve installed the PHPLIB and PEAR library. Normally, these get installed during PHP installation. For your convenience, I ve provided these in the lib/phplib.tar.gz and lib/pear.tar.gz directories on the CD-ROM. In these sample installation steps, I assume that these are installed in the /%DocumentRoot%/phplib and /%DocumentRoot%/pear directories. Because your installation locations for these libraries are likely to differ, make sure you replace these paths in the configuration files. Here is how you can get your Tell-a-Friend applications up and running: 1. Install the application framework. If you have not yet installed the application framework discussed in Chapter 4, you must do so before proceeding further. 2. Install the Tell-a-Friend Database. The quickest way to create the Tell-a- Friend database is to run the following commands: mysqladmin u root p create TELL_A_FRIEND mysql u root p D TAF < taf.sql 3. Install the Tell-a-Friend applications. Now from the ch13 directory on the CD-ROM, extract ch13.tar.gz in %DocuemntRoot%. This will create taf in your document root. Configure %DocumentRoot%/taf/apps/ contact.conf for path and database settings. The applications are installed in the %DocumentRoot%/taf/apps directory and the templates are stored in %DocumentRoot%/taf/apps/templates. If your MySQL server is hosted on the web server, it can be accessed via localhost. However, if this is not the case, you can easily modify the database URLs in each application s configuration files. For example, the contact.conf file has a MySQL database access URLs such as the following: define( TAF_DB_URL , mysql://root:foobar@localhost/TELL_A_FRI END );

460 Part III: Developing E-mail Solutions 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.