The basic setup: Order submission with a gateway.
Welcome to NebuCart
Thank you for choosing NebuCart, the JavaScript E-commerce Solution!
The following documentation is designed to get you online and selling your products
in the shortest possible time. When followed step by step, your implementation
of NebuCart will be fully operational.
Using This Manual
If followed step by step, this manual will allow you to
install and operate the NebuCart JavaScript Shopping Cart in a minimal amount
of time. It is designed to be as simple and no nonsense as possible so as to
facilitate installation of the basic demo cart. Once you have the demo cart
working on your site, modifying the pages or creating new catalog pages is an
easy process.
It is recommended that when setting up the cart, you keep a backup copy of the cart in case you need to restore a page or cart module.
PLEASE NOTE: This guide is for both the FREE and FULL versions of NebuCart and none of the cgi scripts are included in the FREE version.
Getting Started - Unpacking "the box"
The NebuCart Shopping Cart is packaged as a compressed zip file. If you are
using Windows XP, you can extract all the files through Windows Explorer. Otherwise,
use an unzipping tool like Winzip
(Windows) or StuffIt (Macintosh)
to extract all the files.
When you extract the files for the cart, be sure to extract them with directories intact. If you don't do this, all the files will be extracted into one directory as opposed to their predefined structure.
Once you have unzipped the cart files, you can test the cart immediately from
your desktop. To launch the cart, just open the index.html page in your browser
to begin testing. The cart is initially configured with a generic setup, and
will post all orders to a test page on the NebuCart site to show you what was
posted.
Once extracted to the directory of your choice, the files and
directory structure are in Appendix A.
Installing the CGI Scripts (FULL version only)
The first step in setting up your shopping cart is to ensure that the order
capture script is installed and working properly so it can archive the orders
you receive. If you are comfortable with editing and configuring simple CGI
scripts for use on your account, you should be able to configure the nc.pl script
with relative ease. If you are new to setting up scripts, please follow the
instructions step by step to ensure a proper installation.
If all else fails, the support forums are available for quick help, and registered
cart users get a free month of tech support.
How Order Capture Works
The bulk of NebuCart is client side, meaning that when the customer browses
your catalog, their browser downloads all the cart modules. When an item is
added to the cart, the cart is stored in cookies, so no real work is done on
the server side.
This changes, however, when the customer checks out. When the customer submits an order, all of the cart contents, including the billing and shipping data, is posted to the Order Capture Script on your server. The script records all of the data in an encrypted file on your server, then reacts based on its configuration settings.
|
The basic setup: Order submission with a gateway. |
There are two basic methods for capturing orders: order capture with a gateway, and order capture without a gateway. Each method is explained below:
Order Capture With Gateway
When a customer checks out, they will have the payment options for
the gateways you decide to use. The cart comes with several gateway modules
designed specifically for those gateways. When used on the checkout page, each
module formats the order data as required by that gateway and places it in a
hidden field named NC_Redirect. When the order is posted, the nc.pl script looks
to see if this field exists. If it does, it will use this field to post the
formatted order data to your gateway, effectively transferring your customer
from your site to the secure checkout area of that gateway.
When the customer is routed to the secure gateway, they can then enter their credit card or other payment info and complete the order. Typically, the gateway will email you, the merchant, and the customer a copy of the transaction.
Once you receive a payment notification, you can login to your order administration screen and see which orders are completed by comparing the Order ID with the ID that was passed to your gateway.
Order Capture Without Gateway
This is the simplest method of order capture. When a customer checks
out, their order will be posted to the nc.pl script where the order is recorded
in an encrypted format. Once that occurs, the script can display its default
thank you page, or route the customer to a page that is sitting either on your
site or somewhere else.
When you check your orders, you would need to process payment offline or some other method of settlement. Some merchants chose to take credit card data and process it offline, and some decide to call the customer for the card info after recording their order. However you process the orders is completely up to you.
Explanation of the CGI scripts
Step 1 - uploading
Using your FTP application of choice, upload all the files in the cgi-bin directory
to the directory on your server. Assuming that your server uses the typical
"cgi-bin" directory for holding your perl scripts, the file structure
for the cart scripts should look like this:
 |
