Christian Web Host, Java Programming - Cheap Web Hosting Blog

Chapter 19: Web Forms Manager 691

690 Part V: Internet Applications Listing 19-2 (Continued) define(AUTO_REDIRECT_URL, http://www.yourdomain.com ); $ERRORS[ US ][ ERROR_FNAME ] = First name -missing. ; $ERRORS[ US ][ ERROR_LNAME ] = Last name -missing. ; $ERRORS[ US ][ ERROR_EMAIL ] = Email address -missing. ; $ERRORS[ US ][ ERROR_COMPANY ] = Company name -missing. ; $ERRORS[ US ][ ERROR_SUBJECT ] = Subject of your question missing. ; $ERRORS[ US ][ ERROR_DETAILS ] = Details of your question missing. ; ?> Now on Your Web browser make a request for http://yourserver/ask.php. Figure 19-3 shows one such request. Figure 19-3: A simple Web form called ask.php. This form is managed by the submit.php application developed in this chapter, but that can be noted only if you review the source code, which contains the following lines:

Chapter 19: Web Forms Manager 689 lname => 1:text:size=3-30:name:trim|lower|ucwords , company => 1:text:size=2-60:org_name:trim|lower|ucwords , email => 1:text:size=5-60:email:trim|lower , url => 0:text:size=3-60:url:trim|lower , about => 0:text:size=3-60:any_string:trim|lower|ucwords , subject => 1:text:size=3-60:any_string:trim|lower|ucwords , details => 1:text:size=0-20KB:any_string:none ); //Do we need to upload file from the form 0 - not, 1 - yes define(UPLOAD_FILE, 0); //directory name for storing file define(UPLOAD_FILE_DIR, site_forms/askform/uploadfile/ ); //form relative template directory define(FRM_TEMPLATE_DIR, site_forms/askform/templates/ ); $UPLOAD_FILE_FIELDS_ARRAY = array( attachment => 0:size=0-60KB , ); // Do we send email to person submitting the form? 1= yes 0 = no define(SEND_OUTBOUND_MAIL, 1); define(OUTBOUND_MAIL_TEMPLATE, outbound_mail.html ); define(OUTBOUND_MAIL_SUBJECT, Thank you ); define(EMAIL_FIELD, email ); // Do we send email to inbound (company hosting the form) per submission? 1= yes 0 = no define(SEND_INBOUND_MAIL, 1); define(INBOUND_MAIL_TEMPLATE, inbound_mail.html ); define(INBOUND_MAIL_TO, you@yourdomain.com,sales@yourdomain.com ); define(INBOUND_MAIL_SUBJECT, Inbound mail for new request ); // If auto redirect is not TRUE then we show a thank you template define(SHOW_THANKYOU_TEMPLATE, thanks.html ); // Should we automatically redirect once form is submitted define(AUTO_REDIRECT, FALSE); Continued

688 Part V: Internet Applications . Upon successful completion of a Web form, if you want to automatically redirect users to an URL other than the one from which they came, you can set AUTO_REDIRECT to 1 and specify a value for AUTO_REDIRECT_URL. Note that if your Web form is a PHP script, you can redirect users to the URL from which they clicked the Web form by incorporating the following lines in the Web form: > . Finally, define the error messages that you want to show when a required field is missing. This is done using the following lines in askform.conf: $ERRORS[ US ][ ERROR_FNAME ] = First name -missing. ; $ERRORS[ US ][ ERROR_LNAME ] = Last name -missing. ; $ERRORS[ US ][ ERROR_EMAIL ] = Email address -missing. ; $ERRORS[ US ][ ERROR_COMPANY ] = Company name -missing. ; $ERRORS[ US ][ ERROR_SUBJECT ] = Subject of your question missing. ; $ERRORS[ US ][ ERROR_DETAILS ] = Details of your question missing. ; Here, when the fname field is required but missing, the $ERRORS[ERROR_ FNAME] value is displayed using a JavaScript alert window. You can customize these messages as you see fit. Now you are ready to test the ask.php form. Listing 19-2: askform.conf 1:text:size=3-30:name:trim|lower|ucwords ,

