Introduction
A form is way of allowing your website users to respond to the site by email. The form may be designed to simply provide a means of commenting on the site, through to complex order and information requests. The Freeway Reference manual and the Softpress KnowledgeBase (at http://www.softpress.com/kb/) provide excellent coverage of the whole subject along with how to use the different types of form item in Freeway.
By far the quickest and simplest method of creating a form in Freeway is to use the Send Form Action (see http:// www.softpress.com/kb/questions/416/Send+Form+Action) but it is also possible to manually build the script for your form if you prefer (or perhaps if you have some specific functionality that is not supported by the Action).
This tutorial is about the “nuts and bolts” of setting up a form for your web site. There are lots of neat tricks in Freeway to make your form look really good but that is a design issue; we are just going to make a basic form that works! For this tutorial you will need the Freeway Reference and a form mail script. Click here to download a PDF of this tutorial.
This tutorial uses the free FormMail script available from http://nms-cgi.sourceforge.net/ and is a suggested replacement for the one located at Matt’s Script Archive. This tutorial follows the ‘compat’ script, which is easiest to install and configure.
Form Mail Tutorial
We advise that you study the ReadMe file that comes with the script for information about the form and how to configure it. Softpress Systems are unable to provide technical support regarding direct configuration of the script and we recommend any questions concerning this are directed to NMS.
The cgi-bin
A form mail script is a programme that enables your website to communicate with the server and send an email. The script is often written in Perl hence the .pl suffix. The script processes the content of your form fields and sends the results to a specified “recipient”. As most servers are protected from access by website users there needs to be somewhere that the script can operate without compromising the servers protection. That place is usually the cgi-bin, which is a directory (folder) in your web space. The Common Gateway Interface is what all servers use to process requests from applications like your browser. A gateway is a program, or script, that acts as mediator between servers and client.
There are four common situations
-1. Your ISP has a pre-configured script in place already for you.
2. Your ISP will allow you to put your own formmail script in your own cgi-bin.
Assuming your ISP will let you put the script “formmail. pl” on your server there is a little information that you need to acquire from them:
1. Ask them where the cgi script should go (you will have to ftp it to the cgi-bin or cgi folder at the location they give you) or easier still, they may put it there for you.
2. Ask them for the location of the sendmail programme on their server. Typically this is something like ‘/usr/sbin/ sendmail’
If your ISP says NO, then ask them what form script they will let you use and how to configure it. Depending on what script they use, this tutorial may or may not help you. In this instance, you may want to consider changing your ISP or upgrading to a more commercial service.
Editing the Script
Open the FormMail.pl script in your preferred text edit, such as TextEdit or BBEdit.
WARNING: UNNECESSARY EDITING OF THE SCRIPT MAY CAUSE THIS TO BREAK.
Navigate to the section of the script which includes: $mailprog = ‘/usr/lib/sendmail -oi -t’;
$postmaster = ‘’;
@referers = qw(dave.org.uk 209.207.222.64 localhost);
@allow_mail_to = qw([email protected] some.one.else@ your.domain localhost);
There are a few lines here you need to edit to get the fundamentals of the form working:
$mailprog = ‘/usr/lib/sendmail -oi -t’;
This the path to the sendmail program on your ISP’s server. Replace the /usr/lib/sendmail/ to be the location advised by the ISP.
$postmaster = ‘’;
Enter the envelope sender address between the ‘ ‘ to use for all emails sent by the script. This address will receive bounce messages if a confirmation email cannot be delivered (should you choose to enable this parameter in the script - consult the readme for further information). If in doubt, put your own email address here. i.e. = ‘you@ domain.com’;
@referers = qw(dave.org.uk 209.207.222.64 localhost);
Replace the dave.org.uk, the IP address and localhost to the domain name/IP of the server. For example, for a form residing on the Softpress server this may say qw(softpress. com);
@allow_mail_to = qw([email protected] some.one.else@ your.domain localhost);
Replace the email addresses in this field with the email addresses of the person(s) that will receive the results of the feedback form.
Save the formmail.pl script file. It must be saved a text file and do not change the name of the file - it should be called formmail.pl.
Setting the Permissions (chmd)
You will need to upload the script to your cgi-bin, or to the directory advised by your ISP, before you can set the permissions. We recommend using the FTP application Transmit (but below are details for using Fetch and Interarchy, which you may be using instead).
In order for viewers to submit the form, permissions (of ‘755’) need to be set on the file. Select the uploaded script then do the following, according to what FTP application you are using:
Transmit
Choose ‘Get Info’ from the File menu.
At the bottom of the dialogue the are the Permission settings. Make sure that these are set as below.
Fetch
From the ‘Remote’ menu choose ‘Set Permissions’
Interarchy
From the Listing menu choose ‘Set Upload Permissions’
If your FTP application requires the chmd to be set as a command line enter:
Creating a form in Freeway
Place the form elements that you require on your page (sample form below).
When you create the form, the ‘Name’ you specify in the Form Options tab of the Inspector Palette will be returned in the form, therefore it’s recommended that something appropriate to the field is entered here:
When the email field is completed and the form is returned the information will say something like: email = [email protected]
Form Setup
Now the basic form has been setup, some information about the form, and any hidden fields, need to be entered in the Form Setup dialogue on the Page Menu.
Hidden fields tell the form how to operate are not visible on the form page. The most important thing that you must do is to tell the form where the script is and who to send the results to.
Your ISP may send you the code for this. If so, click here. Leave Method as “Post” unless your ISP tells you
otherwise. In the Action field enter the path to your FormMail script - typically this may be:
cgi-bin/FormMail.pl
You can check this by looking at your site via ftp or ask your ISP. Or you can use the full URL of the script e.g. http://www.yourdomain.com/cgi-bin/formmail/formmail.pl
Click on the Hidden Field tab in the Form Setup and click New.
You now need to specify the email address to which the form submission should be sent. If you would like it copied to more than one recipient then you can separate multiple email addresses with commas.
For Name enter recipient
For Value enter your email address i.e. you@yourdomain. com
Your form should now work.
If your ISP sends you some form code similar to: <form method=POST action=”/cgi-bin/FormMail.pl”> <input type=hidden name=”recipient” value=”email@ domain.com”>
<input type=hidden name=”subject” value=”The email subject”>
<input type=hidden name=”redirect” value=”http:// www.domain.com/thethankspage.html”>
</form>
Copy the code and, in your form page, select Edit > Paste Special.
Additional Hidden Fields
At the moment, when the information is submitted, the email that is returned will list the results alphabetically. The form will also redirect your user to a default “Thank you” page listed in the form script or one that your ISP has set up. This may obviously be less than ideal but there are further hidden fields that can be entered in the Form Setup to give you more control over this:
Redirect
Name = redirect
Value = <URL of your thank you page i.e. http://www. domain.com/thankyou.html>
Description: If you wish to redirect the user to a different URL, rather than having them see the default response to the fill-out form, you can use this hidden variable to send them to a pre-made HTML page.
Create a new page in your Freeway site and enter the ‘Thank you’ details. Enter the URL of your Thank You page into the Value field
Subject
Name = subject
Value = <email subject line>
Description: The subject field will allow you to specify the subject that you wish to appear in the e-mail that is sent to you after this form has been filled out. If you do not have this option turned on, then the script will default to a message subject: WWW Form Submission
Required
Name = required
Value = <form item name i.e. email,name>
Description: This is a list of fields that the user must fill in before they submit the form. If they leave any of these fields blank then they will be sent back to the form to try again. Separate more than one form name with a comma
Sort
Name = sort
Value = order:name,email,phone
Description: This sets the order in which the submitted form elements will appear in the email and on the success page. You can use the value ‘alphabetic’ for alphabetic order, or the string “order:” followed by a comma separated list of the input names.
Missing_Fields_Redirect Name = missing_fields_redirect Value = <URL of your error page>
If this is set, it must be a URL, and the user will be redirected there if any of the fields listed in ‘required’ are left blank. Use this if you want finer control over the error that the user sees if they miss out a field.
Create the error page in Freeway and enter the URL of this page in the value field.
PLEASE REFER TO THE FORMMAIL README FILE FOR DETAILS OF OTHER HIDDEN FIELD OPTIONS
