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.

What's New in v2.5

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
 
modules
 
Crypt
 
RC5.pm
Mail
 
Sender.pm
nc.pl
servercheck.cgi

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>

Limit - Optional

The optional, upper limit on how many of a particular item the user may order during this session. Users should not be able to alter this value.

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    

Description - Required

A brief text description of the item. Resist the temptation to write a 200 word essay about the item and its qualities; save that for the catalog pages. At this point the description should be a just few simple words. For example: "Bowling shirt with small emblem"



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    

Price - Required
The amount to be paid for a particular item.

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    

Options (non cost changing) - Optional

This is anything that can be customized about the item that does not alter the base cost. If you are using an option that requires the user to input a text string, make sure that you place an upper limit on the input. You can have up to 21 options, as shown in the Name of Element column.

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>

Options (cost changing) - Optional

These are options that add or subtract from the item's base cost and require a special method of construction. In the value section of the HTML tag, you must use a "|" character to separate the text description that the user sees from the numeric value that changes the cost. As with non cost altering options, you can have up to 20 options. You may also wish to note on your page that the added or subtracted cost of the option will not be figured into the total cost until the user adds the item to his shopping cart.



Note: You may use non cost changing options with cost changing options as you see fit.


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
 
catalog_builder
 
globalbuttons.html
index.html
optbuttons.html
optfields.html
optvalues.html
prodbuttons.html
proddesc.html
prodid.html
prodlimit.html
prodprice.html
prodqty.html
cgi-bin (Full version only)
 
modules
 
Crypt
 
RC5.pm
Mail
 
Sender.pm
nc.pl
servercheck.cgi
gateways (Full version only)
 
2checkout
 
NC_2checkout.js
authnet_sim
 
NC_authnet.js
linkpoint
 
NC_linkpoint.js
nochex
 
NC_nochex.js
paybycheck
 
NC_paybycheck.js
paypal
 
NC_paypal.js
secpay
 
NC_secpay.js
callback.html
uk_switch_card
 
NC_switch_card.js
verisign
 
NC_verisign.js
worldpay
 
NC_worldpay.js
imgs
 
gateways (Full version only)
 
2checkout_logo.gif
authnet_logo.gif
nochex_logo.gif
paypal_logo.gif
secpay_logo.gif
verisign_logo.gif
wp_logo.gif
co01.gif
co02.gif
co03.gif
co04.gif
geo.gif
geo.swf
geo_logo.gif
NC_link_button.jpg
NC_link_button1.jpg
s01.gif
s02.gif
s03.gif
s04.gif
js
 
cvv2.gif
cvv2_amex.gif
NC_buildcredit.js
NC_buildform.js
NC_buildlogo.js
NC_debug.js
NC_detect.js
NC_finalbuttons.js
NC_formatting.js
NC_getshipping.js
NC_mini_viewcart.js
NC_mini_viewcart_plus.js
NC_orderoptions.js
NC_secure_setup.js
(Full version only)
NC_settings.js
NC_shipoptions.js
NC_viewcart.js
NebuCart.js
cart.html
cones.html
customer_data.html
formorder.html
gateway.html
geodes.html
index.html
NC_Field_List.txt
printorder.html
printverify.html
secure_formorder.html
secure_gateway.html
spheres.html
Whats_New.txt