PerlShop^TM Manual
(version 1.0)

Table of Contents:

1. Overview
2. Installing the Script
3. Customizing the Script
1. Server Customization
2. Company Customization
4. Creating the Catalog Pages
1. Catalog Page Format
2. Automating Catalog Page Creation
5. Appendix
1. Security
1. File Security
2. Transaction Security
2. Debugging
3. Output File Formats
1. Customer File
2. Order File
3. Log File
4. Requirements

PerlShop is a shopping cart program that displays a catalog that is embedded in static html pages using hidden form field tags. You can use any design for your catalog pages, PerlShop will only add navigational menu bars and buttons when it displays the pages.

A unique order number is assigned to each user upon entering the store. The order number is used to keep track of the state of each user's transactions and is saved across each user's session using hidden fields.

PerlShop was designed from the beginning with security in mind. Please read the security section below to make sure you understand how to properly implement the security features before you start accepting orders.

1. Locate your cgi directory (usually 'cgi-bin'), change to that directory, and create a subdirectory under it to hold the PerlShop script, e.g. 'mkdir MyStore'.
2. Change the permission on the directory by entering the command 'chmod 777 MyStore' from within the cgi-bin directory.
3. Copy the PerlShop.cgi script to the subdirectory created in step #1 above.
4. Find the location of the Perl Interpreter on the web server (usually /usr/bin/perl, or /usr/local/bin/perl), you can usually find it by entering 'whereis perl' at the command prompt, if that doesn't work, try entering 'which perl'. If you still have trouble finding it, ask your ISP where it is located.
5. Edit PerlShop.cgi and change the first line to point to the location of the Perl interpreter on the server found in step 2 above, (e.g. '#! /usr/bin/perl').
6. Make it executable by entering one of the following commands at the prompt:
1. If using CgiWrap use: 'chmod 700 PerlShop.cgi'
2. If not using CgiWrap use: 'chmod 755 PerlShop.cgi'
7. Test it out by entering 'PerlShop.cgi' at the command prompt, it should display a copyright notice.
8. Create the following subdirectories under the subdirectory you created in step #1 above:
   customers, orders, catalog, tokens, temp_customers, temp_orders, log. (e.g. /cgi-bin/MyStore/customers, /cgi-bin/MyStore/orders, etc.), and change their permissions with 'chmod 777 customers', etc.
9. Create a subdirectory under your main document directory (usually this is the Public_Html, or the htdocs directory, not the cgi-bin directory!), that will contain contain any image files (gif, jpg) that are to be used by the PerlShop script, and copy the images there.
   

Customizing the Script

10. Server Customization
1. Change the variable '$use_cgiwrap' to 'yes' if running the script under cgiwrap, set it to 'no' otherwise.
2. Change the variable '$server_address' to the ip address (or the equivalent domain name, e.g. www.myserver.com) of the server the script will be running on.
3. If not using cgiwrap, change the variable '$cgi_directory' to the subdirectory of your cgi-bin directory which was created in step #1 under "Installing the Script". e.g. '/cgi-bin/MyStore'
4. Iif you are using cgiwrap, change the variable '$cgiwrap_directory' to the subdirectory of your cgi-bin directory which was created in step #1 under 'Installing the Script', using a format like '/cgi-sys/cgiwrap/username//MyStore' (see your ISP for the exact format).
5. Change the variable '$image_directory' to point to the subdirectory created above in step #8 under "Installing the Script" to hold image files (e.g. '/MyStore/Images')
6. Change the variable '$mail_program' to point to the location of the sendmail program on the server (e.g. '/usr/sbin/sendmail')
7. If you did not use the default subdirectory names as specified above in step #9 under "Installing the script", then you must modify the corresponding variables in the script to point to the subdirectories that you created.
   
11. Company Customization
1. If you wish to include an image at the top of the pages generated by PerlShop, you must change the values of the '$banner' variable, and the associated image attribute variables ($hspace, $vspace, $border, $height, $width, $width, $align). If you do not want to include an image, you must set the value of '$banner' to a null string (e.g. "").
2. If you wish to include a background image or change the background color of the generated pages, change the value of the '$background' and '$background_color' variables.
3. Change the '$company_name' variable to the name of your own company.
4. Change the '$company_address' variable to the address of your own company, each address line must be separated by a '<br>' html tag.
5. Change the '$company_email' variable to the email address at your company that you will use for catalog related inquiries.
6. Change the '$mail_order_to' variable to the email address at your company that will receive the emailed order confirmations.
7. Change the '@accept_payment_by' variable to include the valid methods of payment that your company will accept.
8. If your company will accept credit card payments, then change the '@valid_credit_cards' variable to include the valid card types your company will accept.
9. If your company will accept COD payments, then change the '$cod_charge' variable to the value of the amount that will be added to the order for COD shipments.
10. Change the '$Pay_checks' variable to the name of the person or company that checks should be made out to if the order is being paid by check.
11. Change the text of the '$return_policy' variable to reflect your own company's return policy that will be included at the bottom of each order confirmation.
12. Change the '$shipping_type' variable to the method of calculating shipping that your company will use.
13. Modify the '@Shipping_Rates' variable to reflect the shipping companies that your company uses, and the rates your company charges.
14. Modify the '@Tax_States' variable to include any states for which your company must charge sales tax, and the rate charged.

1. Catalog Page Format
1. Each page of your catalog that you create must have a tag on the first line of the page that has links to the previous and next pages of the catalog. For example, the tag for the first line of page2 of the catalog would look like:
                     <PSTAG prevpage=page1.html nextpage=page3.html>
   ( If page1.html was the first page, then on page1.html you would use page1.html as the prevpage. If the last page was page3.html, then on page3.html you would use page3.html as the nextpage).
