Mail-Merge - The Easy Way!

So, you would like to be able to publish the contents of your Freepages Guestbook and/or Visitor's comments directly to a webpage of your choice. Well this can easily be done, and with the approach I am about to describe the output to the webpage will be capable of being styled to match the theme of your page, and contained in a scrollable container with the last message posted displaying first.

To start with you will need a suitable form for your visitors to enter their comments, but before getting to it, some consideration to security and hence access to the form needs to be given. In todays rather anti-social climate on the internet, much of the spam getting into forms is by automated means, whereby nasty little robots seek out ways of adding unsavoury website urls into open forms, and/or leaving sleazy type messages.

The first line of defence is in controlling access to the form, and the easiest means of thwarting the spammers is to make getting to the form subject to the use of "human intelligence". This means that when you click on the link below to the demonstration form, you will be confronted with transcribing a 'password' embedded as a graphics image on the page. Once entered correctly, the page will be re-written to reveal the form.

This is a case of where you must have Javascript enabled, else you will never get to the form. "But surely the source code for the form must be there somewhere", the doubters will say! Of course it is, though it is embedded in a completely unrecognisable form encrypted by a Blowfish algorithm which will only be decoded when the correct password is used. That password cannot be found within the source code, and hence "human intelligence" is required to get to the form.

In the interests of getting Mail-Merge working for you simply and quickly, the initial form you set up will not be protected. Instructions on how to go about protecting the form will be given separately.

When you get to the following link, it will open to display a password page. This is to protect entry to the form as described earlier. Now lets go to the demonstration form which is similar to the one you are going to use while getting this system up and running. It is live, so try entering some text into it and click "Submit Entry". The Mail-Merge Gateway page will open to show you a simple summary of the entry you just made. Use your Back Button to return to this page. Needless to say, you'll be able to change the form to suit your requirements later.

Here is a demonstration display page in which the last entry visible is the one you have just made. You will note that the 'My Display Page' is a template page using Cascading Style Sheets (CSS) designed by Patricia Geary, and clicking on any of the Navigation links in it will lead you to further pages also designed by her.

Now lets get on with making Mail-Merge work for you!

The contents of the form, that is the fields which have been allocated a 'name', are sorted by the Mail-Merge CGI script, located on the Freepages server, with reference to a template and then automatically written to a text file. This text file is then downloaded to your display page using Server Side Includes (SSI). It may all sound rather complicated, but if you follow the next three steps, you will have the complete system up and running within 15 minutes.

Lets begin!

(1).. Clicking on this link will download a Zip file containing all the files required to get you set-up. Elect to 'Save' and navigate to a Folder of your choice (or create one) and save the Zip file. When prompted, click 'Open Folder' and click on mymail_401t.zip. You may be prompted to 'Extract' the zipped files at this point, or you may see a new Folder with the same name appear. Click on that Folder and it will open to reveal the now unzipped files you will be using.

They are - mydisplay1.css, mydisplay.html, myform.html, myoutput.txt and mytemplate.tpl. Only two of these files need your attention, and they are - myform.html and mytemplate.tpl.

(2).. Lets deal with myform.html first. Right-Click on the filename and select 'Open with' Notepad (or your prefered plain text editor). Once opened, scroll down until you find:-


The line refered to, immediately below the one indicated above, needs the red text as shown below changed to match your account name:-

<form action="/cgi-bin/Mail-Merge.cgi/~myaccount/mytemplate.tpl" method="post">

(0).. Once done, 'Save' the file.

(3).. It is now time to make changes to mytemplate.tpl. NOTE: The .tpl extension to this file in place of the more common .tmp which could accidentally be deleted when temporary files (.tmp) are cleared from your computer. As before, Right-Click on the filename and select 'Open with' Notepad or your Editor. The only changes to be made are to those red parts of the line commencing - ACTION=File: - and shown below.

ACTION=File: /u1/m/y/a/c/myaccount/computers_html/myoutput.txt

(0).. Start by replacing m/y/a/c/ with the first 4 characters of your account name inserted between the slashes and then substitute 'myaccount' with your whole account name. NOTE: The tilde ~ is NOT used here. Now change 'computers_html' to match the community you are using on Freepages e.g. genealogy_html. Finally, check that you have not changed anything else and 'Save' the file.

You are now ready to test your handiwork by uploading the following files to your Freepages website - mydisplay1.css, mydisplay.html, myform.html, myoutput.txt and mytemplate.tpl. Once again keep everything in the same folder and to ensure it will run correctly the first time, load all the files to the root directory of your chosen Freepages community.

Before you try anything out, you MUST give the myoutput.txt file Read/Write permissions. Whether you used Freepages Fileman or a FTP client to upload the files, you will now need to go to http://freepages.rootsweb.com/fileman, enter your account name and password, select the correct community and when in your root directory check the 'radio button' adjacent to myoutput.txt. Moving down to the right you will find the File Controls; click on "Use with Mail-Merge". This action sets the CHMOD to 666 and gives global Read/Write permissions to the file. NOTE: This cannot be done using your FTP client, but you will be able to check the results by refreshing the file on the FTP server side and clicking on properties. Depending on your FTP client, you may also see rw-rw-rw alongside the file.

Here comes the 'smoke test'. If you are not already 'online', go 'online' and start by entering the correct url to myform.html, then call the page. Once you have the page, enter text into those fields you want to and click "Submit Entry". You should now be greeted by a Mail-Merge Gateway page which will display a summary of the information you entered in the form.

If you have got this far successfully, the remainder is bound to work! Now enter the url for mydisplay.html and call the page. Everything being equal, the contents of myform.html will now be displayed in a <div> of mydisplay.html. Even though the display area of the page seems small, additional messages will cause the vertical scrollbar to come into play, while the latest message to be entered will be the first one you see, provided you append the suffix #end to the url, e.g. mydisplay.html#end. Scroll 'up' for older messages.

Having successfully got your form and display page working, some advice on how to change myform.html and mytemplate.tpl to suit your needs may be in order, as well as details on how to protect entry to the form. Further information can be found in the Mail-Merge Add-ons page.

Credits
http://stein.cshl.org/WWW/software/mailmerge/ - for full documentation on Mail-Merge.
http://www.genealogy-web-creations.com/ - Patricia Geary - who suggested creating this page, and whose CSS Template I've used for the display page.