Using Surveymail in NTU 
 
  • What is SurveyMail?

SurveyMail is a program that helps you store responses to an online survey into a plain-text data file. It is an extension of Formmail.pl, a general purpose submission form. (Refer to Using Submission Form in NTU for details on Formmail.)

SurveyMail is a Perl program that has been adapted from BFormMail.pl. The latter was written for Unix platform, but SurveyMail.pl was modified and enhanced for NTU's NT Web server.

Like the normal Formmail.pl program, you will get an email detailing what the user has filled in, whenever a user fills in your survey form. But this time the responses will automatically be added into a text file in your personal Web account space, or anywhere in NTU's Web server where you have permission to write to. You can use the data in the text file in any software you like, e.g. Excel for tabulating and reporting purposes. (We do not teach you how to do it as it varies with the software you are using but usually the step involves importing a delimited text file.)

Should you anticipate many responses, you have the option to turn off the emailing routine. (Otherwise your mailbox will be flooded with many entries.) Data will simply be appended into the text file as usual. If you suspect the program is not responding well at a later time, you can turn on the email feedback again.

In the text file, fields are delimited with any character you like, and blank fields will be delimited by your self-specified delimiter in front and behind the empty field, leaving no space in between. A date and time stamp all automatically be placed as the first two fields in a record.

If you have the email feedback turned on, you have the option to tabulate a subset of the input fields into the text file. That is, the email will show all the fields the user has keyed in, but the text-based data file will not keep track of all the fields. You have the option to tabulate only the fields you want.

The text file is treated like a database. This file can be placed anywhere you want, even in a sub-directory in your personal Web account. With a one-time access to an NT machine, you can modify the Read/Write privileges of the file yourself, without help from Centre for IT Services. (Without modifying the file access privileges, the server-based SurveyMail program cannot write to your database file.) The advantage of being able to do it yourself is that you can give a meaningful name to your database, and you can place it in a location that is meaning to you. You can also have a few surveys going on at the same time since the each survey form can write to a different database file. But should you need help with the setting of file access privileges, we can help you with that as well.

 
  • Purpose of this guide

This guide is meant for those who know how to create a form on a Web page. It is not meant to be a step-by-step guide on how to create an online form. That is too technical as forms are one of the more complex features of HTML.

However, if you have a good programming background, or are game enough to read till the end and dissect the source codes of a working form, you are welcomed to continue reading this guide.

As this SurveyMail.pl program is based on Formmail.pl, the submission form, you should refer to the write-up on Formmail (Using Submission Form in NTU) if you are totally new to creating Web-based forms.

It is also assumed that you know what to do with a text-based flat file database. We will not help you with importing the file into your analysis programs.

 
  • Codes for a form
These are the codes extracted from the Barebones Guide on Forms.

FORMS
Define Form <FORM ACTION="URL" METHOD=GET|POST> </FORM>  
File Upload <FORM ENCTYPE="multipart/form-data"> </FORM>  
Input Field <INPUT TYPE="TEXT | PASSWORD | CHECKBOX | RADIO |  IMAGE | HIDDEN | SUBMIT | RESET">  
Field Name <INPUT NAME="***">  
Field Value <INPUT VALUE="***">  
Checked? <INPUT CHECKED> (checkboxes and radio boxes)
Field Size <INPUT SIZE=?> (in characters)
Max Length <INPUT MAXLENGTH=?> (in characters)
Selection List <SELECT></SELECT>  
Name of List <SELECT NAME="***"></SELECT>  
# of Options <SELECT SIZE=?></SELECT>  
Multiple Choice <SELECT MULTIPLE> (can select more than one)
Option <OPTION> (items that can be selected)
Default Option <OPTION SELECTED>  
Input Box Size <TEXTAREA ROWS=? COLS=?></TEXTAREA>  
Name of Box <TEXTAREA NAME="***"></TEXTAREA>  
Wrap Text <TEXTAREA WRAP=OFF|VIRTUAL|PHYSICAL> </TEXTAREA>  

 

  • How to use SurveyMail.pl

The coding

The codes that are needed to call this program are some text in the Form action field. Use this POST statement below:

<FORM METHOD="Post" ACTION="http://www3.ntu.edu.sg/cgi-bin/surveymail.pl">

There are also eight main hidden fields of interest to this program. The first three are similar to those usually used in the normal email sorter program, Formmail.pl The latter fields are required for the database appending routine to work. These are:

recipient email address that will receive the results. It has to be a NTU email address ending with @ntu.edu.sg
subject email message subject header
redirect URL of the 'thank you' page which you have created. This is optional. If you do not use a redirect field, the results of what the user keys in will be displayed on screen once he submits the form. The 'thank you' file is just another ordinary HTML file that you have to create yourself.
mailback option to turn on (value = 1) or off (value = 0) the email response that you will receive for every completed survey submission
drive drive letter on the server that matches the location of your Web account
append_db the path name of the directory and filename of the database file
db_delimiter character you wish to use to separate the individual fields. Use a character that will NOT appear in any field.
db_fields specifies exactly which fields are appended to the database. Any field not specified in db_fields will not be appended to the database. The order of the fields in the database file will be the same order you give for your string in the db_fields variable.