2. Each Individual item for sale in the catalog must be contained within an html <form>...</form> block. A sample follows with an explanation of each line below it:
1. <FORM METHOD=POST ACTION="http://www.arpanet.com/cgi-bin/PolishBooks/perlshop.cgi">
2. <input type="submit" name=ACTION value="ORDER">
3. <INPUT TYPE=HIDDEN NAME=ORDER_ID VALUE="!ORDERID!">
4. <INPUT TYPE=HIDDEN NAME=ITEM_ID VALUE="12345">
5. <INPUT TYPE=HIDDEN NAME=ITEM_NAME VALUE="Polish for Dummies">
6. Polish For Dummies $212.98 <br>
7. <INPUT TYPE=HIDDEN NAME=ITEM_PRICE VALUE="212.98">
8. <INPUT TYPE=HIDDEN NAME=ITEM_CODE value="!ITEMCODE!">
9. <INPUT TYPE=HIDDEN NAME=thispage value=page1.html>
10. Qty:<INPUT TYPE=TEXT SIZE=3 MaxLength=3 NAME=QTY VALUE="1">
11. This book is especially good for beginners. <br>
12. </FORM>

Description of each line above:

1. This is the opening form tag with the location of the perlshop.cgi program on your server.
2. This is a hidden field that tells the perlshop script to process the 'ORDER' action command, and creates the 'ORDER' button on the catalog page.
3. This is a hidden field that has a placeholder !ORDERID! that will be replaced automatically by the perlshop script with the actual unique invoice number for this shopping session.
4. This is a hidden field whose value should be set to item number you have assigned for this catalog item. Each item number must be unique.
5. This is a hidden field whose value should be set to the name of the item.
6. This is the name of the item, and the price, as it will appear on the catalog page.
7. This is a hidden field whose value should be set to the price of the item. The price must be in the format '999999.99', i.e. no commas, and no leading dollar sign. There is no limit on the actual price of the item.
8. This is a hidden field that has a placeholder !ITEMCODE! that will be replaced automatically by the perlshop script with a unique digital signature generated for this catalog item and shopping session only
9. This is a hidden field whose value should be set to the actual file title of the page that this catalog item is located in.
10. This is the Quantity field that will appear on the form whose value is the default number of items that will be ordered if a customer orders this item.
11. This is some descriptive text you can add if the item name does not sufficently describe the item being ordered.
12. This is the closing form tag.
    
2. Automating Catalog Page Creation
   There are several programs currently available that will allow you to generate your catalog pages from an existing database. The programs usually read an html template file that you have created, replacing special tags with data from the database.
1. BestWeb
2. BackPage(tm)  Free (requires Microsoft Access 95 and Microsoft Windows 95)
3. 4W Publisher(tm)
   
3. Appendix
1. Security
   IMPORTANT NOTE: PerlShop as distributed includes several security features, but these must be augmented by external programs for real security. No guarantees or warranties of any kind regarding security are made, either using PerlShop alone or augmented by external programs. Since PerlShop is distributed as source code, it is possible someone could modify it to create holes in the security. One way to minimize this possibility is to record digital signatures, using MD5, SHA or PGP, of perlshop.cgi and check them occasionaly.
1. File Security
   The files created by an internet server are normally created under the user 'nobody', this is not very secure since anyone else running a script under the default 'nobody' user would have access to those files.
   The only way to secure the PerlShop output files is to run it under your own userid. This can be done by using the program cgiwrap. When using cgiwrap, the script itself should have it's permissions set to 700 to prevent access from a non-cgiwrap URL.
   PerlShop will also set all output file permissions so that the files created are only accessable to your own userid.
   The output files should be created in subdirectories of your cgi-bin directory as specified in the Installing the Script section above, and not within your server's document directory.
   The output files are not encrypted online, since anyone having access to them would obviously have access to the encryption key used within the program as well.
   The output files should be periodically removed from the Internet server as often as possible. If you don't remove them, you should at least encrypt them manually, making sure not to store the encryption key on the server. If transferring the files to your own computer, they should be encrypted first.
2. Transaction Security
   The only way to ensure the security of each transmission is to use an encryption enabled browser/server combination. You just need to find out the URL of your secure server, and change the URL's generated within PerlShop accordingly.
   
   PerlShop attempts to guarantee the integrity of each transaction by creating a digital signature of the data sent in each transaction, and sending the signature along with the data. On receipt of each transaction, the signature is re-computed and compared to the one received, if there were any alterations of the data, the two signatures would not compare, and the transaction is rejected.
   
2. Debugging
   Please see the following references first, then if you still have problems, you can send email to: perlshop@arpanet.com
1. Cgi Debugging
2. The Idiot's Guide to Solving Perl CGI Problems
   
3. Output File Formats
1. Customer File
   A single record CSV (comma separated, quoted) file with the following fields:
   invoice#, ip address, date, time, title, first name, last name , company, street1, street2, city, state, zip, country, email, daytime phone, daytime extension, evening phone, evening extension, fax, Shiptype, Payby, Cardtype, Card#, Expire month, Expiration year, source, suggestions.
2. Order File
   A multiple record CSV (comma separated, quoted) file with the following fields: invoice#, item id#, item name, price, quantity.
3. log File
   A single record CSV (comma separated, quoted) file with the following fields:
   Page title, date, ip address.
4. Requirements:
   PerlShop has currently only been tested using Perl5 under Unix.

ARPAnet Corp.
182 5th Ave. #1R
Brooklyn, NY 11217
718-399-0460
www.arpanet.com
info@arpanet.com

PerlShop, Adverware, and the PerlShop logo are trademarks of ARPAnet Corp.
All other trademarks are the property of their respective owners.