Form Mail Tutorial 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. 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. 3. Your ISP uses a different script 4. Your ISP does not allow such scripts Using Forms To Go with Freeway page 1
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(you@your.domain 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(you@your.domain 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. Using Forms To Go with Freeway page 2
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. Interarchy From the Listing menu choose Set Upload Permissions Fetch From the Remote menu choose Set Permissions If your FTP application requires the chmd to be set as a command line enter: chmd 755 FormMail.pl Using Forms To Go with Freeway page 3
Creating a form in Freeway Place the form elements that you require on your page (sample form below). When the email field is completed and the form is returned the information will say something like: email = sendersname@domain.com 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 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: 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. Using Forms To Go with Freeway page 4
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 Using Forms To Go with Freeway page 5
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 Using Forms To Go with Freeway page 6