All the field names listed above must be in lowercase.

 

Examples of how you can use the eight fields above:

<INPUT TYPE="hidden" NAME="recipient" VALUE="your_name@ntu.edu.sg">
<INPUT TYPE="hidden" NAME="subject" VALUE="XYZ Survey Replies">
<INPUT TYPE="hidden" NAME="redirect" VALUE=http://www3.ntu.edu.sg/directory_name/thankyou.html>

<INPUT TYPE="hidden" NAME="mailback" VALUE="0">

<INPUT TYPE="hidden" NAME="drive" VALUE="1">
<INPUT TYPE="hidden" NAME="append_db" VALUE="your_name\directory_name\database_filename.txt">
<INPUT TYPE="hidden" NAME="db_delimiter" VALUE="*">
<INPUT TYPE="hidden" NAME="db_fields" VALUE="field1,field2,field3,field4,field5,field6">

Place the eight statements anywhere after the POST statement, and before the SUBMIT button statement.

  • Substitute values for the recipient field above with your preferred email address. For NTU Exchange addresses, the full address with the @ntu.edu.sg bit is needed. Only NTU addresses will be accepted by the program.
  • Substitute the value for subject with any subject header you like.
  • The redirect field is optional. If you want to have it, you have to prepare a thank-you HTML file first.
  • mailback field is compulsory. "0" for no email feedback, "1" for email.
  • The value for drive must match the location where your survey form's data file resides. See section below for details.
  • In the field append_db, you have to give your Web account name followed by a "\" and the directory where your data file resides. E.g. if your account name is attan, and the data file is in the root directory and it has a name of data.txt, the syntax would be: <INPUT TYPE="hidden" NAME="append_db" VALUE="attan\data.txt">
  • Ensure that whatever character you give for the db_delimiter it must be appear in your data. E.g. "#" would not be appropriate if you have user addresses with a unit number of say #03-1234.
  • Only fields listed in the db_fields variable will be appended to the database. So remember to check your codes.

As for the rest of the form, you can use any of the valid field type you want. There is no limit to the length of field name or any particular way the name of the field ought to be named. SurveyMail will just take anything in the NAME field wholesale. However, do note that the field names are case-sensitive, i.e. Course is treated as a different field from course. See the sample form given in the next section for illustration.

There are also many other fields with special functions that you can use in your submission form. Read this SurveyMail Advanced for the details.

 

Matching the drive number
The value for the drive field will depend on where your Web account resides. This may change with every new academic year when new students come in and the seniors graduate. Please check this section again every new academic year for a possible change in drive assignment. The drive field assignment for staff's pages and those of official nature should be static, unless there is a server disk upgrade. NOTE: This SurveyMail program will only work if your database file resides in the NTU Web server.

xxx refers to the Web account name of your Web space.

Location of your database file
Drive
  
http://www.ntu.edu.sg/xxx
 0
 Official websites of Schools/Departments
http://www.ntu.edu.sg/home/xxx
 1
 Personal websites of staff
http://www.ntu.edu.sg/studorgn/xxx
 2
 Websites of student organisations residing in WEB
http://www.ntu.edu.sg/home1/xxx
 3
 Personal websites of students
http://www.ntu.edu.sg/home2/xxx
 4
  as above
http://www.ntu.edu.sg/home3/xxx
 5
  as above
http://www.ntu.edu.sg/home4/xxx
 6
  as above
http://www.ntu.edu.sg/home5/xxx
 7
  as above
http://www.ntu.edu.sg/home98/xxx
 8
  as above
http://www.ntu.edu.sg/xxx
 9
 Official website of Library or CITS
http://www.ntu.edu.sg/home99/xxx
 10
 Personal websites of students
http://www.ntu.edu.sg/home2000/xxx
 11
 as above
http://www.ntu.edu.sg/home2001/xxx
 12
 as above
http://www.ntu.edu.sg/home2002/xxx
 13
 as above
http://www.ntu.edu.sg/home2003/xxx
 14
 as above
http://www.ntu.edu.sg/home2004/xxx
 15
 as above
http://www.ntu.edu.sg/home2005/xxx
 16
 as above
http://clubs.ntu.edu.sg/xxx

 17

 Websites of student organisations residing in WebX
http://www.ntu.edu.sg/home2006/xxx

 18

 Personal websites of students
http://www.ntu.edu.sg/home2007/xxx

 19

 as above
http://www.ntu.edu.sg/home2008/xxx

 20

 as above
