Commerce.cgi 2.0 These docs are still very much under construction. We're working hard to create extensive documentation and will be updating this file regularly. Commerce.cgi 2.0 is distributed according to the GNU General Public License. Please read this license before proceeding: http://www.careyinternet.com/main/commerce/license.html No support is offered for this product. We wish we could help everyone, but it's just not possible. There is a support forum available at http://www.careyinternet.com/main/support/bbs and you can subscribe to the mailing list by visiting http://www.onelist.com/subscribe/commerce.cgi ################################################################ Finally, we are ready to release Version 2.0 of Commerce.cgi. I've been working on this whenever I've had a chance, but there just never seems to be enough time :-) First I want to say thanks very much for your support. I wish I had more time to offer help to Commerce.cgi users, but it just never seems to happen. I'm really impressed by the helpful community that exists on the Mailing List and Support Forum....it's great to see users helping each other out...one of the many cool things about Open Source software! Anyway, we're very excited about this new version. It includes some long awaited new features that may be helpful... 1) Product pages finally have "Next" and "Previous" buttons, so you don't have to display every product in a category on one long page... 2) Multiple options per product are now supported 3) Shipping is no longer calculated as a percentage of the total order (MANY people complained about this!). Now, you can assign a shipping price to each individual product. 4) The look and feel of the product pages can now be edited much more easily. We've broken the html for the product pages out into separate template files, so you no longer have to dig through the library files to make changes. 5) You can now add 5 user defined fields to each product and display them on your product pages. The template files allow you to add 'tokens' to the product pages that will be replaced dynamically with the data values. 6) The standard and pro versions are now combined into one. If you aren't quite ready for real time credit card processing, you can change a setting in Store Manager to process your orders 'Offline'. If you decide later that you want to use AuthorizeNet or iTransact, you can make a few quick changes in Store Manager and you'll be all set! Also, if you choose AuthorizeNet or iTransact, the script is now setup to use the gateway's secure server...a separate secure server on your end will no longer be necessary (unless you choose 'Offline' processing), as all the form data will be collected on the gateway's secure orderform... 7) Cookie settings will be way easier to set...we've added in some regular expressions to determine the correct settings based on your URL... 8) The annoying 'Path To Html' variable has been removed. 9) Other things that I don't remember right now.... One thing to be aware of: This is a totally NEW version of Commerce.cgi, this is NOT an upgrade! The data.file uses a different format now as we've included the user defined fields and the shipping price, and we've made many chages throughout the supporting libraries. I wish we could offer a smooth upgrade, but I don't have the resources or time to make that possible. At some point, I'd like to offer a perl script that will convert the old data.file to the new format...unless someone else offers it first :-) ################################################################ Telnet Installation Currently, we only offer docs for telnet installation. We will offer ftp docs soon. Upload the file commercecgi.tar to the /cgi-bin directory on your web server. Be sure to upload the file as a BINARY file, not as an ASCII file! Telnet into your web server and at the command prompt, type the following: tar -xvpf commercecgi.tar This will create a directory within the /cgi-bin directory called /store. This directory will contain the commerce.cgi program and supporting libraries. **Before Doing Anything Else** Make sure that the first lines of manager.cgi and commerce.cgi 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, ask your Systems Administrator for the correct path. -----Enabling Store Manager----- Next, to get the store up and running, you will need to enable the Store Manager. While the Store Manager itself uses simple password protection, for greater security you *must* also password protect the /store/protected directory. To do this, you will need to telnet into your web server and change directories (cd) to the /store/protected directory. Here, if you view the files by typing 'ls' (without the quotes), you will see an called htaccess. Open this file in the text editor of your choice and look for the line: #AuthUserFile /mnt/web/guide/dial411/dev1/store/protected/manager.access Here you must un-comment this line by removing the # symbol directly before the word 'AuthUserFile'. Next, you will need to set the path that follows the 'AuthUserFile' to your web server's path to the 'manager.access' file. This is the SERVER PATH, not the URL. If you are unsure what this is, type 'pwd' (without the quotes) at the command line from within in the /protected directory or ask your Systems Administrator. Save this file as .htaccess (Note the addition of the 'dot' in front of htaccess). Next, pick a user name, and type the following on the command line... htpasswd manager.access your_user_name The server should respond with... Adding user your_user_name New password: (you'll type your password) The server should respond with... Re-type new password: (you'll type it again :-)) Please note: If your system does not support 'htpasswd' (as some of you have told me), the Store Manager is also password protected. This is just for some added protection - YOU STILL NEED TO PASSWORD PROTECT THE /protected directory. Ask your System Administrator to help you...they should be able to offer you a way to password protect this directory. While you're waiting to hear from your SysAdmin, you can TEMPORARILY skip over the directory password protection by doing the following. 1) Rename the .htaccess to .htaccess.back. This removes the login prompt to the directory 2) Open up the manager.cgi file in a text editor and change the username and password variables at the top. The file contains directions to walk you through this. 3) The program stores your I.P. address in a temporary file to keep track of you during your visit. You must rename this file to something unique that you choose. Set the $a_unique_name variable to whatever name you like, just DO NOT skip over this step! If you find the login page just reloads itself over and over, this is one possible reason why that is happening. Last warning: Don't forget to password protect the /protected directory as soon as possible! Now you must set a few important pieces of information unique to your store. Access the Program Settings page using this syntax: /cgi-bin/store/protected/manager.cgi?welcome_screen=yes If you leave off the '?welcome_screen=yes' part of the URL, a blank page will be returned, so make sure to use the correct URL to access Store Manager. -----Using Store Manager to set the Program Settings----- Login to Store Manager and select the 'Program Settings'. After successfully logging in you will be taken directly to the 'Add A Product' screen of Store Manager. Click the 'Program Settings' link at the top of the page. 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. This selection is new in Commerce.cgi 2.0 and allows you to choose either 'Offline', "AuthorizeNet' or 'iTransact'. 'Offline' simply means that you'd like to have your orders logged and you will process them offline through your own credit card software. The order is logged to a text file on the server and also e-mailed to the merchant. For security, the text file on the server will contain the type of credit card that is being used and the first eight digits of the credit card number. The e-mailed copy of the order that is sent to the merchant will contain the last eight digits of the credit card number, and the expiration date. While it is a housekeeping chore to collate these two files to obtain the full credit card information, it is also more secure. Many people have problems setting up PGP encryption on their server, so this seemed to be a resonable alternative. Plus, PGP technically needs to be purchased for commercial use. If this process doesn't work for you, you may want to consider using real time credit card processing. Commerce.cgi 2.0 currently allows you to use choose from AuthorizeNet or iTransact. Whether you choose 'Offline', 'AuthorizeNet', or 'iTransact', you will need to enter some additional information in the new "Gateway Settings' screen. We'll learn more about that after we get through the rest of the 'Program Settings'.... 2) 'Please enter the full URL of your /images directory. For example: http://www.careyinternet.com/cgi-bin/store/html/images DO NOT include the trailing slash!!' Commerce.cgi 2.0 does away with the annoying 'Path To Html' variable that we used in the 1.02 version. Now, if you find that you cannot serve images from your /cgi-bin directory, you can simply create an images directory somewhere else on your server and enter the URL to that directory here. Just as it says, DO NOT include the trailing slash in the URL! 3) 'Please enter the full URL of your store here: (ex: http://www.careyinternet.com/cgi-bin/store/commerce.cgi)' To help fix another annoying problem from version 1.x, we've added some regular expressions into Store Manager to calculate your cookie settings. Now you can just enter the full URL to your store here and the cookie settings should be all set. One important note: Cookies are very particular and need to be set carefully. Specifically, take a look at these two URLs http://www.careyinternet.com/cgi-bin/store/commerce.cgi http://careyinternet.com/cgi-bin/store/commerce.cgi If you drop the 'www' from your URL in this setting, and then try and 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 selcted above will have this percentage added to the order for sales tax. 6) 'Do you wish to have orders e-mailed to you?' 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?' 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.... **Offline Processing If you've chosen to process your orders offline, you will only be asked to enter one more piece of data 1) 'Please enter the Secure URL to your commerce.cgi store.' Because you are collecting credit card data, you really should have a secure connection when that data is sent from the orderform to the server. Commerce.cgi requires that the secure URL is accessing the exact same commerce.cgi file as the standard URL. For example: http://www.careyinternet.com/cgi-bin/store/commerce.cgi http://server6000.net/careyinternet/cgi-bin/store/commerce.cgi Both access the same exact file, one is through a standard http connection, the other is through a secure https connection. If you're hosting company expects you to put secure files on a different machine, commerce.cgi will not work. If they want you to put secure files in a special directory, you *may* be able to creat a softlink from the secure directory to the directory containing commerce.cgi. Ask your Server Administrator for assitance. Hopefully, you will simply be able to enter the secure URL and you'll be all set.... **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 orderform. It is no longer necessary for you to have a secure server on your end to use Commerce.cgi 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 orderform. 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 orderform.' 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 orderform.' 8) 'Enter the text that you'd like displayed at the bottom of your orderform.' 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 your customer's e-mail receipt.' 12) 'Enter the text that you'd like displayed at the bottom of your customer's e-mail receipt.' The e-mail receipt is sent to the customer by AuthorizeNet after the order is processed. **iTransact Processing If you've chosen to use iTransact, you'll be asked to enter some additional information. Most of it is self explanatory, and will be used to customize the iTransact orderform. It is no longer necessary for you to have a secure server on your end to use Commerce.cgi with iTransact. All order data is now collected on the iTransact secure server... 1) 'Gateway Username' Enter a valid username provided to you by iTransact 2) 'Secure URL to your Gateway's server' This is most likely: https://secure.itransact.com/cgi-bin/mas/split.cgi 3) 'Enter the name of your business here.' Self explanatory 4) 'Are setup to accept credit cards through iTransact? Select '0' for no, '1' for yes.' 5) 'Are you setup to accept checks through iTransact? Select '0' for no, '1' for yes.' 6) 'Are you setup to accept EFT through iTransact? Select '0' for no, '1' for yes.' These three variables need to be answered correctly for your specific account. If you are unsure of any of these, contact iTransact support for assistance. 7) 'Do you want to allow customers to enter an alternate shipping address? Select '0' for no, '1' for yes.' If you answer yes to this, the iTransact orderform will allow customers to enter a shipping address that is different from the billing address. Depending on your business, you may or may not want to allow this... 8) 'Enter the text that you'd like to appear in the body of the confirmation e-mail sent to the customer.' This is the e-mail that is sent to the customer by iTransact after the order is processed. ----------------------------------------------------------------- Adding your Header, Footer, and Frontpage The header and footer is displayed on all of your dynamic product pages. There are separate header and footer files which are displayed on the orderform, 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 commerce.cgi is accessed. 1) Create your standard header HTML and save it in a file called store_header.inc. This file should NOT include <html> or <body> tags - use the sample store_header.inc as a guide. Upload this file and place it in the directory /cgi-bin/store/html/html-templates 2) Create your secure header HTML and save it in a file called secure_store_header.inc. This file should NOT include <html> or <body> tags - use the sample secure_store_header.inc as a guide. This file can contain secure links to images if needed. Upload this file and place it in the directory /cgi-bin/store/html/html-templates 3) Create your standard footer HTML and save it in a file called store_footer.inc. This file should NOT include </html> or </body> tags - use the sample store_footer.inc as a guide. Upload this file and place it in the directory /cgi-bin/store/html/html-templates 4) Create your secure footer HTML and save it in a file called secure_store_footer.inc. This file should NOT include </html> or </body> tags - use the sample secure_store_footer.inc as a guide. This file can contain secure links to images if needed. Upload this file and place it in the directory /cgi-bin/store/html/html-templates 5) 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. ----------------------------------------------------------------- Editing the look and feel of your product pages We've tried to make it a little easier for desigers 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%%