Chapter 19: Web Forms Manager 687 However, it is not required (0), and it is considered text data; it is considered to be of size 3 to 60 and validated using validate_url() method. Once validated, the field data is trimmed and lowercased before being stored in a database. As you can see, each field is defined in terms of required/not required, type (text, number, name, e-mail, and so on), size requirements, validation method, and cleanup functions. . If you have a file upload field, make sure that you create the UPLOAD_FILE_DIR directory (/webforms/apps/site_forms/askform/ uploadfile) and make it writable by the Web server user. You also have to define $UPLOAD_FILE_FIELDS_ARRAY to list the Web form fields that are file names. For example, the sample ask form configuration shows a field called attachment as the file upload field, as follows: attachment => 0:size=0-60KB , The uploaded file is not required (0) and cannot exceed size 60 kilobytes. . If you do not want to use the default templates used for the thank-you response and inbound (to whomever you wish) and outbound mail (to the submitter), you can store your own templates per form in the FRM_ TEMPLATE_DIR directory. Make sure that this directory is stored in /webforms/apps/site_forms/askform/templates for the current example. . If you want to send an e-mail message to the submitter upon submission, set SEND_OUTBOUND_MAIL to 1 as done in askform.conf. Set EMAIL_FIELD to point to the e-mail field in your Web form. The OUTBOUND_MAIL_ TEMPLATE template is used for mailing the message. You should customize this message as needed. The OUTBOUND_MAIL_SUBJECT defines the subject line used in the message. Note that if you do not supply a custom mail template, the default mail template from /webforms/apps/templates is used. . To receive an e-mail for each successful form submission, set SEND_ INBOUND_MAIL to 1 as done in askform.conf. The INBOUND_MAIL_ TEMPLATE template is used for mailing this message to you. You should customize this message as needed. The INBOUND_MAIL_SUBJECT defines the subject line used in the message. Note that if you do not supply a custom mail template, the default mail template from /webforms/apps/ templates is used. The users who can receive inbound messages are listed in INBOUND_MAIL_TO. . The thank-you template is specified using SHOW_THANKYOU_TEMPLATE. If you do not have a Web form specific thank-you template in the form s own template directory, the default template is used.

686 Part V: Internet Applications . Create a database table in your WEBFORMS database using the name given (FORM_TABLE) in askform.conf. This table should have all the fields in your Web form and the ID and SUBMIT_TS fields. The following CREATE TABLE statement is used for our sample ask.php form: # # Table structure for table `ASK_TBL` # CREATE TABLE ASK_TBL ( id bigint(20) NOT NULL auto_increment, fname varchar(30) NOT NULL default , lname varchar(30) NOT NULL default , company varchar(30) NOT NULL default , email varchar(70) NOT NULL default , url varchar(127) NOT NULL default , about tinytext NOT NULL, subject tinytext NOT NULL, details text NOT NULL, SUBMIT_TS bigint(20) NOT NULL default 0 , PRIMARY KEY (id,email) ) TYPE=MyISAM . Once you have created the appropriate database table, you are ready to submit requests. Make sure that you configure the rest of askform.conf to match your requirements. For example, to control access to your Web form via an IP address, you can use the ACL_ALLOW_FROM and ACL_DENY_FROM lists. The $FORM_FIELDS_ARRAY should be used to define the fields that you have in your Web form (exactly as they appear in your Web form), whether they are required or not; and the type of validation and clean-up operations you want to perform on them before submission is stored in the database. For example, the askform.conf shown in Listing 19-2 shows the following: fname => 1:text:size=3-30:name:trim|lower|ucwords , Here, the Web form has a field called fname. The above configuration line states that this field is required and can be of size 3 to 30 characters long. The field is to be validated using the validate_name() method. If the field is valid, the value of the field is to be cleaned up using trim, lower, and ucwords functions. This means that a valid fname field value will be trimmed for whitespaces and lowercases and, finally, each word of the value will be uppercased before storing in the WEBFORMS database. Similarly, the URL field (url) is defined using the following: url => 0:text:size=3-60:url:trim|lower ,

Chapter 19: Web Forms Manager 685 . Set file/directory permissions. Make sure that you have changed the file and directory permissions so that your intranet Web server can access all the files. Once you have performed the preceding steps, you are ready to test your Web Forms Manager applications. Testing the Web Forms Manager Once everything is installed, make a copy of one of your existing Web forms and rename it oldname.php. Here, we will rename a Web form called ask.html to ask.|php. The ask.php form can be found on the CD-ROM that accompanies this book in the ch19/webforms/example_forms directory. It is already configured for the setup discussed here. The changes in the Web form that we need to make are as follows: . Change the FORM ACTION line as shown here:
The action line should be pointing at the submit.php location. The preceding line shows the recommended location and what we used for this test. . Add the following two hidden fields > The form_id value is something you choose arbitrarily. This value must be used in webforms.conf as follows: $KNOWN_FORMS = array( X9393948482339290000 => contact.conf , X9393948482339295000 => newsletter.conf , X9393948482339292929 => askform.conf ); Here, the form_id X9393948482339292929 is associated with a configuration file called askform.conf. This configuration file must reside in the /webforms/apps/site_forms/askform directory. A sample configuration is shown in Listing 19-2. This configuration defines the form- specific database table name using FORM_TABLE.