http://www.ntu.edu.sg/home2009/xxx       21 as above

Substitute the corresponding drive value depending on where your database file resides. You can only use the Web space of accounts where you have access rights for editing.

 

The database file
You have to create an empty text file for the program to append records to. Decide where you want to place the database file. If you want it to be in a sub-directory in your Web account, you have to create a folder in the Web account first. Then you can use a text editor like Notepad to create an empty file. You can give it any name you want, but a good guide is not to give a name with spaces in between or unusual characters. The Web browser may not be able to handle such unconventional names probably. (Though it may work during your testing, bear in mind that some of your survey respondents may not be using a Windows machine.) To facilitate reading of the database file, since it is a plain text file, it is advisable to give it a file extension of .txt [Video: How to create an empty text file. Size: 309KB]

Note: The date and time will be stamped at the start of the record (line) for every new entry. The format is as such: DD/MM/YYY#HH:MM:SS# assuming "#" is your delimiter.

The next crucial step in the preparation of this database file is to open it for writing by the Web server. To do this, you have to use any Win 2000 machine on campus that is on the NTUnet network.

  1. Go to the machine (there are some in the Centre for IT Services' Terminal Room at the South Spine, or in the labs) and log in using your Web account name and password (the same way you log in to the network when you want to edit your files).
  2. Use the Windows Explorer to map a drive to the Web account if it is not mapped already. [Video: How to map a drive for Win 2000. Size: 854 KB.] Normally personal Websites are automatically mapped to drive H when you log in.
  3. Navigate till you see your Web account. [Video: Finding your Web account directory in Win 2000. Size: 1,047 KB]
  4. If you have created a sub-directory for your database file, go to the folder. Right click on the folder, and select Properties located at the bottom of the pop-up list. Click on the second tab called Security. You should see a list of users who can access your folder. Keep the default settings. Double check that the IUSR_IISSEC user has these privileges: Read & Execute, List Folder Contents, and Read. Then click OK to get out of the window. [Video: How to set sub-directory permissions in Win 2000. Need to view this in 800x600 or higher resolution. Size: 559 KB]
  5. Then from the Windows Explorer window, select the database file. Proceed to change the permission rights as in step 4. This time for the IUSER_IISEC user, click on Modify (and related permissions like Read & Execute, Read, and Write will also be checked).[Video: How to set file permissions. Need to view this in 800x600 or higher resolution. Size: 478 KB]

If you still have problems changing the permission settings, you can send an email to webadmin giving us all the necessary information like your Web address (URL), the database filename and directory where it resides, etc. and we will try to do it for you. Make sure that you have already created the empty database file. However, it is better if you can do it yourself as you can have more flexibility in your testings, and there will be less turnaround time.

 

  • Example of a simple form

A form is a pretty technical piece of work, as you will need to understand what is a textbox, drop-down list, etc. Some examples are shown below.

 

But here is an example of a working survey form for you to look at its codes. However you will have to change the email address for the recipient field to a valid one. You may be able to decipher the syntax and modify it for your own use. Just substitute the REDIRECT field, the RECIPIENT field, the SUBJECT field, etc. for your own.

Sample form - view the source codes and print it out for your own reference. Pay particular attention to how the POST statement, special fields, and SUBMIT and RESET buttons are coded.

  • Why is it that no records are added in the database file?

If during your testing, no records are added into the database fields, check that these things are in order:

  1. Did you specify the drive field? This field is compulsory. And is it correct for your Web account? (refer to table above).
  2. Does the filename you typed in the survey form match the name of the empty database file in your Web account?
  3. If your database file is placed in a sub-directory, check that the permission rights for the sub-directory is set to Internet Guest Account Read, and the IUSR_IISEC user has Read & Execute, List Folder Contents, and Read permissions.
  4. Check that the permission rights for the database file is set to Read Write for the Internet Guest Account user, and IUSR_IISSEC user permission is set to Modify, Read & Execute, Read, Write.
 
  • Do we accept personalised forms on our server?

Some people find the formmail.pl and the surveymail.pl programs to be too generalised and would like to tailor it for their own use, or they may like to put in their own programs on the server. But the Centre for IT Services will not accept any other scripts on our Web server.

The reasons are:

  • Security: We do not have the manpower or sometimes the know-how to check that all alien programs are safe on our system. We are accountable to all NTU users when the server fails.
  • Maintenance: It is difficult to keep track of who's program it is that is on the server. People will ask to put something up, but they may not tell us when they no longer need the program. We have thousands of users using our server, so even if only one percent of the users have a special program on the server, the tracking work will already be quite substantial.

Alternatives:

  • Set up your own server if you know how and have the equipment to do so. Some schools have their own servers.
  • You are free to call any other free services from other websites on your web page. E.g. some people use counter programs from overseas servers, or other free guestbook services.
Printer-friendly | Send to a friend