Installation Step 1 - Depending upon which file you downloaded, decompress (unzip or untar) the downloaded file using WinZip or a similar program. Click Here for more info on the UNIX tar command. This should leave you with a directory named /store that contains all of the necessary shopping cart files. Step 2 - Upload this entire directory to your /cgi-bin. All of these files MUST be transferred in ASCII mode!!! The ONLY exceptions to this are the files contained in the directory /store/html/images which need to be transferred in BINARY mode. WARNING - Failure to transfer these files in the correct mode (ASCII or BINARY) is one of the most common causes of problems - TAKE YOUR TIME AND DO THIS RIGHT :-) Step 3 - Now you must set the permissions on these files ( ask your web host if you are unsure how to do this ). chmod 777 /store/admin_files directory and all files within Hint: chmod -R 777 directoryX will change all the permissions of the files in directoryX and below. chmod 777 /store/data_files directory and all files within chmod 777 /store/log_files/ directory and all files within chmod 755 /store/protected/checkoutmanager.pl file chmod 777 /store/shopping_carts directory chmod 755 /store/checkout.pl file *******>IMPORTANT SIDEBAR<******* Although this will effectively disable Store Manager, you'll probably want to re-visit this area after you complete your installation and tighten up your permissions as follows. chmod 744 /store/admin_files directory chmod 644 all files within /store/admin_files directory chmod 644 all files within /store/html/html-templates/ directory chmod 744 /store/data_files directory chmod 644 /store/data_files/data.file *******>END IMPORTANT SIDEBAR<******* -> Before Doing Anything Else Check That The file 'checkout.pl' is located in the /cgi-bin/store directory The file 'checkoutmanager.pl' is located in the cgi-bin/store/protected directory Make sure that the first lines of checkoutmanager.pl and checkout.pl contain the correct path to perl on your system. This line should look something like: #!/usr/bin/perl -T It is *very* important that you use perl version 5. Some systems have both version 4 and version 5 installed in different locations for backwards compatibilty. The scripts may appear to run with perl 4, but you will encounter weird errors along the way. If you're unsure at all, ask your Systems Administrator for the correct path to perl 5. -------------------------------------------------------------------------------- Windows (NT, 2000) Server Users Often some extra modifications are need for the cart to work on a Windows Server. 1) Open checkout.pl you will see 3 or 4 lines down the line '$is_nt = "no";' change this to '$is_nt = "yes";' 2) If you get an error similar to "Can't locate ../relative_path/file.pl in @INC" Then you will have to modify checkout.pl and checkoutmanager.pl simply add the lines to the second line of the script. This is for checkout.pl (1st line)#d:/apache/usr/bin/perl.exe # or what ever the path to perl is (New 2nd line) push @INC,"/full/path/to/the/store/directory/"; Now open checkoutmanager.pl and add, (1st line)#d:/apache/usr/bin/perl.exe # or what ever the path to perl is (New 2nd line) push @INC,"/full/path/to/the/admin/directory/"; -------------------------------------------------------------------------------- Enabling Store Manager Next, to get the store up and running, you will need to enable the Store Manager. For security you should password protect the /cgi-bin/store/protected directory. If you do not password protect the directory anyone that knows a bit about this shopping cart and has nothing better to do can get in and modify your settings and cause general havoc. If you are unsure how to do this, ask your System Administrator (or Web Hosting Company) to help you...they should be able to offer you a way to password protect the directory. You can continue on with the setup, but do not forget to get the password protection set up before you go live. YOU HAVE BEEN WARNED! Now you must set a few important pieces of information unique to your store. Access the 'Program Settings' section of Store Manager through your Web Browser by accessing this URL http://www.your-site.com/cgi-bin/store/protected/ checkoutmanager.pl?welcome_screen=yes You need to change www.your-site.com to reflect your specific URL and path. If you have problems with Store Manager, please double check your permission settings - that is almost always the root of the problem! -------------------------------------------------------------------------------- Using Store Manager to set the Program Settings The Program Settings screen allows you to easily set certain configuration variables for your store. We'll go through each of these choices one by one... 1) Please choose how you will process orders Here you choose how you'd like to process your orders. You can choose either 2CheckOut or AuthorizeNet. Whether you choose 2CheckOut or AuthorizeNet, you will need to enter some additional information in the new Gateway Settings screen. We'll learn more about this after we get through the rest of the Program Settings.... 2) Please enter the full URL of your /images directory. For example: http://www.yoursite.com/cgi-bin/store/html/images DO NOT include the trailing slash!! Note: Many web hosts do not allow the serving of images from the cgi-bin, so you may need to move the images directory out from under the cgi-bin. 3) Please enter the full URL of your store here: (ex: http://www.yoursite.com/cgi-bin/store/checkout.pl) One important note: Cookies are very particular and need to be set carefully. Specifically, take a look at these two URLs: http://www.yoursite.com/cgi-bin/store/checkout.pl http://yoursite.com/cgi-bin/store/checkout.pl These two URLs may access the same file, but they ARE NOT the same URL!. If you drop the 'www' from your URL in this setting, and then try to access your Store using the 'www' in the URL, you'll find that the cookie won't be set. Similarly, if you include the 'www' in this setting, but access the Store without using the 'www' in the URL, the cookie won't be set. Just be consistent with how you use your URL and you shouldn't have any problems. If you're worried that visitors to your Store may drop the 'www' on their own, just make sure that all the links on your FrontPage include the 'www' and then the cookie will be set when they click through.... 4) Customers from the state selected here will be charged sales tax This is self explanatory. Orders that are SHIPPED to this state will be charged sales tax. 5) Enter sales tax percentage here. Enter as a decimal number. Ex: ".05" for "5%", ".06" for "6%", etc. Orders that are shipped to the state selected above will have this percentage added to the order for sales tax. 6) Do you wish to have orders e-mailed to you? You'll probably answer 'yes' to this... 7) Enter the e-mail address where you'd like the orders sent Self explanatory - just make sure that it's an address that is reliable. 8) Do you wish to have the orders written to a log file? You'll probably answer 'yes' to this too... 9) Choose a unique name for your log file. (ex: "mylog3218.txt") This is *very* important. Make up an odd name that only you will remember...use letters and numbers. This file will contain your order data and will be located in the /cgi-bin/store/log_files directory. It is a wise idea to password protect this directory! 10) Enter the e-mail address of your webmaster or administrator here This is the e-mail address that appears as the return address when the customer is sent an order confirmation e-mail. A customer service e-mail address is a good choice for this.... Once you have entered all of the data above, you can click the Submit button. You should see a message stating: System settings have been successfully updated. Check your Gateway Settings here Click the Gateway Settings link. Depending upon how you've decided to process orders, you will be asked for certain information.... -------------------------------------------------------------------------------- 2CheckOut Processing If you've chosen to use 2CheckOut.com, you'll be asked to enter some additional information. Most of it is self explanatory. It is not necessary for you to have a secure server on your end to use checkout.pl with 2CheckOut.com . All order data is (optionally) collected on the 2CheckOut secure server... 1) Seller ID Enter a valid seller ID provided to you by 2CheckOut 2) Test Mode On? If yes, then no credit card is charged. Used to setup the cart and test. Set to No when ready to start accepting orders. Most of the settings for customizing 2Checkout.com's payment routines are handled in the 2Checkout.com Admin Area. -------------------------------------------------------------------------------- AuthorizeNet Processing If you've chosen to use AuthorizeNet, you'll be asked to enter some additional information. Most of it is self explanatory, and will be used to customize the AuthorizeNet order form. It is no longer necessary for you to have a secure server on your end to use checkout.pl with AuthorizeNet. All order data is now collected on the AuthorizeNet secure server... 1) Gateway Username Enter a valid username provided to you by AuthorizeNet 2) Secure URL to your Gateway's server This is most likely: https://secure.authorize.net/gateway/transact.dll 3) Complete URL to the logo you'd like to display on your order form. This MUST be a secure https URL. You can also leave this blank if you prefer. This is self explanatory. If you choose to include this, just make sure it is a SECURE url or you'll have problems. 4) Background color of your order form. 5) Text Color 6) Link Color These three are all self explanatory customization variables.... 7) Enter the text that you'd like displayed at the top of your order form. 8) Enter the text that you'd like displayed at the bottom of your order form. Self explanatory.... 9) Enter the text that you'd like displayed at the top of your receipt page. 10) Enter the text that you'd like displayed at the bottom of your receipt page. Self explanatory... 11) Enter the text that you'd like displayed at the top of the customer's e-mail receipt. 12) Enter the text that you'd like displayed at the bottom of the customer's e-mail receipt. Self explanatory...the e-mail receipt is sent to the customer by AuthorizeNet after the order is processed. -------------------------------------------------------------------------------- Adding Products To Your Datafile Although there is no 'hard-coded' limit to the amount of products that can be maintained by Store Manager (or used by checkout.pl), we generally recommend that you use caution (100 to 200 products max). This is for performance reasons, mostly. Nothing is programmed into checkoutmanager.pl or checkout.pl to limit the amount of products, but you may see server performance problems if your datafile becomes too big....just be careful and consider yourself warned :-) The 'Add A Product' screen of Store Manager can be access here: http://www.your-site.com/dev/cgi-bin/store/ protected/checkoutmanager.pl?add_screen=yes Obviously, you need to change this to reflect your specific URL and path. 1) Reference # - This value is entered automatically by Store Manager. This is not a SKU number, but simply a unique number needed by checkout.pl to identify this particular product 2) Category - This should be one word only, no spaces. checkout.pl displays products on dynamic product pages based on this category. For example, to display all of the products in the 'books' category, you create a link that looks something like this: http://www.your_domain.com/cgi-bin/store/checkout.pl?product=books 3) Price - just the numeric price, no $ sign needed 4) Product Name - two or three words to identify the product. This value is displayed in the shopping cart. 5) Image File - This is just the name of the image file, NOT the complete URL or path! If you've correctly set the 'URL To Images' field in the Program Settings screen, you this image should display correctly on your checkout.pl product pages. 6) Option File - the filename of your options file NOT the complete URL or path. The options files are located in the /store/html/options directory. Check out the sample file called gift_option.html for reference. 7) Shipping Price - This should be set to your base shipping price for each product. See the 'Shipping' Price section of this Read Me for more complete details. 8) User Defined Field One through Five - these five fields allow you to store up to five pieces of data that can be displayed on your product pages by placing 'tokens' within the productPage.inc file. These are defined in the upcoming discussion called "Editing the look and feel of your product pages". Please note that User Defined Fields are NOT captured as a part of the order, they are designed for product page display only. 9) Description - This is where you enter the description and information about the product. HTML can be included here as well... -------------------------------------------------------------------------------- Editing Products Within Your Datafile The Edit Product screen can be accessed here: http://www.your-site.com/cgi-bin/store/ protected/checkoutmanager.pl?edit_screen=yes Obviously, you need to change this to reflect your specific URL and path. Here you will select the product you wish to edit, and then you will be taked to a form similar to the Add A Product form where you can make your changes. -------------------------------------------------------------------------------- Deleting Products From Your Datafile The Edit Product screen can be accessed here: http://www.your-site.com/cgi-bin/store/ protected/checkoutmanager.pl?delete_screen=yes Obviously, you need to change this to reflect your specific URL and path. Here you will select the product you wish to delete. Use this screen with care!! -------------------------------------------------------------------------------- Shipping Levels and Prices As mentioned in the 'Adding Products To Your Datafile' section of this Read Me, every product has a fixed 'base shipping' price assigned in the datafile. To add some additional flexibility, there is now a way to add in additional levels of 'upgrade' shipping. First, you will need to determine which order form you are using. This is dependent upon how you are processing your orders. Look in the /store/html directory and you'll notice four files named *-orderform.html, They are: 2CheckOut-orderform.html AuthorizeNet-orderform.html Choose the order form that matches your method of order processing, download this file in ASCII mode and open it up in your text editor. Look for this SELECT box: This is where you'll add your levels of upgraded shipping. Notice how the "VALUE=" statements contain pipe delimited data such as: 5|U.P.S. Two Day - Upgrade The '5' indicates 5% will be added to the base shipping price defined in the datafile. The 'U.P.S. Two Day - Upgrade' is the method of shipping that will be recorded with the order. -------------------------------------------------------------------------------- Adding your Header, Footer, and FrontPage The header and footer files are displayed on all of your dynamic product pages. There are separate header and footer files which are displayed on the order form, allowing you to include secure links to images more easily. The FrontPage is simply a static HTML page that is parsed by the script and displayed when checkout.pl is accessed. NOTE: Many people are confused by this....to access the FrontPage of your store, your link should look something like this: http://www.your-site.com/cgi-bin/store/checkout.pl The script will grab the file called 'frontpage.html' that is found in the /store/html directory and display that file. DO NOT link directly to frontpage.html!!! PLEASE NOTE: the frontpage.html WILL NOT automatically/dynamically display links to your product categories! This is a static HTML page. Some additional comments on this subject to the frontpage.html that is included with your checkout.pl files - please read that page for more info... 1) Create your standard header HTML and footer HTML (this is done in the "Program Settings" in the admin area). 2) Create your FrontPage HTML and save it in a file called frontpage.html. Upload this file and place it in the directory /cgi-bin/store/html. To view your FrontPage, you need to access checkout.pl through a link that looks something like this: http://www.your_domain.com/cgi-bin/store/checkout.pl PLEASE NOTE: the frontpage.html WILL NOT automatically/dynamically display links to your product categories! As stated, this is a static HTML page. Some additional comments on this subject to the frontpage.html that is included with your checkout.pl files - please read that page for more info... -------------------------------------------------------------------------------- Editing the look and feel of your product pages We've tried to make it a little easier for designers to edit the look and feel of the product pages. There are now template files located in the /cgi-bin/store/html/html-templates directory which will allow you to edit various parts of the product page without digging through the script. The template files are: cart_footer.inc change_quantity_footer.inc delete_items_footer.inc productPage.inc secure_store_footer.inc secure_store_header.inc store_footer.inc store_header.inc The productPage.inc template allows you to drop 'tokens' into the file to easily display product data from the datafile. Here are the possible values... %%image%% %%name%% %%description%% %%price%% %%shippingPrice%% %%userFieldOne%% %%userFieldTwo%% %%userFieldThree%% %%userFieldFour%% %%userFieldFive%% A token is a tag that will be dynamically replaced by the cart. An example would be: The price is: %%price%% Now when a shopper visits the page they would get (taking a product to be $10). The price is: $10 Feel free to modify any of the above files, just make sure that you keep backups. Please note: these tokens are for display only - these values are not included in your order log or confirmation e-mails. -------------------------------------------------------------------------------- Other Resources The shopping cart as provided is a modified version of the cart available at www.commerce-cgi.com. As such additional resources are available there including a mailing list and support form found here. Both carts are based on Selena Sol's 'Web Store' program, which also has a helpful user community and more information found here. -------------------------------------------------------------------------------- Hopefully, this Read Me has answered some of your basic questions. Good luck with your online business!