684 Part V: Internet Applications Here is how you can get your Web Forms Manager application up and running: . Install the application framework. If you have not yet installed the application framework discussed in Chapter 4, you must do so before proceeding further. . Install the WEBFORMS database. The quickest way to create the WEBFORMS database is to run the following commands: mysqladmin u root p create WEBFORMS mysql u root p D WEBFORMS < webforms.sql . The WEBFORMS.mysql script can be found on the accompanying CD-ROM in the ch19/sql directory. The second command in the preceding listing will create two tables, X_TBL and ASK_TBL, in your WEBFORMS database. The X_TBL is not really used, as it is a generic table that explains how a form X can be configured. However, ASK_TBL can be used by the ask.php form. . Note that if you cannot create a new database called WEBFORMS, you can use an existing one. Just make sure that you change the database URL in webforms.conf to reflect your database name as discussed in the following step. . Install the WEBFORMS applications. Now, from the ch19 directory of the CD-ROM, extract ch19.tar.gz in %DocumentRoot%. This will create WEBFORMS in your document root. Configure %DocumentRoot%/webforms/ apps/webforms.conf for the path and database settings. The applications are installed in the %DocumentRoot%/webforms/apps directory, and the templates are stored in %DocumentRoot%/webforms/apps/templates. You will have to keep your form-specific files (configuration files and upload directories) in different form directories in %DocumentRoot%/webforms/ apps/site_forms. If your MySQL server is hosted on the Internet Web server, it can be accessed via localhost. However, if your MySQL database is on a different server than your Web server, you can easily modify the database URLs in each application s configuration files. For example, the webforms.conf file has a database URL as follows: define( FORM_DB_URL , mysql://root:foobar@localhost/WEBFORMS ); Suppose that your database server is called db.domain.com and the user- name and password to access the WEBFORMS database (which you will create during this installation process) are admin and db123, respectively. In such a case, you would modify the database access URLs throughout each configuration file as follows: define( FORM_DB_URL , mysql://admin:db132@db.domain.com/WEBFORMS );

Chapter 19: Web Forms Manager 683 processRequest() This method is responsible for the entire process of enabling a user to download the form data. This is how it works: . First, it determines whether the passed form ID is valid. If it is empty, it displays an alert message and returns null. . Next, an object of FormData is created. Depending on the type of download (all records or latest records), the getFormData() or getData AfterRecordID() method is called to retrieve the appropriate data and then store it in the $dataArr array. In the case of the latest data download, the getLastDLRecordID() method is called to retrieve the top record id of the previously downloaded data so that the new download can start after it. . If $dataArr is not empty, a CSV file is created and opened in the temp directory of the application, and the $dataArr values are written in it, separated by commas. . After the data writing in the CSV file is done, the updateDownloadTrack() method is called to store the record id of the row that was last written in the CSV file. . Finally, the user is redirected to the CSV file, from which he can download the data as a CSV file. . If $dataArr is empty, the user is shown an alert message stating that the requested dataset is empty. Installing the Web Forms Manager In this section, it is assumed that you are using a Linux system with MySQL and the Apache server installed. During the installation process for the Web Forms Manager, we will refer to the Web document root directory as %DocumentRoot%. It is also assumed that you have installed the PHPLIB and PEAR libraries. Normally, these are installed during PHP installation. For your convenience, these are provided in the lib/phplib.tar.gz and lib/pear.tar.gz directories on the CD-ROM. In the following sample installation steps, it is further assumed 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 that you replace these paths in the configuration files.

682 Part V: Internet Applications . It determines whether the given range for the report is valid. If not, an error message is stored in $msg, to be shown later. . If both of the preceding checks pass, an object of the FormData class is created and the getFormData() method is called to get the data submitted within that range of time from the given form. This data is stored in an array named $dataArr. . Dynamic contents of the report template are set. The form names and IDs are set to the select combo box for the forms. The starting date and ending date are set to the combo boxes accordingly. . Then the $dataArr array is checked to determine whether it has any data. If not, $msg is checked for any error messages. If there is an error message, it is set to the template to be parsed and printed to the user. Otherwise, it means that the requested range doesn t have any data for the given form. Therefore, a message is set and printed accordingly. . If $dataArr has any data in it, the headings of the data are set to the heading block of the template. Then the data block is set with the rows of data. The row colors are maintained according to the odd and even colors prescribed in the configuration file. . If the form id is selected and it is a valid and known form, the links for data download are set to the template. . Finally, the template is parsed and printed to the user s browser. Creating the CSV Data Exporter Application This application, CSVExporter.php, is responsible for allowing form administrators to download the data for a form. This application is included on the CD-ROM in the ch19/apps directory. This application has the methods described in the following sections. run() When the application is run, this method is called. It calls the processRequest() method with the form ID and the type of download (all records or latest records) to enable users to download data.