Listing 14-1 (Continued) | + forms | + apps | + class | + templates | + images To configure the applications for your directory structure, you’ll have to change the settings shown in Table 14-1. TABLE 14-1 THE survey.conf SETTINGS THAT YOU NEED TO CHANGE Fields Explanation $PEAR_DIR This should be set to the directory where you have installed the PEAR packages. This is needed because the DB class needed for class.DBI.php is part of the PEAR packages. $PHPLIB_DIR This should be set to the directory where the PHPLIB packages are stored. This is needed because the Template class ( template.inc) is part of the PHPLIB packages. $APP_FRAMEWORK_DIR This directory should point to our application framework class directory. $AUTHENTICATION_URL This URL should point the central authentication application ( login.php), which is part of the application framework. $LOGOUT_URL This URL should point to the central logout application ( logout.php), which is part of the application framework. $ROOT_PATH This directory point to the document root directory of your Web site where you host this application. $REL_ROOT_PATH This should point to the relative path, which is the parent of the apps directory. 496 Part III: Developing E-mail Solutions 18 549669 ch14.qxd 4/4/03 9:26 AM Page 496 Fields Explanation $SURVEY_DB_URL This URL should be configured to allow you to connect to the survey database via the named host using the named user name and password. $MAX_DELIVERY_AT_A_TIME This should be set to the maximum number of e-mail deliveries per run by the Survey Execution Manager. You should not set this number to a very large number. $MAX_WAIT_PER_DELIVERY This number sets how many seconds are past before the Survey Execution Manager is recalled via the meta refresh tag. Setting Up the Interface Template Files The applications use a number of template files that are provided in the ch14/ apps/templates directory in the CD-ROM. These files are discussed in Table 14-2. TABLE 14-2 INTERFACE TEMPLATES File Name Purpose survey_menu.ihtml This is the Survey Menu template. survey_add.ihtml This template is used to add surveys. survey_add_form.ihtml This template is used to add survey forms. survey_add_label.ihtml This template is used to add survey form labels. survey_add_list.ihtml This template is used for adding survey lists. survey_execute.ihtml This template is used for executing a survey. It shows the execution status information. survey_report.ihtml This template is used for showing the survey report. survey_status.ihtml This template is used to show status messages. This template is used by the PHPApplication’s show_status() method. powered_by.html This HTML file contains the footer that is added to the survey sent to the end user. Chapter 14: E-mail Survey System 497 18 549669 ch14.qxd 4/4/03 9:26 AM Page 497 These templates also use images that are stored in an image directory called images within the template directory pointed by the $TEMPLATE_DIR variable in the survey.conf file. Setting Up the Central Survey Messages File All the applications in the survey suite use a central messages file called survey. messages , which is shown in Listing 14-2. Listing 14-2: survey.messages <?php $MESSAGES[‘US’][‘LIST_DELETE_SUCCESSFUL’] = “List deleted.”; $MESSAGES[‘US’][‘LIST_DELETE_FAILED’] = “List not deleted.”; $MESSAGES[‘US’][‘LIST_UPLOAD_SUCCESSFUL’] = “List upload successful.”; $MESSAGES[‘US’][‘LIST_UPLOAD_FAILED’] = “List upload failed.”; $MESSAGES[‘US’][‘FORM_UPLOAD_SUCCESSFUL’] = “Form upload successful.”; $MESSAGES[‘US’][‘FORM_UPLOAD_FAILED’] = “Form upload failed.”; $MESSAGES[‘US’][‘FORM_DELETED’] = “Form deleted.”; $MESSAGES[‘US’][‘FORM_NOT_DELETED’] = “Form not deleted.”; $MESSAGES[‘US’][‘SURVEY_ADD_FAILED’] = “Survey not added.”; $MESSAGES[‘US’][‘SURVEY_ADD_SUCCESSFUL’] = “Survey added.”; $MESSAGES[‘US’][‘SURVEY_DELETE_SUCCESSFUL’] = “Survey deleted.”; $MESSAGES[‘US’][‘SURVEY_DELETE_FAILED’] = “Survey not deleted.”; $MESSAGES[‘US’][‘SURVEY_SENT’] = “Survey sent.”; ?> The default language of the messages is set in the survey.conf file using the $DEFAULT_LANGUAGE parameter. If you want to port this application to a different language, copy the above messages at the end of this file and change US to your two-digit language name and replace the English error messages with the appropri- ate translation. Google has a translation tool that can be used to translate simple messages to other languages such as Spanish, Italian, German, and so on. See www. google.com for details. Setting Up the Central Survey Errors File Like the central messages file, all the applications in the survey system use the survey. errors file for error messages, as shown in Listing 14-3. 498 Part III: Developing E-mail Solutions 18 549669 ch14.qxd 4/4/03 9:26 AM Page 498 Listing 14-3: survey.errors <?php // Errors for survey apps $ERRORS[‘US’][‘APP_FAILURE’] = “Application failure”; $ERRORS[‘US’][‘ADD_SURVEY_LIST_REQ_MISSING’] = “Please enter list and file name”; $ERRORS[‘US’][‘ADD_SURVEY_FORM_REQ_MISSING’] = “Please enter form and file name”; $ERRORS[‘US’][‘IHTML_REQUIRED’] = “IHTML file expected”; $ERRORS[‘US’][‘FIELD_NUM_INVALID’] = “Number of fields has to be a number greater than zero”; $ERRORS[‘US’][‘LIST_NO_LIST_CHOSEN’] = “Please select a list.”; $ERRORS[‘US’][‘FORM_NOT_SELECTED’] = “Please select a form.”; $ERRORS[‘US’][‘ADD_SURVEY_NAME_MISSING’] = “Please enter a survey name.”; $ERRORS[‘US’][‘ADD_SURVEY_LIST_MISSING’] = “Please select a survey list.”; $ERRORS[‘US’][‘ADD_SURVEY_FORM_MISSING’] = “Please select a survey form.”; $ERRORS[‘US’][‘DEL_SURVEY_ID_MISSING’] = “Please select a survey.”; $ERRORS[‘US’][‘RUN_SURVEY_ID_MISSING’] = “Please select a survey.”; $ERRORS[‘US’][‘ADD_FORM_MISSING_SUBJECT’] = “Please enter a subject line.”; $ERRORS[‘US’][‘ADD_FORM_MISSING_FROM’] = “Please enter a from address.”; $ERRORS[‘US’][‘SURVEY_EXECUTION_FAILED’] = “Survey execution failed.”; $ERRORS[‘US’][‘SURVEY_ALREADY_SUBMITTED’] = “Survey already submitted.”; $ERRORS[‘US’][‘SURVEY_SUBMITTED’] = “Survey submitted. \\n\\nThank you.”; $ERRORS[‘US’][‘REPORT_NOT_SELECTED’] = “Please select a report.”; ?> Creating Survey Forms The survey forms that are used in the survey system are HTML files that have a few specific requirements. They are listed here: ◆ Form action value should be set to {SERVER_URL}{APP_PATH}/ {SURVEY_RESPONSE} as shown here: <form action=”{SERVER_URL}{APP_PATH}/{SURVEY_RESPONSE}”> ◆ The form must contain the mainBlock comments as shown here: <! BEGIN mainBlock > Your form data goes here <! ENDBEGIN mainBlock > ◆ You can only personalize the form using the {FIRST} and {LAST} tags. Chapter 14: E-mail Survey System 499 18 549669 ch14.qxd 4/4/03 9:26 AM Page 499 ◆ Each field in the HTML form must be named using numbers. ◆ Each question can be either a text box (the maximum size is limited by the database, currently set to 50 characters), a checkbox, a radio button, or a drop-down select list. ◆ A set of hidden fields are a must to allow proper handing of the form. These fields are shown here: <input type=hidden name=”SURVEY_ID” value=”{SURVEY_ID}”> <input type=hidden name=”SUID” value=”{SUID}”> <input type=hidden name=”EXEC_ID” value=”{EXEC_ID}”> <input type=hidden name=”EXEC_TS” value=”{EXEC_TS}”> A sample form is available in ch14/forms directory in the CDROM. The {POWERED_BY_LOGO} tag is optional. Testing the Survey System When you’ve configured the application using survey.conf and installed it per the configuration under your web server’s document root, you can test the system. To test the system you need to create a CSV file with the following format: EMAIL, FIRST, LAST A sample CSV file called mycustomers.csv is shown in Listing 14-4. Listing 14-4: mycustomers.csv KABIR@evoknow.com,MOHAMMED,KABIR joe@evoknow.COM,Joe,Gunchy jennifer@evoknow.com,JENNIFER,GUNCHY abe@EVOKNOW.COM,ABE,NONE rome@EvoKnow.Com,rome,ahead Notice that this list has badly formatted e-mails and names. Because the List Manager can filter name and e-mail for case issues, you can fix these during list creation. 500 Part III: Developing E-mail Solutions 18 549669 ch14.qxd 4/4/03 9:26 AM Page 500 . needed because the DB class needed for class.DBI .php is part of the PEAR packages. $PHPLIB_DIR This should be set to the directory where the PHPLIB packages are stored. This is needed because. authentication application ( login .php) , which is part of the application framework. $LOGOUT_URL This URL should point to the central logout application ( logout .php) , which is part of the application framework. $ROOT_PATH. PHPLIB packages are stored. This is needed because the Template class ( template.inc) is part of the PHPLIB packages. $APP_FRAMEWORK_DIR This directory should point to our application framework class