FirstProductions Human Test
FormMail Example

Script Does Not Output Form Tutorial

Use this tutorial if your CGI script does not output the form and the form is a separate HTML file (if the script does output the form, please use our Script Outputs Form Tutorial instead). Before continuing be sure to download the formmail.zip file, which contains the example scripts used in this tutorial. This tutorial will use formmail3.cgi (original script) and formmail4.cgi (modified script to use Human Test), as well as formmail3.html and formmail4.shtml, the HTML files.

Examining the Script

First take a look at formmail3.cgi. This is the original FormMail script that we want to integrate the Human Test library into. Please note that this script was created especially for this tutorial, and is not intended to be used in an actual setting. It may contain security holes that we are not aware of.

We also have an example of the original script and the script modified to use Human Test running on our server as a demonstration. These have been modified so they do not actually send mail.

The script first has a configuration section. Configure the script to work with your server.

Next, the script does three things to submit the form.

	&get_fields;
	&send_mail;
	&output_sent;

First, it gets the input fields, then it sends the mail, then it outputs a page that says the mail has been sent.

Adding Human Test Library to the Script

To add the Human Test library to the script, first be sure that the library is configured and working on your server by using the test script included with the Human Test library. Next you need to tell the script that you want to use the Human Test library by inserting this line towards the beginning of the script (we placed it just after the use CGI; statement.

	require "captcha.pl";

This should point to the Human Test library installed on your server. If it is not in the same directory as the script, use the full or relative server path to the library.

Adding Human Test Library to Form Output

Our example script does not output the form. The form is located in an external HTML file named formmail3.html. Rename this file with a .shtml extension, as we will be adding SSI to display the image.

Add these two lines of code to the form just before the line that contains the Submit button.

	<p>Security code: <!--#include virtual="/cgi-bin/human/formmail4.cgi?ssi=1" -->
	<br>Please enter the characters you see in the image: <input type="text" name="code" value=""></p>

The first line of code contains an SSI command to call the FormMail script and pass the variable ssi=1. This will let the FormMail script know that we want to output the image.

The second line contains an input box to enter the code.

Now add the following code to the script just before it calls the three subroutines to process the form (get_fields, send_mail, and output_sent).

	$ssi = $q->param('ssi');
	
	if ($ssi == 1){
		$crypt = &generateCode(8);
		
		print "Content-type: text/html\n\n";
		print "<input type=\"hidden\" name=\"crypt\" value=\"$crypt\">\n";
		print "<img src=\"$captcha_webfolder/$crypt.png\" width=".($captcha_length*$captcha_width)." height=$captcha_height border=0>\n";
		exit;
	}

First the script checks to see if ssi=1. If so, then it needs to output the image instead of processing the form. The script uses the generateCode function of the Human Test library to generates a code that is eight characters in length. An encrypted version of the code is returned into the $crypt variable.

Next the script outputs the crypt, an encrypted version of the code, to a hidden form field needed to check the code when the form is processed.

The next line shows the security code. The image is located in the folder specified in the configuration section of the Human Test library ($captcha_webfolder), and the name of the image is the encrypted version of the code ($crypt) with the .png suffix. The width of the image is the number of characters ($captcha_length=8) multiplied by the width of each character ($captcha_width). The height of the image is the same as the height of each character ($captcha_height) as all of the characters are lined up in a row.

Finally the script calls the exit command, as we are done showing the image and do not need to continue with the rest of the script that processes the form.

Adding Human Test Library to Form Processing

Our example script processes the form in the get_fields subroutine. Find this subroutine in the script. At the end of this subroutine, after it checks the name, email, and comments, the script needs to check the code.

	$code = $q->param('code');
	$crypt = $q->param('crypt');

These two lines of code get the code variable and crypt variable from the form. $code contains the code entered by the user, and $cyrpt contains the encrypted version of the code passed to the script via the hidden form field. Now to actually check the code using the checkCode function.

	if ($code && $crypt){
		$result = &checkCode($code,$crypt);
		if ($result != 1){
			&error("Incorrect or expired security code! Please press back, refresh the page to get a new code (the code that you just tried has expired), and try again. You may want to copy your comments before refreshing the page because they will be cleared when the page refreshes. Then paste them back on the refreshed page.");
		}
	}
	else{
		&error("Security code is required! Please press back and try again.");
	}

What this code does is first checks to be sure the user entered a code. If not, the script outputs an error. Next the script runs the code and crypt through the checkCode function from the Human Test library. If the code and crypt are valid, the function returns a value of one. If the function returns zero or a negative value (different returned values are explained in the Human Test library documentation), then the code is either incorrect or expired, so the script outputs an error if the function does not return a value of one.

If no code at all is entered, then the user just needs to press back and enter the code. If an incorrect or expired code is entered, however, then the user also need to refresh the page to get a new code. This is becasuse the code expires after it is checked. If no code is entered, then it is not checked, and thus it does not expire.

Conclusion

The Human Test library is now fully integrated into the example FormMail script. The final script is included in the zip file named formmail4.cgi, and the HTML form is named formmail4.shtml. Please review the steps needed to integrate the Human Test library into an existing script that does not output the form. Then use this knowledge to integrate Human Test library into your own scripts. If you have any questions or need additional assistance, please use our Support Forums.