are created from external comma-separated value (CSV) files that are uploaded by the survey administrator. The ch14/apps/class/class.SurveyList.php file in the CDROM is an implementation of this class. I will discuss the methods available in this class. SURVEYLIST() This is the constructor method, which performs the following tasks: ◆ Sets a member variable called list_tbl to $SURVEY_LIST_TBL, which is loaded from the survey.conf file. The $SURVEY_LIST_TBL variable holds the name of the survey list table. ◆ Sets a member variable called list_data_tbl to $SURVEY_LIST_DATA_TBL, which is loaded from the survey.conf file. The $SURVEY_LIST_DATA_TBL variable holds the name of the list data table. ◆ Sets a member variable named dbi to point to the class.DBI.php-provided object, which is passed to the constructor by an application. The dbi mem- ber variable holds the DBI object, which is used to communicate with the back-end database. ◆ This method calls the setSurveyListID() method to set the list ID of the object. SETSURVEYLISTID() This method sets the survey list ID. If the list ID is provided as a parameter, it is set as the object’s list ID; otherwise, the current list ID is returned. SETRETURNVALUE() This is a utility method that returns TRUE if the DBI returned result is set to DB_OK, which notifies that the SQL operation was successful; other- wise, it returns FALSE. ADDNEWSURVEYLIST() This method creates a list using user uploaded CSV data. The method does the following: ◆ Creates a unique check flag called $checkflag using the user’s ID ($uid) and current time stamp ($today) supplied from the calling application. ◆ It then inserts a new row in the survey list (SURVEY_LIST) table and gets the newly created list id (LIST_ID), which is needed to insert the list data in the list data table (SURVEY_LIST_DATA). ◆ For each line in the user uploaded file, it creates a record set consisting of $email (EMAIL), $fname (FIRST), and $lname (LAST) fields. ◆ If the filter options are enabled for filtering the name fields (FIRST, LAST) and/or the e-mail field (EMAIL), the method applies fields. Currently, the name fields are filtered such that each word in a name is first lower- cased and then only the first character is uppercased. The e-mail field is lowercased. Chapter 14: E-mail Survey System 481 18 549669 ch14.qxd 4/4/03 9:26 AM Page 481 ◆ The filtered (or not filtered) data is then inserted into the list data table (SURVEY_LIST_DATA). ◆ When all data is inserted, the RECORDS field in the list table (SURVEY_LIST) is updated to reflect the data inserted in the list table. GETTOTALRECORDCOUNT() This method returns the total record count for a given list. In other words, it returns the number of survey recipients in a list. Since the EMAIL address is unique in the list table per list, each list can only contain a single instance of an e-mail address. This ensures that a survey is not sent to the same user twice from the same execution of the survey. GETAVAILABLELISTS() This method returns a list of available survey lists in the database. The returned list is an array, which is indexed with LIST_ID, and the value of each element is the corresponding name of the list. DELETELIST() This method removes a list from the database. GETTARGETDATA() This method returns a list of records from the survey list data table ( SURVEY_LIST_DATA) using LIST_ID. It limits the returned list of records using SUID and delivery chunk size stored in the survey.conf file. In other words, this method returns a list of records as an associative array, which has SUID as key and row object per record as value. The returned record set is limited by the SUID and specified record size ($deliverySize). For example, to get a list of 100 records that have SUID greater than 5,000 from the SURVEY_LIST_DATA, you can call this method as follows: $surveyListObject->getTargetData(5000, 100); Designing and implementing the SurveyForm Class This class provides the survey Form object. The survey form object is used to manipulate survey form data. Applications can add or remove survey forms using the survey Form object. The methods provided by the class are discussed below. The ch14/apps/class/class.SurveyForm.php file in the CDROM is an implementa- tion of this class SURVEYFORM() This is the constructor method, which creates the survey form object. This method sets member variables survey_form_tbl to $SURVEY_FORM, survey_form_field_tbl to $SURVEY_FORM_FIELD_LBL_TBL, dbi to $dbi and fid to $fid. 482 Part III: Developing E-mail Solutions 18 549669 ch14.qxd 4/4/03 9:26 AM Page 482 SETSURVEYFORMID() This method sets the survey form ID. SETRETURNVALUE() This is an utility method that returns NULL if the passed para- meter is null else returns the value passed to it. ADDNEWSURVEYFORM() This method adds a new survey form in the database. It inserts the survey form information in the SURVEY_FORM after making sure text data is properly quoted. Then it returns the new form’s FORM_ID from the database. GETAVAILABLEFORMS() This method returns a list of all available forms in the SURVEY_FORM in an associative array, which has FORM_ID as the index and form name (NAME) as the value. DELETEFORM() This method deletes a form with the given FORM_ID from the SURVEY_FORM. ADDLABEL() This method inserts a field label for a given form field in a given form. GETTEMPLATE() This method returns the form template ( TEMPALTE) from the SURVEY_FORM for a form with the given FORM_ID field. GETFORMINFO() This method returns the NAME, TEMPLATE, MAILFROM, SUBJECT, CREATE_TS, and CREATOR_ID fields of a form with given FORM_ID. If the given form is not found in the SURVEY_FORM, the method returns FALSE. Designing and implementing the SurveyResponse Class This class provides the survey form Response object, which is used to manipulate the survey response. An application can use the survey Response object to add a new response or check whether a user has already submitted a survey or not. The methods in this class are discussed in the following sections. The ch14/apps/ class/class.SurveyResponse.php file in the CDROM is an implementation of this class. SURVEYRESPONSE() This is the construtor method used to create the SurveyResponse object. It initializes member variables: dbi to $dbi, survey_id to $sid, form_id to $fid, response_tbl to $SURVEY_RESPONSE_TBL and response_rec_tbl to $SURVEY_RESPONSE_RECORD_TBL. ISSUBMITTED() This method returns TRUE if a given user has already submitted her response for a given survey. It performs a SELECT query for the given run of the survey ($EXEC_ID) using the user’s ID ($SUID) in the SURVEY_RESPONSE_RECORD. If a row is found in the user’s table, she has already responded, and the query returns TRUE, otherwise it returns FALSE. Chapter 14: E-mail Survey System 483 18 549669 ch14.qxd 4/4/03 9:26 AM Page 483 ADDSUBMITRECORD() This method adds a submission record in the SURVEY_ RESPONSE_RECORD table for a given run ($EXEC_ID) of a survey for a given user ID ($SUID). The method returns TRUE if the submission record is added successfully else it returns FALSE. ADD() This method adds survey response data for a given survey run ( $EXEC_ID) for a given user ($SUID). Designing and implementing the SurveyReport Class This class provides the survey Report object. Using the survey Report object, an application can perform queries on survey response data stored in the database. The following methods are needed to implement the class, which can be found in the ch14/apps/class/class.SurveyReport.php file in the CDROM. SURVEYREPORT() This is the constructor method that is used to create the SurveyReport object. It initializes member variables: dbi to $dbi, execid to execid, response_tbl to $SURVEY_RESPONSE_TBL, execution_tbl to $SURVEY_ EXECUTION_TBL , survey_tbl to $SURVEY_TBL, survey_response_rec_tbl to $SURVEY_RESPONSE_RECORD_TBL, form_field_tbl to $SURVEY_FORM_FIELD_ LBL_TBL SETSURVEYEXECID() This method sets the survey execution (i.e. run) ID. GETSURVEYRESPONSE() This method returns the responses for a given survey execution in an array. GETRESPONSEDATERANGE() This method returns the start and the last date of recorded response for a given survey execution. GETTOTALRESPONSECOUNT() This method returns the total responses for a given survey run. GETLABELSBYFIELDANDEXECID() This method returns the field label for a given field ID of a survey. Designing and Implementing the Survey Applications According to the system diagram shown in Figure 14-2, the survey system consists of six applications, which are discussed in the following sections. 484 Part III: Developing E-mail Solutions 18 549669 ch14.qxd 4/4/03 9:26 AM Page 484 Developing Survey Manager This application is responsible for displaying the administrative menu to manage the survey application suite. It allows the survey administrator user to add and delete surveys. The ch14/apps/survey_mngr.php file in the CDROM is an imple- mentation of a survey manager. As usual, this application extends the PHPApplication class to create the surveyMngr class, which has the following four methods. run() This method overrides the run() method provided by the PHPApplication class as required by the application framework. It performs the following tasks: ◆ Uses the check_session() method to see if the user has an authenticated session. If not, the user is redirected to the authentication application. ◆ If the user is authenticated, it then checks to see if the user has authoriza- tion to access this application. This check is done using the authorize() method, which is also overridden in this application to replace the empty (abstract) one provided by the PHPApplication class. ◆ A global variable called $cmd is used to control how business logic is cho- sen in this application. This variable is set automatically by PHP when cmd=command is passed from the interface. The acceptable command values are create or delete. ◆ When both authentication and authorization checks pass the global vari- able, $cmd is used to implement a select business logic selection driver. If the $cmd is set to create, the createSurveyDriver() method is called to handle the survey creation process. If the $cmd variable is set to delete, the delSurvey() method is called to handle the survey deletion process. Otherwise, the displayMenu() method is called to load the survey man- agement menu. createSurveyDriver() When the global variable $cmd is set to create from the GUI, the application runs this method. This method uses another global variable called $step to determine the appropriate step for the survey creation process. When a user first enters the survey creation process, the $step is not set in the GUI and, therefore, the method runs the displayMenu() method with the appropri- ate interface template ($SURVEY_ADD_TEMPLATE). The displayMenu() method loads the survey add interface. This interface has a hidden field called step, which is set to 2 to indicate that the next time createSurveyDriver() is called it should call the saveSurvey() method. Chapter 14: E-mail Survey System 485 18 549669 ch14.qxd 4/4/03 9:26 AM Page 485 . and delete surveys. The ch14/apps/survey_mngr .php file in the CDROM is an imple- mentation of a survey manager. As usual, this application extends the PHPApplication class to create the surveyMngr. provided by the PHPApplication class. ◆ A global variable called $cmd is used to control how business logic is cho- sen in this application. This variable is set automatically by PHP when cmd=command. object. The methods provided by the class are discussed below. The ch14/apps/class/class.SurveyForm .php file in the CDROM is an implementa- tion of this class SURVEYFORM() This is the constructor