Installation

Merchant OrderForm Web Based Shopping Cart System @ 2001
Notes on installation

Table of Contents | FAQ | Installation | Security Issues | Building Input Pages | Formatting
Configurations1 | Configurations2 | About Configurations | Troubleshooting | Customizing

These programs are protected by copyright and may not be resold or distributed. Please see the copyright notice for more information on your end user license for this program.

Please observe this Warning:

These programs are capable of collecting and sending credit card numbers via email. They are also capable of collecting other sensitive information like customers' names, addresses, phone numbers, etc. We strongly recommend that you use the security checklist found in the SecurityIssues.html document prior to operating these programs live over your web site.

We can provide professional installation if you prefer. For fees, click here.

What you need to install

1. A server capable of running independent CGI scripts
2. A plain ASCII text editor
3. An FTP (File Transfer) program to send files to/from your server
4. The absolute path (server's disk path) to your web site files
5. The SSL URLs to files on your site (if you are using SSL)

Note: Most commercial hosting companies provide the answers to 4 and 5 under their support or help sections. Look under the topic "CGI scripts." Look for things like: what are absolute paths, how to use the shared SSL. Any good hosting service should also provide this assistance over the phone, or email. They won't install CGI, or troubleshoot it, but they should easily provide you the server's paths for your site.

MOFcart v2.4 has some built in troubleshooting, so if you just can't get the "absolute path" thing, then proceed with the installation, place your cart in troubleshooting mode, and MOF will try to point the way. But, it sure is easier to know it from the start.

You'll also need a plain ASCII text editor. I use EditPad Pro. They have a FreeWare lite version, or head to the NoNags' site Freeware section. You cannot use a formal word processor to edit the Perl script files because they embed all kinds of nasty formatting, great for the office, bad for the Perl language. NoNags has FTP programs, too.

Note: Editors like FrontPage, DreamWeaver, HomeSite do not install CGI scripts. CGI scripts must be installed independently

Installation Steps

1. unZIP the package so that directories are preserved
• on windows unzip to C:\mof-install\
  
  
2. Create directories on your server
   1. for the DATA files (outside public web areas):
      
      • ../orderdata/
      • ../orderinfo/
   2. for the WEB accessible files:
      
      • ../mofcart/
      • ../invoices/
   3. for the placement of CGI scripts
      (location & name depends on server)
      
      • ../cgi-bin/mcart/
        
        
3. Adjust File settings
   • We do a search and replace on all files at once
   • Use bk replace em with preset strings
   • - OR - your own search/replace methods
   • Here's a detail list of strings to replace
     
     
4. FTP everything to your server
   • send all local ../mofcart/ files --> ../mofcart/
   • send all local ../invoices/ files --> ../invoices/
   • send all local ../cgi-bin/ files --> ../cgi-bin/mcart/
     • Adjust permissions on CGI files
     • <mof.cgi> needs 755 permissions
     • <mofpay.cgi> needs 755 permissions
     • <mofnumber.dat> needs 777 permissions
       
       
5. Go for it
   
   
   • With your browser, head to the <mofinstallation.html> page on your server
     http://www.site.com/mofcart/mofinstallation.html
     
     
   • .. and test it up real good
   • .. use the Example pages provided to test various input schemes
   • .. begin making your own store pages, templates, etc.
     
     
   • If you have any problems:
     1. place the cart in troubleshooting mode
     2. run the ?test
     3. If you cannot get the scripts to run ?test
     4. Common causes of ?test problems
        
        
6. When you are done testing and ready to go live :
   
   
   1. Turn on the mail for Merchant : Customer : help
      
      
   2. Adjust configuration settings to suite
      
      Note: MOF's behavior is controlled by two configuration files. You will find all settings for discount, insurance, tax, shipping, fields, input options, and other options in those configuration files :
      
      
      • Configurations1.html has explanations for all settings in mof.conf
      • Configurations2.html has explanations for all settings in mofpay.conf
        
        
   3. Adjust templates to suit, about templates
      
      
   4. Read the SecurityIssues.html document

UNZIP THE PACKAGE

For windows users : create a directory on your C drive called : C:\mof-install\

UnZIP the package components into the new folder. If the MOF files did not unzip into separate directories, then start over, but find the feature in your unzip program to "preserver folders," or "preserve directory structure" so that you have something like this :

• ../mof-install/
  • cgi-bin
  • docs
  • htaccess
  • invoices
  • mofcart
  • orderdata
  • orderinfo

You'll be making some changes to the files before you FTP them over to your server.

CREATE DIRECTORIES ON SERVER

You should create the directory structure on your server before you try to adjust any settings in the MOFcart files. Servers are very different, and you need to know exactly how MOFcart will be set up over on your server.

About permissions

We suggest you first see if MOFcart will run everything under the default directory permissions created by the server. If so, this is better security than 777 permissions.

1. Create the following directories in the account root on your server

• orderdata
• orderinfo

This is the file space area usually one level up from your main public web area. Some servers prohibit traveling outside the main public web area, meaning that you cannot login to your account root area. If that is your case, then you will have to place these directories in your main public web area along side the ../invoices/ and ../mofcart/ directories.

Security Warning: If these directories are placed inside the Public Web areas, then you must take precautions to prevent the data from being viewed or indexed via the web by protecting them with .htaccess. It is not sufficient to simply place "No Access" messages in those directories, because indexing bots can index them. While these files do not contain credit card information, they do contain shipping names, addresses, etc. Simply copy the .htaccess file into each of those directories and you should be safe. You do not need any passwords, you will never need web browser access to these files. Only the scripts need access to these directories.

Important Note to FrontPage users: if you use the .htaccess file in your ../orderdata/ and ../orderinfo/ directories, be extra careful to FTP the .htaccess file *only* to those directories. If you accidentally FTP the .htaccess file to other directories, you will contaminate the FrontPage extensions, losing FrontPage access to your web site.

2. Create the following directories in the main public web area on the server:

• invoices
• mofcart

Notes: The is the area of your file space that is web accessible, from any browser. Create these directories in the top level web accessible file space, the same directory level where your index.html or default.html opening main page for the site is located.

Servers are very different. Your main public web area may not be where you land when you login via FTP. Find your site's opening page. That is usually your main public web area.

If your host allows you to FTP to your account root area, then your main public web area will usually be one directory below, and may be called public_html, www, web, or even your domain.com

Some servers prohibit traveling outside the main public web area, meaning that you cannot login to your account root area. If that is your case, then your top level directory is your main public web area

3. Create the following directory in your cgi-bin

• mcart

A. Scenario one: server has designated directory to run CGI script

Most servers allow CGI scripts to run from special directories only. Check your server help pages on their specifications for where to load your CGI scripts. The special directory for CGI scripts may not be called cgi-bin. It may be called anything: cgibin, cgi-local, cgi. If your server has a designated directory for CGI scripts, then you must use that directory. Do not attempt to create your own directory called cgi-bin. Do not rename the server's designated directory, or change permissions on that directory. Create ../mcart/ as a sub directory in the designated directory. The designated directory may be in your main public web area, or it may be in your account root file space, depending on your server configurations

B. Scenario two: server has no designated directory to run CGI scripts

Some servers, like RAQs do not care where you run CGI scripts. You can simply create the ../mcart/ folder inside your main public web area, along side the ../invoices/ and ../mofcart/ directories.

 

ADJUST FILE SETTINGS

We've embedded replaceable search strings in 31 MOFcart files. The files and search strings are listed in the tables below. Adjust all the replaceable settings in these 31 files with the settings for your site.

See the "easy way" below to do a global replacement on all files at once.

You'll be adjusting settings in these files

Search and replace strings

See the "easy way" below to do a global replacement on all files at once, or use your own favorite search-replace methods : Either way, here are the exact search-replace strings.

Important: Search for these strings exactly. Make sure all replacement strings are accurate for your site settings. Pay close attention to detail:

• no quotes, semicolons, etc.
• no leading or trailing spaces
• use lower case for email and web addresses
• use lower case for Unix/Linux paths
• keep all leading or trailing / backslashes
• for NT/Win see the help section on absolute paths

 

* Notes are examples only, match to your server context

An easy way:

For Windows only, we've included a BK Replace Em v2.0 File Set with all the needed replaceable strings. You'll need to install the BK Replace Em v2.0 on your PC to use the File Set in this package.

• Download -> BK Replace Em v2.0

Once you have the BK Replace Em utility installed on your Winxx PC :

1. Important : Make sure you have all the MOF files located in C:\mof-install\ help
2. Start up the BK Replace Em File Set
   (double click on) SearchReplace.bkr located in C:\mof-install\ folder.

Replaceable strings are on the left, enter your corresponding site settings on the right. We already have it defined to adjust all 31 files at the same time. Carefully put in your settings, and select Replace > Start Replacing. Keep a backup copy of the original MOF package in case you make some errors in a global search and replace and need to start over.

If all goes well, you should get something like a log screen from BK Replace Em, showing you what files were processed and how many changes made. About 31 files will be changed, depending on version.

Tip: on the BK Replace Em File menu: select File > Save File Set to save the settings you entered. If you find you entered an incorrect setting, it's sometimes easier to simply copy in a new set of 31 files, and run your SearchReplace.bkr again.

You don't have to use BK Replace Em, you can use any Search and Replace utility to adjust the packaged settings on the files. We use a great little ASCII text editor called: EditPadPro, which has some pretty nice search and replace functions.

FTP THE FILES

Load up your FTP program, log in to your server where you created directories, and FTP all the files. We recommend you go one directory at a time.

ASCII mode only

You must upload all the script and HTML files in ASCII mode only, the image files in binary mode. Find the options on your FTP program to force ASCII transfers and upload all the script files to the ../mcart/ (CGI-BIN) directory. Some of MOF's file extensions are not recognized by your default FTP settings for ASCII mode, so an "auto" mode may not work reliably. Force ASCII mode for the CGI scripts. An "auto" mode should be fine for the ../mofcart/ directory. If you accidentally transfer the script files in binary mode they will be corrupted on the server and will not run

FTP everything to your server

• send all local ../mofcart/ files --> server ../mofcart/
• send all local ../invoices/ files --> server ../invoices/
• send all local ../cgi-bin/ files --> server ../cgi-bin/mcart/
  
  
• if you placed the DATA directories in a public web area, then
• send all local ../orderdata/ files --> server ../orderdata/
• send all local ../orderinfo/ files --> server ../orderinfo/

Adjust file permissions

You'll need to adjust file permissions on three script files. Many FTP programs have options for CHMOD or adjusting permissions. With WS-FTP right click on the file, and select chmod

These two files need 755 permissions:

• mof.cgi
• mofpay.cgi
  
  
• Owner: Read, Write, Execute
• Group: Read, Execute (only)
• Other: Read, Execute (only)

This file needs 777 permissions:

• mofnumber.dat
  
  
• Owner: Read, Write, Execute
• Group: Read, Write, Execute
• Other: Read, Write, Execute

You may need to give these directories 777 permissions. But wait first, make these directories 777 only if they do not work with default permissions

• ../orderdata/
• ../orderinfo/
• ../invoices/
  
  
• Owner: Read, Write, Execute
• Group: Read, Write, Execute
• Other: Read, Write, Execute

 

 

TEST DRIVE THE CART

With your browser, head to the <mofinstallation.html> page on your server
http://www.site.com/mofcart/mofinstallation.html

Use that page as a Quick Reference to your newly installed shopping cart. To begin testing the cart operations, use the example pages in the section:

• How do I hook up my products to the cart ?

IF YOU HAVE PROBLEMS

MOF's ERRORMODE, as you just installed it, is set to show customer friendly error messages. If you have any installation problems, configuration problems, addressing problems, etc. MOF will respond by redirecting you to the customer friendly Error Page :

--> http://www.site.com/mofcart/moferrors.html

You can place the cart in troubleshooting mode to get specific information about the kind of problem MOF encountered.

1. Open up both configuration files in your ASCII editor
   • mof.conf
   • mofpay.conf
     
     
2. Find the setting called $ERRORMODE in each (close to the top)
   around LINE 56
   
   
3. Set the $ERRORMODE = 0;
   
   
4. FTP (ASCII only) both configuration files back to your server

While MOF is in $ERRORMODE = 0; all configuration errors, path errors, etc. will be reported with more detail to help you diagnose where the problems are.

Run ?test

After setting the $ERRORMODE = 0; then you can run an initial ?test

1. Run the ?test mode for each of the main scripts:
   Type in the full URL to <mof.cgi> on your server, append the "?test" command
   Type in the full URL to <mofpay.cgi> on your server, append the "?test" command
   
   http://www.site.com/cgi-bin/mcart/mof.cgi?test
   http://www.site.com/cgi-bin/mcart/mofpay.cgi?test

This will perform some initial tests, and may show you where some of the more glaring problems are. Consult the Troubleshooting.html document to help with any problems there

If all looks well there, but you're having some other problems, then continue testing the cart while in troubleshooting mode, and consult any error messages presented by MOF

If you cannot get the scripts to run ?test

Tip: refresh your browser regularly, empty the browser cache, etc. to make sure you are not viewing cached browser pages, instead of real live error pages

1. Open up both main program files in your ASCII editor
   • mof.cgi
   • mofpay.cgi
     
     
2. Find the exact second line in each file, which looks like this:
   # use CGI::Carp qw(fatalsToBrowser);
   
   
3. Uncomment the line to make it active (remove the # character in front)
   use CGI::Carp qw(fatalsToBrowser);
   
   
4. FTP (ASCII only) both program files back to your server

This will set up an additional level of feedback from the servers CGI environment. Most of the messages will report "Software Errors." You must read the messages carefully for clues on what you did wrong.

Common causes for run ?test failure

Tip: refresh your browser regularly, empty the browser cache, etc. to make sure you are not viewing cached browser pages, instead of real live error pages

Here are the most common things that go wrong for beginners, listed in order of probability:

• One or more script files did not transfer ASCII mode: help
• Do not have execute permissions on the *.cgi files: help
• You have Perl syntax errors in configuration files
  
  Enable CGI::Carp (instructions above). CGI::Carp will report filename(s) and line number(s) where the Perl interpreter found errors. If you need help with Perl syntax rules see: Docs > AboutConfigurations.html, then check the lines surrounding what CGI::Carp is reporting
  
  
• One or more script files are missing: help
• Make sure the path to perl is correct (pretty uncommon)
  
  First line in mof.cgi and mofpay.cgi
  In the package, Path to perl is set to #!/usr/bin/perl
  Your server may ask you to set it to #!/usr/local/bin/perl
  or perhaps even something different
  
  
• You are on an NT/Win server and scripts do not have execute privileges
• You are on an NT/Win server and need to adjust @INC
• You are on an NT/Win server and need to run MOF as *.pl files only
  Find NT help here
  
  
• In very rare cases I have seen where the server actually requires script files to be stored on the server in UNIX format. If on windows, you'll need an ASCII text editor which can SaveAS UNIX
  

MORE ABOUT ABSOLUTE PATHS

Here's a few more tips on absolute paths under other situations.

Also, a good tip to solve any absolute path problems you are having with MOF, is to obtain a simple script, like a formmail script, or counter, etc. Many hosting services provide pre-installed scripts. Get some simple scripts going on your web site, and look into how those scripts are defining absolute paths.

Absolute paths on NT/Win

NT/Win will need absolute paths defined a little different that UNIX/Linux.

examples
/ABSOLUTE-PATH-TO-DATA/ --> D:\PATH-TO-DATA\
/ABSOLUTE-PATH-TO-WEB/ --> D:\PATH-TO-WEB\

• notice the beginning Drive letter
• notice the backslashes, not forward slashes

NT final adjustments: If you are using the search-replace instructions to install MOF, then use the NT/Win paths as in the example above. Then, before you FTP your files to the server, you should make these quick adjustments to both configuration files:

• in mof.conf
  search for: orderdata\
  replace with: orderdata\\
  
  search for: orderinfo\
  replace with: orderinfo\\
  
  
• in mofpay.conf
  search for: orderdata\
  replace with: orderdata\\
  
  search for: invoices\
  replace with: invoices\\

If you don't do this you'll get a Server Error.  What happens is that the backslash has powerful meaning in Perl, and you need to tell Perl that you want a backslash as a literal ending character on the pathway, else, Perl will truncate the ending quote. You can't compensate for that in the installation search-replace, because that ending is not available to be replaced, so you have to do it independently

using a dynamic path

If your server requires that you use dynamic paths, then complete the installation search-replace for DATA and WEB absolute paths this way:

• do this
  /ABSOLUTE-PATH-TO-DATA/ --> /
  /ABSOLUTE-PATH-TO-WEB/ --> /
  
  
• use only a forward slash as replacement
  

Final adjustments: Before you FTP the files to the server, you should make these adjustments to both configuration files. Open both configuration files in your ASCII editor. You'll need to make some manual changes, not search-replace.

Note: these adjustments are based on the $ENV{DOCUMENT_ROOT} variable, which is the CGI environment variable for your root file space. This is the most common way to create dynamic absolute paths, however, some very large hosting companies have their own way of doing this, and may assign a different variable for the dynamic path root.

• in mof.conf
  $datadirectory = $ENV{DOCUMENT_ROOT} . '/orderdata/';
  $infodirectory = $ENV{DOCUMENT_ROOT} . '/orderinfo/';
  $accept_order_template = $ENV{DOCUMENT_ROOT} . '/mofcart/mofviewcart.html';
  $validation_template = $ENV{DOCUMENT_ROOT} . '/mofcart/mofvalidate.html';
  $preview_info_template = $ENV{DOCUMENT_ROOT} . '/mofcart/mofshipping.html';
  $preview_template = $ENV{DOCUMENT_ROOT} . '/mofcart/mofsummary.html';
  
  
• in mofpay.conf
  $datadirectory = $ENV{DOCUMENT_ROOT} . '/orderdata/';
  $save_invoice_path = $ENV{DOCUMENT_ROOT} . '/invoices/';
  $payment_info_template = $ENV{DOCUMENT_ROOT} . '/mofcart/mofbilling.html';
  $final_template = $ENV{DOCUMENT_ROOT} . '/mofcart/mofconfirmation.html';
  $save_invoice_template = $ENV{DOCUMENT_ROOT} . '/mofcart/mofinvoice.html';

Note: this usually requires that your ../orderdata/ and ../orderinfo/ be placed in your main public web file space, along side the ../invoices/ and ../mofcart/ directories

CREATING YOUR OWN TEMPLATES

See documentation : Making your own templates. (Formatting.html)

The 9 MOF templates are located in the ../mofcart/ directory

1. mofcookies.html
2. moferrors.html
3. mofinvoice.html
4. mofshipping.html
5. mofsummary.html
6. mofvalidate.html
7. mofviewcart.html
8. mofbilling.html
9. mofconfirmation.html

Note: if the MOFcart checkout portion is installed under SSL, the last two templates must have all images, CSS, etc. referenced to the SSL URL.

If you edit the templates, you will need to edit all 9 of them:  They can all be different or the same. MOF uses all of these 9 templates to surround cart functions, which allows you to put your own unique message to show for each of the cart areas and functions.

Note: It's best to use the full URL for any images, CSS, or other objects in your templates. The templates are processed via the CGI on your server, and some CGI environments do not handle relative addressing correctly.

If you edit the templates this line must appear as an HTML comment line at the place in the template where you want MOF to place its output.

<!--MOF-INPUT-AREA-->

It must be on a line by itself. Double check that your html editor has kept it on a line by itself.

The templates can be any HTML design.  Avoid anything too fancy, like a reloading Java menu.  When operating out of a server's CGI only your browser should be allowed to reload a script, so that it can rePOST the necessary data.

These programs are copyright @ MerchantOrderForm.com, MerchantPal.com 2001