If you're in the business of selling something, or if you've ever thought about selling something, you probably already know that the Web offers an unprecedented marketing opportunity. It's relatively inexpensive, gives you immediate exposure to a worldwide market, puts small and large companies on as close to an equal playing field as you can get, and offers anyone with a little marketing savvy a rich variety of dynamic feedback and analysis tools that make it easy to hone a marketing-oriented site for maximum effectiveness. Best of all, with the right tool you can allow visitors to your site to place orders over the Web, leaving you with nothing more to do than check your email for orders and make sure they get processed. (Of course, it's up to you to make sure your site offers something people want to buy.) WebShop is designed to be such a tool and will allow you to add basic shopping capabilities to your Web site.
Shopping programs can get very complicated very quickly, and entire companies are built around the high-end versions. WebShop is designed to handle all of the basics in a way that makes it easy to customize and extend. It includes a variety of features, each of which is summarized in the following list:
 | Customizable Look Each of the pages of your online store is generated from an HTML page template file that includes special tags for WebShop's commands and data. This allows you to create any look you want for your store. |
| Database Oriented WebShop looks up information such as product prices, shipping costs, and tax rates from ASCII database files and inserts this information into the page templates on-the-fly. As a result, when you update one of the databases, the changes are automatically reflected in all pages that refer to it. (This means, for example, that a price change only has to be made in one place.) |
| Email Order Notification Copies of each order are sent to you (and/or whomever else you specify) via email. You can use this feature in conjunction with a commercial email-to-fax service to receive orders via fax as they are submitted. |
| Email Receipt After an order is completed, WebShop will send a receipt to the customer via email. |
| State Sales Tax Calculation WebShop will automatically calculate state sales tax based on information you set up in a text file. This allows you to specify which states should be charged sales tax and what the appropriate rate should be. |
| Shipping and Handling Calculation WebShop gives you the option of automatically calculating shipping and handling costs, either on an item-by-item basis or based on the total purchase amount. Support is included for multiple shipping options (e.g., FedEx, UPS, and regular mail). |
| Credit Card Screening WebShop will check credit card numbers to make sure that they conform to bank specifications. (It will not, however, confirm whether the card is inactive or stolen.) |
| Automatic Order Expiration If a visitor interrupts their session before finalizing their order, WebShop will automatically expire the order after a specified time period. (You choose the time period.) |
| Multiple Stores WebShop uses a configuration file to specify many of the program's parameters, thereby allowing you to operate multiple stores using a single copy of the program. |
The following variables appear in the source of Guestbook.cgi. You will need to use a text editor when making changes to the following variables contained in the source code.
$WEBSHOP_CGI_URL = "http://www.host.xxx/cgi-bin/WebShop.cgi";
% which sendmail
% whereis sendmail
Some servers, however may not require you to place this script in the cgi-bin. Check with your system administrator if you are unsure.
Files Permissions Chmod Command -------------------- --------------------- ----------------------- Template Files Read chmod 744 [filename] Config File Read chmod 744 [config.txt] User Database Read and Write chmod 766 [database.txt] WebShop.cgi Execute chmod 755 [WebShop.cgi] Taxes File Read chmod 744 [taxes.txt] Product Files Read chmod 744 [filename] Product Database Read chmod 744 [products.txt] Intro HTML Page Read chmod 744 [intro.html]
You can basically call the WebShop program from any one of your existing web pages by simply adding a link to the WebShop.cgi program. However, because this script has been designed to work with multiple users, you will also need to include a QUERY_STRIN G which will allow the script to find your configuration file. This is explained below.
<a href="http://www.host.xxx/cgi-bin/WebShop.cgi?config=/home/username/public_html/config.txt">
The ? is used to denote the beginning of a QUERY_STRING, which is an argument passed through the environment variables to the perl script. The config= part lets the script know to expect the configuration file path directly after that. This can then be pulled off of the URL and used to get all of the information about this specific WebShop, which is held in your configuration file. The configuration file will be explained later on, but basically it allows you to pull out the Shop specific variables in to a separate file and run multiple Shops off of one script.
The actual scripting in WebShop is fairly simple and allows most of the work to be done in the setting up of the WebShop through the HTML files. This allows for a HIGHLY customizable interface into your WebShop, allowing this script to blend into your si te perfectly. Templates are used extensively in this script and every page this script sends to a user will be parsed before he or she sees it.
| WebShop Template Instructions | ||||
| Creating Your Intro Page | ||||
| Creating your Products
| ||||
| Setting up a Tax Table | ||||
| Review, Invoice and Final Templates |
The WebShop Templates is a complex way of allowing a user to custom create their own Shopping pages, and with simple web page comments, add the functionality of the WebShop script.
The WebShop specific template markers generally look like:
<!--command: shopping_item-->text<!--/command-->
There are some variations and these are explained below. You'll notice that you have an opening and a closing command tag, much like in HTML. There are only a total of three commands you can use in your templates. You may think that this will not be ne ar enough to have a shopping center, but it allows you to link to a product, purchase a product or review your purchases. The rest is contained in hidden fields and is done automatically by the script, making your job easier.
If the command is set to 'link', this will take the user to the page for the specified item. This page has been defined in the Product Database. Let's also say that the reference name for this product is '4mb' and t he owner of this wants the link to say, "Check out our special on 4MB SIMMs!'. The corresponding template marker would appear as:
<!--link: 4mb-->Check out our special on 4MB SIMMs!<!--/link-->
When this file is parsed, a link will be created which contains instructions in the QUERY_STRING to link to the page for the product '4mb' as specified in the Product Database and parse it for even more template markers. The link will end up looking lik e:
Check out our special on 4MB SIMMs!
Another command you can use is 'purchase'. This actually adds the product to cart and takes the user to the review page, to show that the product has been added. Taking the example above, if we wanted to create a link for the user to be able to buy thi s product and add it to their list of purchases, we would use the following syntax:
<!--purchase: 4mb-->Purchase 4MB SIMM<!--/purchase-->
When this page is parsed, the new link will be around the text "Purchase 4MB SIMM" and important QUERY_STRING information will be appended in the link. There will also be a text box next to the submit button which allows the user to specify the quantity they want to purchase.
You can also use a command called 'review'. This will allow the user to review there purchases so far. It is also the first step towards finalizing the purchases. From this page, they can change the number of items they want to buy, or erase them comp letely. You can use this tag on anyone of your pages, with a simple:
<!--review: purchases-->Review Purchases So Far<!--/review-->
Let's say you're tired of always having plain links for users to click to buy your product. With the addition of a 'BUTTON:' phrase inside of the 'text' field of your template marker, this plain link will turn into a button users can click on. For inst ance, when linking to the 4 MB of RAM, you want that to be a button. All you need to change the template marker to is:
<!--link: 4mb-->BUTTON:Check out our special on 4MB SIMMs!<!--/link-->
This tells the WebShop.cgi script to turn this plain link into a BUTTON which a user can press, much like a submit button, only it will contain the text after the BUTTON: marker. and look like:
There are also other kinds of template markers. These correspond to any form fields which may have been filled in, or special configuration fields which can be used. They are used as: <<marker_name>>, where marker name is either the name of the form field or the special marker. These are especially useful on the final template. On the invoice page, you will create a form which you want to gather information about the user. Then, on the final page and the email templates, you will need to be able to echo these fields.. So if you created a form field called 'name', you would reference it in the templates as <<name>> and the value of the 'name' form field replace the template marker.
If you have a product database entry like:
8mb:8 Megabyte SIMM:8mb.html:65:2
You could also write the something like:
Product: <<PRODUCT_NAME_8mb>>
Price: $<<PRODUCT_PRICE_8mb>>
Ship & H: $<<PRODUCT_SHIPPING_8mb>>
Purchase: <!--purchase: 8mb-->Purchase <<PRODUCT_NAME_8mb>><!--/purchase-->
That would product output like:
Product: 8 Megabyte SIMM
Price: $65
Purchase: $2
Purchase: Purchase 8 Megabyte SIMM
This way, when you update your database, or prices change, you need not go through the entire process of changing prices on every page.
The Intro HTML page is the first page the shopping user will see once they enter the shopping zone. It will create a unique user ID, which will be coded into all of the web pages they visit and any links they may click on.
The Intro page is most often used a list of your products, however, you can design it however you want and even allow users to purchase your products directly from the main page. All you have to do is incorporate the template makers described in the prev ious section.
Because of this, your intro page could even be used as your only shopping page, listing and describing all products and allowing users to buy directly from there.
Since this may seem kind of complicated right now, let's assume we have a memory store, and we wish to sell 4MB SIMMs - 32MB SIMMs. On our intro page, we will link to each of these products on a unique page. Below is an example of what the HTML source f or your Intro HTML page may look like:
<html> <head> <title>Memory Store WebShop</title> </head> <body> <center> <h1>Memory Store WebShop</h1> </center> Welcome to the Memory Store WebShop. Here, we sell memory from 4MB - 32 MB. Buy as much as you like! Click on one of the links below to visit the web page which contains pricing info and ordering forms.<p> <ul> <li><!--link: 4mb-->4MB SIMM<!--/link--> <li><!--link: 8mb-->8MB SIMM<!--/link--> <li><!--link: 16mb-->16MB SIMM<!--/link--> <li><!--link: 32mb-->32MB SIMM<!--/link--> </ul> </body></html>
That is what a basic Intro HTML Web Page might look like. When parsed it would appear to the user as:
Welcome to the Memory Store WebShop. Here, we sell memory from 4MB - 32 MB. Buy as much as you like! Click on one of the links below to visit the web page which contains pricing info and ordering forms.
| 4MB SIMM |
| 8MB SIMM |
| 16MB SIMM |
| 32MB SIMM |
Keep in mind that that is a simple version of an intro page, and you can design yours to look however you want.
Now that we have linked to product names in our intro HTML pages, we need to actually create a database which allows WebShop to know the filename your products are in (when they are linked to), the price of the products, the name you want shown on the inv oice sheet, and shipping and handling charges associated with this product.
We also need to create the actual page templates if you are linking to separate pages for each item, however this is not needed if you simply use the intro HTML page as your only WebShop page and have all purchasing and price information on that page. Yo u can also include multiple products on one page if they relate to one another or you don't want to create a separate page for each product.
The Product Database defines several things about each product code name. The code name are used so that you do not have to type all of this information in every time you want to link to a product page or allow the user to purchase a product. The Produc t Database set-up looks like:
reference name:Full Product Name:HTML Page:Price:Shipping Per Item
The reference name is the code you use in your template markers. From our Memory Store example above, the reference names would be 4mb, 8mb, 16mb, and 32mb. The Full Product Name is the name of the product as you wish it to appear in the invoice. Keep in mind if the name is longer than 32 characters it will be chopped off at the end. The HTML page, is the page on which the product appears. It can also contain template markers to allow the user to buy the product, link back to the intro page, review their orders thus far, and more. For instance, the pages might be named 4mb.html, 8mb.html and so forth. The HTML page is relative to the $base_products_dir. Price is how much thes e products cost and shipping is the amount of Shipping and Handling Costs associated with this product. There is also a Shipping Table which can be set up to charge by how much they spend at your site. Below is a sample of what the Product Database for the example Memory Store would look like:
intro::intro.html:0:0 4mb:4 Megabyte SIMM:4mb.html:35:2 8mb:8 Megabyte SIMM:8mb.html:65:2 16mb:16 Megabyte SIMM:16mb.html:115:5 32mb:32 Megabyte SIMM:32mb.html:200:5
Notice the first line contains a reference to the intro HTML page. This is so you can use the syntax:
<!--link: intro-->Back to Main WebShop Page<!--/link-->
You will also notice the prices. If it is an even dollar amount, you can leave off any trailing zeros. However you can also include prices like 9.99 or anything else. All prices will be rounded top the nearest hundredth.
Now that you have defined each page in the database, you will need to create a template page, which the script will read in and parse whenever the user clocks on a link to visit that product page. These templates pages use the same syntax all of the othe r templates pages use. This syntax information can be found in the WebShop Template Instructions section.
Below is a sample product template for the 4mb.html example used above.
<html> <head> <title>Memory Store WebShop: 4MB SIMM</title> </head> <body> <center> <h1>Memory Store WebShop: 4MB SIMM</h1> </center> 4MB SIMMs is the cheapest solution for upgrading your computer to contain a little more RAM. Our prices cannot be beat. For as low as $35 per 4MB of memory, you can get a faster more efficient machine.<p> <li><!--purchase: 4mb-->Purchase 4MB SIMM<!--/purchase--> </body></html>
WebShop also allows you to use a tax table for different states. For any states which you may need to apply Sales Tax for, simple add them to a tax table file (commonly named taxes.txt). Your tax table might look like:
CO:6.25 LA:8.5 NY:5
This would then add a 6.25% sales tax to anyone who lives in Colorado, 8.5% to anyone in Louisiana and 5% for anyone in New York. This does, however, only work if the user specifies the state in which they live.
WebShop allows you to set up a shipping table, which can be used to calculate the shipping price of products based on the amount of money a shopper spends at your site and what type of shipping servuce they wish to use. This is to reflect the fact that many places charge shipping, not by the product you buy, but by how much money the shopper spends. You can also specify a percent of the purchase to be charged as the shipping price. For instance, the memory store decides to take the shipping prices out of their product_info database (by setting the values to 0) and instead, on anything from $0 - $250 charge $5 shipping and handling, from $250 - $500 charge $10 shipping and handling and on anything over 500 charge 7% of the sub total for U.S. Postal Service Delivery. For Federal Express, their charge is 15% of the price of the product. Their shipping table would then look like:
USPS:0:250:5 USPS:250:500:10 USPS:500:10000000:7% FedEx:0:10000000:15%
As you can see, we specified a really large limit for the 7% & 15% values. This is because WebShop needs an upper limit and most likely no one will exceed $10,000,000 in purchases from the memory store. :-) Then save this file and set up the $SHIPPING_TABLE variable.
Now, you will need to edit your Review Template and include something like:
What type of shipping do you wish to use?
<input type=radio name="shipping_type" value="USPS"> U.S. Postal Service or <input type=radio name="shipping_type" value="FedEx"> Federal Express
Which will look like:
What type of shipping do you wish to use?
U.S. Postal Service or Federal Express
WebShop also supports a pseudo-validation of credit cards. It will not guarauntee a good card, however it can dis-prove obviously bad credit card numbers. It can check Visa, Mastercard and American Express. To use this, add something like the following to your Invoice Template:
If paying with Credit Card:
Pay with: <input type=checkbox name="cc_verify" value="YES"> Credit Card
<input type=checkbox name="pay_check" value="YES"> Check
Card Number: <input type=text name="cc" size=20>
Expiration Date (MM/YY): <input type=text name="cc_exp_date" size=6>
Card Type: <select name="cc_type">
<option value="MC">Mastercard
<option value="VS">Visa
<option value="AX">American Express
</select>
Which will look like:
Pay with: Credit Card
Check
If paying with Credit Card:
Card Number:
Expiration Date (MM/YY):
Card Type:
The field names cc_verify, cc, cc_exp_date and cc_type must appear exactly as shown. For validation, cc_verify must be set to 'YES'. cc must contain the credit card number, cc_exp_date must contain the credit card expiration date and cc_type must be 'MC' (mastercard), 'VS' (visa) or 'AX' (american express).
You can change the name of the check field to anything you wish. Aso, be sure to rpint these values out in your templates by using markers like: <<cc>> to get the credit card to appear, etc...
The only templates left to create for your WebShop web pages are the Review, Invoice and Final template Pages. In each of these HTML pages, if you include <<purchase_table>> in your HTML source, a table will be shown to the user (using <pr e> tags) that indicates which items they have selected to buy, the total, and other information. Below are samples of each of these pages:
<html> <head> <title>Memory Store WebShop: Review Order</title> </head> <body> <center> <h1>Memory Store WebShop: Review Order</h1> </center> Below is a copy of your purchases so far. You can <!--link: intro-->Continue Shopping<!--/link--><p> <<purchase_table>> <input type=submit value="Show Invoice"> <input type=reset> </form> <!--link: intro-->Back to Main Shopping Page<!--/link--> </body></html>
There are several things to notice about this template. By default, WebShop sets up the review page, so that if the user clicks on a submit button you create directly after the purchase table, it will take them to the invoice. In other words, it sets up the form the invoice page will need to use and then allows you to declare the submit and reset fields and close the form. You MUST close the form if you plan on using any other template markers below the form on that page, or it can mess up the s cript.
<html> <head> <title>Memory Store WebShop: Invoice</title> </head> <body> <center> <h1>Memory Store WebShop: Invoice</h1> </center> Below is a copy of your purchases so far. Fill out all of the information in the form below if you wish to purchase these products. Otherwise, you can <!--review: purchase-->Review Your Purchases<!--/link--><p> <<purchase_table>> Name: <input type=text name="name"><br> E-Mail: <input type=text name="email"><br> Street Address: <input type=text name="address"><br> City: <input type=text name="city"><br> State: <input type=text name="state"><br> Zip: <input type=text name="zip"><br> Credit Card: <input type=text name="cc"><br> <input type=submit value="Purchase Items"> <input type=reset> </form> <!--link: intro-->Back to Main Shopping Page<!--/link--> </body></html>
From here, you will notice a couple of things different about this template from the review template. The first noticeable difference is the fact that we have added a bunch of new form fields. You can enter as many input boxes, textareas, checkboxes, ra dio buttons or anything else as you like into your form. Taking the example above, these form fields can then be referenced in the e-mail invoice templates, the reply mail templates and final template pages with <<name>>, <<email>> ;, <<address>>, etc...
<html> <head> <title>Memory Store WebShop: Purchase Accepted</title> </head> <body> <center> <h1>Memory Store WebShop: Purchase Accepted</h1> </center> Thanks for purchasing items at the WebShop. Below is a summary.<p> <pre> <<purchase_table>> <<name>> <<email>> <<address>> <<city>>, <<state>> <<zip>> <<cc>> </pre> <!--link: intro-->Back to Main Shopping Page<!--/link--> </body></html>
From here, you will notice a couple of things different about this template from the invoice template. The first noticeable difference is the fact that we have added a bunch of new form field template markers. You will also notice that <pre> tags surround the purchase table. In the previous examples, the pre tags have been automatically added, however they are left out of the purchase_table this time so that it will correctly format in your e-mail messages. Simply add the pre tags to the page as shown above.
| Main File Paths &
Locations
| ||||||||||||
| Template Locations
| ||||||||||||
| WebShop Options
| ||||||||||||
| Mailing Order Information
| ||||||||||||
| Mailing Reply Information
|
$DATABASE = "/home/~username/public_html/WebShop/database.txt";
You must also make sure that this file is chmoded correctly.
$INTRO_HTML = "/home/~username/public_html/WebShop/intro.html";
$BASE_PRODUCT_PATH = "/home/~username/public_html/WebShop/products/";
$PRODUCT_INFO = "/home/~username/public_html/WebShop/products.txt";
$TAX_TABLE = "/home/~username/public_html/WebShop/taxes.txt";
$TAX_TABLE = "/home/~username/public_html/WebShop/shipping.txt";
$REVIEW_TEMPLATE = "/home/~username/public_html/WebShop/templates/review.html";
$INVOICE_TEMPLATE = "/home/~username/public_html/WebShop/templates/invoice.html";
$FINAL_TEMPLATE = "/home/~username/public_html/WebShop/templates/final.html";
$EMAIL_TEMPLATE = "/home/~username/public_html/WebShop/templates/email.txt";
Make sure you read more information about defining who to send the email message to in the Mailing Order Information section.
Here is an example of what a possible email template would contain, from the examples used in the explanations above.
<<purchase_table>>
<<name>>
<<email>>
<<address>>
<<city>>, <<state>> <<zip>>
<<cc>>
As you can see it is just a simple way of creating a custom look and being able to include and form fields you may have asked the user to fill in.
$REPLY_TEMPLATE = "/home/~username/public_html/WebShop/templates/reply.txt";
$MAX_MINUTES = "180";
$ORDER_TO = 'user@host.xxx';
Remember that if you use double quotes around the email address you will need to comment out the @ sign such as:
$ORDER_TO = "user\@host.xxx";
$ORDER_SUBJECT = "WebShop Order";
$CC_ORDER = 'user2@host.xxx,user3@host.xxx';
$REPLY_FROM = 'user@host.xxx';
$REPLY_SUBJECT = "Thanks For Ordering at WebShop!";
Last Updated: 13 May 2001
Copyright © by Esosoft Corporation 1996-2001
All Rights Reserved.
http://www.esosoft.net