◆ First it checks to see if the user has chosen a survey ID ($survey_id) or not. If not, it displays an error message and exits. ◆ If the survey ID is found, the method then creates a Survey object using the given survey ID ($survey_id) and gets the details of the survey using the getSurveyInfo() method. The STATUS field of the survey is stored in the $status variable. If the given survey does not exist in the database, the method exists with an error message. ◆ When the survey information is located, the method determines if this was being called before. If it was called before, the $lastrow information is set to the last row processed for this campaign. ◆ If the $lastrow is empty then the executeSurvey() method creates an execution record in the SURVEY_EXECUTION table using the addExecution Record() method of the Survey object. This record is used to identify that the current survey was executed at the current time. The newly created execution record ID (EXEC_ID) is returned by the addExecutionRecord() method, and it is used as a hidden field within the survey form to allow the survey response manager to identify which survey execution the user is responding to. ◆ Using the $lastrow and maximum delivery per run ($MAX_DELIVERY_ AT_A_TIME ) value, the getTargetData() method is used to get the list of target records for the current run of the executeSurvey() method. ◆ The survey form is loaded into an HTML template, and it is personalized per the survey recipient and sent via e-mail. ◆ Once the current set of records is processed and delivered, a status message is displayed on the screen using an HTML template. This template has a meta tag to refresh the screen automatically after $MAX_WAIT_PER_DELIVERY delay, which is configurable form the survey.conf file. ◆ The application is automatically called from the status message page and it restarts the entire process automatically and starts exactly where it left off. This allows the application to run large campaigns without having to deal with web browser timeout. authorize() See the authorize() method in the “Developing Survey Manager” section for details. Developing Survey Response Manager This application is responsible for submitting survey responses to the survey data- base. When an end user who received a survey via e-mail clicks on the Submit button, this application is called and it stores the result in the database. The ch14/ apps/survey.php file in the CDROM implements this application, which uses the following methods. Chapter 14: E-mail Survey System 491 18 549669 ch14.qxd 4/4/03 9:26 AM Page 491 run() The run method performs the usual checks for authenticated and authorized users and then calls the addRecord() method to add the survey response. addRecord() This method is responsible for adding the response record in the database. It works as follows: ◆ A SurveyResponse object is created with the user ID ($SUID) and survey execution ID ($EXEC_ID) that are collected from the submitted survey response. Note that the values are supplied as hidden data when the survey form is mailed out. ◆ After the SurveyResponse object is created, the isSubmitted() method is called to see if this participant has already submitted this particular survey response or not. If she has submitted a response for this particular execution of the survey, a status message is shown to inform her that the survey has already been submitted earlier. No data is added to the database. ◆ On the other hand, if this is the first time she is submitting the response data, the addSubmitRecord() is used to create a submission record for this survey execution in the SURVEY_RESPONSE_RECORD table. ◆ Then the response data is added to the appropriate table (SURVEY_RESPONSE) using the add() method for the SurveyResponse object. Developing Survey Report Manager This application displays the survey report. The ch14/apps/survey_rpt_mngr.php file in the CDROM is an implementation of this application. It uses the following methods. run() The run method performs the usual checks for authenticated and authorized user and then calls the showSurveyReport() method to display the survey report. showSurveyReport() This method shows the survey report. It works as follows: ◆ First, it checks to see if the user chose the survey’s execution ID ($exec_id) from the Survey Manager interface. The execution ID is used to create the report. ◆ A report template is loaded and a SurveyReport object is created. ◆ The report column ordering is set using the $orderid field, which is stored in the report column heading. 492 Part III: Developing E-mail Solutions 18 549669 ch14.qxd 4/4/03 9:26 AM Page 492 ◆ Using the SurveyReport object’s getSurveyResponse() method, a list of responses are retrieved from the database for the chosen execution of the survey. ◆ Each response is then displayed. ◆ The getResponseDateRage() and getTotalResponseCount() methods are used to display the range of date and the total response record count. toggleDescField() This is a utility method that toggles the DESC value from desc to null. The DESC value is used in creating ascending or descending order for the displayed columns in the report table. authorize() See the authorize() method in the “Developing Survey Manager” section for details. Setting Up the Central Survey Configuration File Each of the applications in the survey system uses a central configuration file called survey.conf, which is shown in Listing 14-1. Listing 14-1: survey.conf <?php error_reporting(E_ALL); $PEAR_DIR = $_SERVER[‘DOCUMENT_ROOT’] . ‘/pear’ ; $PHPLIB_DIR = $_SERVER[‘DOCUMENT_ROOT’] . ‘/phplib’; $APP_FRAMEWORK_DIR = $_SERVER[‘DOCUMENT_ROOT’] . ‘/framework’; $PATH = $PEAR_DIR . ‘:’ . $PHPLIB_DIR . ‘:’ . $APP_FRAMEWORK_DIR; ini_set( ‘include_path’, ‘:’ . $PATH . ‘:’ . ini_get(‘include_path’)); $AUTHENTICATION_URL = “/login/login.php”; $LOGOUT_URL = “/logout/logout.php”; $APPLICATION_NAME = ‘SURVEY’; $XMAILER_ID = ‘Survey System Version 1.0’; $DEFAULT_LANGUAGE = ‘US’; Continued Chapter 14: E-mail Survey System 493 18 549669 ch14.qxd 4/4/03 9:26 AM Page 493 Listing 14-1 (Continued) $ROOT_PATH = $_SERVER[‘DOCUMENT_ROOT’]; $REL_ROOT_PATH = ‘/survey_tool’; $REL_APP_PATH = $REL_ROOT_PATH . ‘/apps’; $REL_FORMS_DIR = $REL_ROOT_PATH . ‘/forms’; $UPLOAD_DIR = $ROOT_PATH . $REL_ROOT_PATH . ‘/uploads’; $FORMS_DIR = $ROOT_PATH . $REL_FORMS_DIR; $TEMPLATE_DIR = $ROOT_PATH . $REL_APP_PATH . ‘/templates’; $CLASS_DIR = $ROOT_PATH . $REL_APP_PATH . ‘/class’; //Classes $SURVEY_LIST_CLASS = $CLASS_DIR . ‘/’ . ‘class.SurveyList.php’; $SURVEY_FORM_CLASS = $CLASS_DIR . ‘/’ . ‘class.SurveyForm.php’; $SURVEY_CLASS = $CLASS_DIR . ‘/’ . ‘class.Survey.php’; $SURVEY_RESPONSE_CLASS = $CLASS_DIR . ‘/’ . ‘class.SurveyResponse.php’; $SURVEY_REPORT_CLASS = $CLASS_DIR . ‘/’ . ‘class.SurveyReport.php’; require_once “survey.errors”; require_once “survey.messages”; require_once ‘DB.php’; require_once $APP_FRAMEWORK_DIR . ‘/’ . ‘constants.php’; require_once $APP_FRAMEWORK_DIR . ‘/’ . $APPLICATION_CLASS; require_once $APP_FRAMEWORK_DIR . ‘/’ . $ERROR_HANDLER_CLASS; require_once $APP_FRAMEWORK_DIR . ‘/’ . $AUTHENTICATION_CLASS; require_once $APP_FRAMEWORK_DIR . ‘/’ . $DBI_CLASS; require_once $TEMPLATE_CLASS; // Application names $SURVEY_MNGR = ‘survey_mngr.php’; $SURVEY_FORM_MNGR = ‘survey_form_mngr.php’; $SURVEY_LIST_MNGR = ‘survey_list_mngr.php’; $SURVEY_RPT_MNGR = ‘survey_rpt_mngr.php’; $SURVEY_EXEC_MNGR = ‘survey_exec_mngr.php’; $SURVEY_RESPONSE_MNGR = ‘survey.php’; $SURVEY_CLASS = $CLASS_DIR . ‘/class.Survey.php’; $REL_TEMPLATE_DIR = $REL_APP_PATH . ‘/templates/’; $SURVEY_DB_URL = ‘mysql://root:foobar@localhost/SURVEY’; $MAX_DELIVERY_AT_A_TIME = 1; 494 Part III: Developing E-mail Solutions 18 549669 ch14.qxd 4/4/03 9:26 AM Page 494 $MAX_WAIT_PER_DELIVERY = 5; /* START TABLE NAMES */ $SURVEY_TBL = ‘SURVEY’; $SURVEY_LIST_TBL = ‘SURVEY_LIST’; $SURVEY_LIST_DATA_TBL = ‘SURVEY_LIST_DATA’; $SURVEY_FORM_TBL = ‘SURVEY_FORM’; $SURVEY_RESPONSE_TBL = ‘SURVEY_RESPONSE’; $SURVEY_FORM_FIELD_LBL_TBL = ‘SURVEY_FORM_FIELD_LBL’; $SURVEY_RESPONSE_RECORD_TBL = ‘SURVEY_RESPONSE_RECORD’; $SURVEY_EXECUTION_TBL = ‘SURVEY_EXECUTION’; /* END TABLE NAMES */ $STATUS_TEMPLATE = ‘survey_status.ihtml’; $SURVEY_MENU_TEMPLATE = ‘survey_menu.ihtml’; $SURVEY_ADD_LIST_TEMPLATE = ‘survey_add_list.ihtml’; $SURVEY_ADD_FORM_TEMPLATE = ‘survey_add_form.ihtml’; $SURVEY_ADD_LABEL_TEMPLATE = ‘survey_add_label.ihtml’; $SURVEY_ADD_TEMPLATE = ‘survey_add.ihtml’; $SURVEY_EXECUTION_TEMPLATE = ‘survey_execute.ihtml’; $SURVEY_REPORT_TEMPLATE = ‘survey_report.ihtml’; $SURVEY_POWERED_BY_TEMPLATE = ‘powered_by.html’; /* REPORT */ $REPORT_EVEN_ROW_COLOR = ‘#ffccff’; $REPORT_ODD_ROW_COLOR = ‘#ccccff’; ?> For the preceding sample configuration file, the directory structure is shown here: htdocs ($ROOT_PATH = %DocumentRoot%) | + survey_tool | + uploads Continued Chapter 14: E-mail Survey System 495 18 549669 ch14.qxd 4/4/03 9:26 AM Page 495 . ‘survey_mngr .php ; $SURVEY_FORM_MNGR = ‘survey_form_mngr .php ; $SURVEY_LIST_MNGR = ‘survey_list_mngr .php ; $SURVEY_RPT_MNGR = ‘survey_rpt_mngr .php ; $SURVEY_EXEC_MNGR = ‘survey_exec_mngr .php ; $SURVEY_RESPONSE_MNGR. ‘:’ . $PHPLIB_DIR . ‘:’ . $APP_FRAMEWORK_DIR; ini_set( ‘include_path’, ‘:’ . $PATH . ‘:’ . ini_get(‘include_path’)); $AUTHENTICATION_URL = “/login/login .php ; $LOGOUT_URL = “/logout/logout .php ; $APPLICATION_NAME. $CLASS_DIR . ‘/’ . ‘class.SurveyList .php ; $SURVEY_FORM_CLASS = $CLASS_DIR . ‘/’ . ‘class.SurveyForm .php ; $SURVEY_CLASS = $CLASS_DIR . ‘/’ . ‘class.Survey .php ; $SURVEY_RESPONSE_CLASS = $CLASS_DIR