cgi-bin | ||||||||||||||||||||
|
Step 2 - script permissions
Set the permissions on all the files you just uploaded to 755. For more information
in script permissions, consult the documentation provided by your host or the
help files in your FTP application. Basically, the script permissions allow
a user to execute the scripts via a web browser - and that's good.
Point your browser to the newly uploaded nc.pl script. If you are viewing a login screen, then you can skip to Step 6.
Step 3 - server settings
(linux/unix users account only)
Point your browser to the URL of the freshly uploaded servercheck.cgi script
(example: http://www.yoursite.com/cgi-bin/servercheck.cgi). You should now be
viewing a window that displays all of your account and server statistics listed.
From the menu of links at the top of the window, click the "Server Environment Variables" link and record the PATH variable. This will be used later for configuring your order capture script. The PATH variable should point to the location of the cgi-bin directory where the servercheck.cgi is running.
Next, click the "Mail Program" link and record the path to sendMail. This will be used if the order capture script will be configured to send an email receipt after capturing an order.
Step 3 - server settings
(windows accounts only)
From your host's help files, control panel, or support staff, you will need
to get the following information:
Step 4 - basic configuration
Open the nc.pl file in your text/script editor of choice. UltraEdit
or TextPad are both very
useful applications for editing scripts. To get the script running, we will
only make two edits, then test the script to ensure that it's running. Afterwards,
feel free to configure the rest of the script.
Step 5- testing the script
Upload the newly edited nc.pl script, then point your browser to the script.
You should now be viewing the NebuCart Order Administration screen. If not,
then there are a couple of things you may be viewing.
If you are seeing a 500 server error page (with or without an error listing report), then the script is misconfigured. It may be that there is a typo in the script due to editing, or the path to perl may be incorrect. Edit the file and check the path to perl - the first line of the script. Your host should be able to tell you the path to Perl. If the path to Perl is incorrect, change it and reload the script. Give it another try!
If you are looking at a screen that states the module directory path is invalid, then check the path to your module directory and verify that it is correct. You may also try setting moduleDirectory and dataDirectory to '.' and see if that works. That simply denotes that the path to use is the directory where the nc.pl is currently running.
Step 6 - fine tuning
Now that nc.pl is up and running, its time to configure it for your particular
setup. Below are some tips on setting up the nc.pl script for various ordering
scenarios:
Order Capture with no gateway
If you chose to take orders with this option, a customer will post their
order to the Order Capture Script, and once it has received the post, it can
do several things:
Below is an explanation of how to achieve each of these options:
Order Capture with gateway
If you chose to take orders with this option, a customer will post their
order to the Order Capture Script, and be routed to the gateway processor for
final checkout. While you can configure the script to email you the order at
this time, it is not suggested. This is because until the customer completes
the transaction at the gateway, the order is still in a pending status. Emailing
the customer a copy of the order before it is completed might lead to some confusion,
and gateways usually send a transaction receipt anyway. However, you can still
set up the options below:
Below is an explanation of how to achieve each of these options:
Cart Setup
How NebuCart Works
Now that you have the back end of the cart installed and ready to receive orders,
we'll begin integrating the cart into your site design. Before we begin doing
that, it's important to understand how the client side of the cart works.
Like any e-commerce system, the idea is to get the customer connected to your products as quickly as possible. Once they add items to their cart and are ready to checkout, you want to make the process as quick and easy as possible. NebuCart accomplishes this by distilling the checkout process down to as few steps as poissble and grouping related information and forms to reduce customer confusion. Below is an example of a typical purchasing process:
Step 1 - catalog browsing
Here we see the catalog page of the NebuCart Demo. The Catalog pages can use any layout you desire to best compliment your site and enhance the customer's visit. After selecting an item of interest, the customer would select a quantity of the item desired and add the item to their cart. There are several options for quantity selection and adding an item to the cart. Full instructions on this are available in the Catalog Setup section.
Step 2 - viewing the cart
Once an item is added to the cart, the customer will be taken to the cart page. This page displays the items in the cart, quantities, options, price, and running total. At this point, the customer can update quantities, continue shopping, checkout, or delete the entire cart. For the purpose of the example, we'll assume the customer decided to checkout.
Step 3 - billing and shipping information
The first step in checking out is having the customer enter their billing and shipping information so that the order can be delivered. Based on your configuration of the cart, you can offer an alternate shipping address option. If the customer has been to your store before, their information will be retained in cookies for quick population of their data. This saves the customer time during the checkout process.
Step 4 - checkout method selection
A little further down the page on the billing/shipping information page, the customer is presented with their checkout methods. NebuCart can support a printable form option as well as four other checkout methods that can handle form posts. Two of these options can be secured if you have access to a secure server. If you have shipping options available, the customer can select their preferred shipping method at this time.
Typically, merchants have a single credit card processor, but there have been instances where the merchant offers checkout by multiple methods. For instance, a merchant may offer checkout by PayPal and AuthorizeNet, as well as a printable form. If the customer has a PayPal account, they may chose that method of checkout.
Step 5 - order review and submit
Once the customer has chosen his or her method of checkout, they are routed to a page allowing them to review and submit their order. On this page, they get the final tally of taxes, shipping, and discounts for the order before completing the transaction.
Based on your configuration of the cart, they may be able to add additional comments, and typically their credit card information for order processing.
Step 6 - order completion
When the customer clicks the button to submit the order, all of the order information gets posted to the script that has been designated to handle the post. For our example, the posting option was the cart test page on the NebuCart site. However, the Order Capture script would usually handle the post, or you may have a custom solution to complete the order.
Catalog Pages
Setting up a page for use with NebuCart is relatively easy. It involves including
the javascript modules required for the cart to operate, and including any items
inside a specially named form tag. Below is the minimum HTML required for a
catalog page:
<html>
<head>
<!-- include the debug module -->
<script language=javascript src="path/to/your/js/NC_debug.js"></script>
<!-- include the settings module -->
<script language=javascript src="path/to/your/js/NC_settings.js"></script>
<!-- include the cart engine module -->
<script language=javascript src="path/to/your/js/NebuCart.js"></script>
<!-- include the formatting module -->
<script language=javascript src="path/to/your/js/NC_formatting.js"></script>
</head>
<body>
<form name=NC_form>
... all your items go inside this form...
</form>
</body>
</html>
The text "path/to/your/js" should be replaced with the full URL or relative path to where you have the scripts installed on your site. This formatting is all that's required to make a page NebuCart enabled. However, a catalog page isn't much good without products, so let's put some items on that page, shall we?
Products
Product pages can be created dynamically by an ASP, PHP, CGI, or some
other server based script, or they may be static. There is no limit to the number
of catalog pages or items that NebuCart can handle.
There are six main properties that each product may have:
To create an item that can be added to your cart, a product must have the product ID/quantity field, as well as the price and description. All other fields are optional.
The following tables will show you what options are available for displaying and storing each of these values on your pages. For each product property, almost every form field type may be used, but some field types should not be used with all properties. For instance, a product's price should not be editable by the customer, so it is recommended that you only use a hidden field for this property.
ID/Quantity - Required
This is used by the customer to select / enter how many of a particular
item he or she wants. This value can be any alphanumeric value that does not
start with a number and does not contain a period.
| Available Input Types | Name of Element | Acceptable Range | Looks Like | Example Code |
| Text | itemID (where itemID is the ID/code for your product) |
Any value greater than zero | <input type="text" name="itemID" size=6 value="1"> | |
| Hidden | <input type="hidden" name="itemID" value="1"> | |||
| Radio Button |
1 2 3 |
<input type="radio" name="itemID" value="1">
1 <input type="radio" name="itemID" value="2"> 2 <input type="radio" name="itemID" value="3"> 3 |
||
| Check Box | ||||
| Text Area | <textarea name="itemID" cols="20" rows="2"
maxlength="10" wrap="virtual"> </textarea> (text areas are used more for bulk text input. Usage is not recommended) |
|||
| Select | <select name="itemID"> <option value=1>1 </option> <option value=2>2</option> <option value=3>3</option> </select> |
| Available Input Types | Name of Element | Acceptable Range | Looks Like | Example Code |
| Text | itemID_limit (where itemID is the ID/code for your product) |
Any number greater than zero | ||
| Hidden | <input type="hidden" name="itemID_limit" value="1"> | |||
| Radio Button | ||||
| Check Box | ||||
| Text Area | ||||
| Select |
| Available Input Types | Name of Element | Acceptable Range | Looks Like | Example Code |
| Text | itemID_desc (where itemID is the ID/code for your product) |
Any short, alphanumeric string. | ||
| Hidden | <input type="hidden" name="itemID_desc" value="Bowling shirt with small emblem"> | |||
| Radio Button | ||||
| Check Box | ||||
| Text Area | ||||
| Select |
| Available Input Types | Name of Element | Acceptable Range | Looks Like | Example Code |
| Text | itemID_price (where itemID is the ID/code for your product) |
Any number greater than zero | ||
| Hidden | <input type="hidden" name="itemID_price" value="15.30"> | |||
| Radio Button | ||||
| Check Box | ||||
| Text Area | ||||
| Select |
| Available Input Types | Name of Element | Acceptable Range | Looks Like | Example Code |
| Text | itemID_opt itemID_opt1 ... itemID_opt20 (where itemID is the ID/code for your product) |
Any value greater than zero | <input type="text" name="itemID_opt" size=6> | |
| Hidden | <input type="hidden" name="itemID_opt" value="1"> | |||
| Radio Button | <input type="radio" name="itemID_opt" value="1"> | |||
| Check Box | <input type="checkbox" name="itemID_opt" value="1"> | |||
| Text Area | <textarea name="itemID_opt" cols="20" rows="2" maxlength="10" wrap="virtual"></textarea> | |||
| Select | <select name="itemID_opt"> <option value="Option 1">Option 1</option> <option value="Option 2">Option 2</option> <option value="Option 3">Option 3</option> </select> |
|||
| Select Multiple | <select name="itemID_opt" size="3"
multiple> <option value="Option 1">Option 1</option> <option value="Option 2">Option 2</option> <option value="Option 3">Option 3</option> </select> |
| Available Input Types | Name of Element | Acceptable Range | Looks Like | Example Code |
| Text | itemID_opt itemID_opt1 ... itemID_opt20 (where itemID is the ID/code for your product) |
Text value|number equal or greater than zero. | ||
| Hidden | <input type="hidden" name="itemID_opt" value="Some text|3.00 "> | |||
| Radio Button |
Option 1 (adds $3.00) Option 2 (adds $5.00) |
<input type="radio" name="itemID_opt" value="Option
1|3.00">Option 1 (adds $3.00) <input type="radio" name="itemID_opt" value="Option 2|5.00">Option 2 (adds $5.00) |
||
| Check Box |
Option 1 (adds $3.00) Option 2(adds $5.00) |
<input type="checkbox" name="itemID_opt" value="Option
1|3.00">Option 1 (adds $3.00) <input type="checkbox" name="itemID_opt" value="Option 2|5.00">Option 2 (adds $5.00) |
||
| Text Area | ||||
| Select | <select name="itemID_opt"> <option value="Option 1 (add $3.00)|3.00">Option 1 (add $3.00)</option> <option value="Option 2(add $5.00)|5.00">Option 2 (add $5.00)</option> <option value="Option 3">Option 3 (no extra cost) </option> </select> |
|||
| Select Multiple | <select name="itemID_opt" size="3" multiple> <option value="Option 1 (add $3.00)|3.00">Option 1 (add $3.00)</option> <option value="Option 2(add $5.00)|5.00">Option 2 (add $5.00)</option> <option value="Option 3">Option 3 (no extra cost) </option> </select> |
Adding Products To The Cart
Once you've defined a product by it's properties and added it to a
catalog page, you'll want your customers to have the ability to add the item
to their cart. Items are added to the cart by making a call to the NebuCart
function AddItem and passing the Product ID to the function. Usually this is
done by using a hyperlink or button to add the item. Below are some ways to
accomplish this:
| Add Item Method | Looks Like | Example Code |
| HyperLink | Add to Cart | <a href="javascript:AddItem('itemID')">Add to Cart</a> where itemID is the ID/code for your product |
| Button | <input type="button" value="Add to Cart" onClick="AddItem('itemID')"> | |
| Image Button |  |
<a href="javascript:AddItem('itemID')"><img src="imgs/buy_button.gif" border="0"></a> |
Of course, how you add an item to the cart is only limited by your imagination. The only requirement is that you call the function AddItem and pass the product ID.
Catalog Page Example
With the guide above, it should be relatively easy to create the necessary
fields for your items. Below is an example of a page that contains one item
for sale with some basic options:
<html>
<head>
<!-- include the debug module -->
<script language=javascript src="path/to/your/js/NC_debug.js"></script>
<!-- include the settings module -->
<script language=javascript src="path/to/your/js/NC_settings.js"></script>
<!-- include the cart engine module -->
<script language=javascript src="path/to/your/js/NebuCart.js"></script>
<!-- include the formatting module -->
<script language=javascript src="path/to/your/js/NC_formatting.js"></script>
</head>
<body>
<form name=NC_form>
myItem is a very simple product. You should by it. At only $295.0, it's a deal!<br>
<!-- tem ID and quantity field -->
Qty: <input type="text" value="1" name="myItem" size="3"><br>
<!-- add to cart button -->
<input type="button" value="buy!" onClick="AddItem('myItem')"><br>
<!-- tem price field -->
<input type="hidden" value="295.00" name="myItem_price">
<!-- tem description field -->
<input type="hidden" value="A very simple product" name="myItem_desc">
<!-- tem option menu -->
<select name="myItem_opt">
<option value="xtra small (subtract $10)|-10">xtra small (subtract $10)</option>
<option value="small">small</option>
<option value="medium">medium</option>
<option value="large (add $50)|50">large (add $50)</option>
</select>
</form>
</body>
</html>
The resulting HTML would look like this:
| myItem is a very simple product. You should by it. At only $295.0, it's
a deal! Qty: |
The customer would be able to input a quantity and select a size for the item. You'll notice that the option drop down menu contains both normal and cost changing options. Clicking on the "buy!" button would add the product "myItem" tot he customer's shopping cart with the option selected. If they had selected a cost changing option, the price of the item would be altered by the amount defined in the drop down.
For more examples of item setup, refer to the sample GeoStore cart that is packaged with the zip files. Every catalog page shows a comments variation on the usage of all available form inputs.
Note: The text "path/to/your/js" should be replaced with the full URL or relative path to where you have the scripts installed on your site.
Appendix A
Cart File Structure
|
Folder where you extracted it | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
