We recommend ActivePerl 5.6 (available from ActiveSTATE) and will refer to this distribution in this documentation.
e-gateway requires version 5.6 (or greater) of Perl; the "LWP::Simple" (or "libwww-perl"), "Socket", "CGI.pm" and "MIME::Lite" packages are also required. Of these, only "MIME::Lite" is not installed as standard with ActivePerl 5.6. REMEMBER: Modules, libraries and packages should be in Perls' "search path" to make them globally accessible to all scripts using Perl on that server.
The installation and maintenance of Perl packages, modules and libraries is easy with the "Perl Package Manager" which is installed as standard with ActivePerl 5.6. The procedure for installing the required packages under ActivePerl 5.6 & PPM is described below. For other installations you should refer to the documentation supplied with your Perl distribution.
Note: In order to run the PPM you will need to have either physical or Telnet access to the web-server that e-gateway will be installed on. You will also need to have the required operating system permissions (in most cases, your System Administrator or ISP would be responsible for maintaining Perl).
At the shell prompt (DOS) type: ppm
At the "ppm>" prompt type: query
This will generate a list of all the installed packages on your server. Page through the list and you should find "libwww-perl" listed. If you are using ActivePerl 5.6 you won't see "CGI.pm" or "Socket" on the list, but they are installed. If you're really lucky you'll also see "MIME-Lite", in which case you need do nothing else. In all likelihood though, you'll need to install "MIME::Lite" so...
At the "ppm>" prompt type: install MIME-Lite
PPM will respond with: install package 'MIME-Lite?' (y/N)
Press "y" and PPM will respond with: Retrieving package MIME-Lite...
The PPM will then retrieve the module from an Internet repository and automatically install it. It will also display a message about where it has written the resulting file(s). Your Perl installation now consists of everything required to run e-gateway.
The e-gateway distribution consists of various files in the following sub-directories:
| cgi-local | - | This directory contains the e-gateway application ("mail_gateway.pl"), a CGI diagnostic package ("doctor.pl") and an example configuration file ("form_0001.config") |
| pages | - | This directory contains two standard HTML files that represent a web form ("feedback.htm") and a "thank you" page ("thanks.htm"), which is displayed when the form process is complete |
| templates | - | This directory contains the example templates that e-gateway will use to generate its output as it runs. "approval.template" is used to present a preview to the user before they submit their form data; "html_mail.template" is used to present HTML e-mails generated by the associated form and "ascii_mail.template" is used to present ASCII e-mails generated by the application |
| documentation | - | This directory contains all the documentation for e-gateway (in HTML format) |
We recommend that you install the e-gateway distribution "as is" in order to verify compatibility with your server hardware & software configuration BEFORE you begin to customise the application to process your own web forms.
The files included in the standard distribution constitute a complete e-gateway package for processing a basic "Customer Feedback" form. This form captures a users' name, e-mail address and their comments. A preview is presented (whereby the user can opt to submit their feedback, or return and edit), then e-mails are sent to the webmaster/website operator and to the user.
For the purposes of this documentation, we assume that you will use an FTP (File Transfer Protocol) client to copy the e-gateway files on to a remote web-server. If you have physical access to the web-server, then you can, of course, copy the files directly onto the server. We use the term "Source" to denote the files you will be copying (on media supplied by us, or on your computer or LAN) and "Destination" to denote the web-server you will be copying the e-gateway files to.
All the files that constitute an e-gateway installation (html files, templates, the ".config" file and the "mail_gateway.pl" application itself) should be uploaded as ASCII-type files when FTPing them on to your web-space. If "mail_gateway.pl" is uploaded as a binary-type file then it will not run when executed.
- Edit the first line of "mail_gateway.pl" to reflect the physical path to Perl on your server. In the majority of cases this line will already indicate the correct path, but some servers will be configured differently. Check with your ISP or System Administrator for the correct path or, if you are able to Telnet on to the server, issue a "which perl" command and the server will return the path information you require. If you are installing e-gateway on a Microsoft Windows® NT server under Microsofts' "IIS" (Internet Information Server) web-server software then you do not need to edit this line (do not remove it though). If installing under Microsoft Windows® NT with any other web-server software ("Apache" for example) then you do need to edit this line.
- From the e-gateway distribution Source, copy the contents of the "cgi-local" and "templates" directories to the CGI-enabled directory on the Destination server (often called "cgi-bin", or "cgi-local"). You should not use seperate directories for the application and templates at this stage, although you will be able to change this later if required.
- Copy the contents of the "pages" directory (Source) to the directory that contains the other HTML pages of your website on the web-server (Destination)
- Adjust the file permissions on the web-server as follows: "mail_gateway.pl" must have global read and execute permissions (it must be accessible and executable by anyone using your website). On a Unix server use "chmod 755". If activity logging is to be used, then a directory should be set-aside for e-gateways' logs. Such a directory should have global read and write permissions (it must be accessible and writeable by anyone using your website). On a Unix server use "chmod 766". All other files require global read permissions only (they must be accessible by anyone using your website, but should not be executable, or writable). On a Unix server use "chmod 644"
- Edit the configuration file ("form_0001.config") as follows: the variable "$thank_you_id" should contain the full URL (on your website) to the "thanks.htm" page; the variable "$webmaster_email" should contain your name and e-mail address (in exactly the same format as that which is illustrated); the variable "$webmaster_email_format" should be set to your preferred e-mail format; the variable "$sender" should contain a name and e-mail representing the "Sender" of the form (this is often the same as "$webmaster_email", but is available as a variable so that you can dictate a different return address); the variable "$smtp_server" should contain either the Internet address of an SMTP server that will act as a mail relay for e-mails generated by e-gateway, or the path to the Unix "sendmail" program if you wish to use sendmail (for detailed documentation on editing the configuration file read "Developing for e-gateway")
- Save the edited configuration file and upload (or copy) it onto the web-server to replace the existing copy in the CGI-enabled directory
- The form web-page ("feedback.htm") needs to be edited to point the form to the "mail_gateway.cgi" application (the path to this is could vary depending on how your website is structured). The line to be edited is clearly indicated... change the "Action" variable to point to "mail_gateway.pl". Absolute or relative paths can be used.
- Save the edited web-page and upload (or copy) it onto the web-server to replace the existing copy in the directory that contains the other HTML pages of your website on the web-server
- Test the application by accessing "feedback.htm" in your web-browser, enter some information into the form and approve it at the "Proof Read Your Message" screen
At this stage, if everything is working correctly, you should see a "Thank You" screen in your web-browser and you should have received an e-mail (or two) from e-gateway. If this is the case then the installation has been successful and you are now ready to begin deploying e-gateway on your website (read " Developing for e-gateway").
Otherwise, check again that you have followed the installation procedure exactly as described here and test again. If you still encounter problems read " Troubleshooting".
http://www.cpan.org/ (CPAN - Comprehensive Perl Archive Network)
|