The Interface
Quick Start Guide
Creating Pages
Opening and Editing Pages
Uploading and Managing Files
Menu Display System
Site Templates
Shopping Cart & eCommerce
Event Calendar
eNewsletter Module
Database Table Manager
Secure Users
Site Data Tables
Photo Album
Site Statistics
Blog Manager
Webmaster Menu
Custom Web Forms
Custom PHP Includes
Programming structure
Custom HTML and PHP within the Page Editor
Custom Shipping Include
Custom Gateway Included
Custom Invoice Include
Custom Template Include
Custom Detail Page Include
Resources for Help
Search Engine Optimization
Useful Web Resources
Default Style Sheet File
Built-In Javascript Functions
Frequently Asked Questions (FAQs)
Online Users Manual Search Manual for:  
Custom PHP Includes
Custom Shipping Include

As described before, the Shopping Cart module utilizes its own builder program to operate. Thus, like the page editor, it will process these includes as it encounters them in the checkout process.

It was recognized that shipping calculations vary so drastically from client to client, that their needed to be a way to customize shipping charges as quickly as possible. The included shipping calculations will cover 75%-80% of your client base but inevitably will not cover 100%.

As before, it is important first to understand the variable data that already exists within the system. Because the shopping cart system relies totally on session data, the entire shopping cart contents and sku data is already available to you when your shipping script is executed.

For this example, we are going to use the following scenario:
Your client is perfectly fine with charging shipping fees based on a per sku bases, however, our customer would like to add a base rate of $7.00 to all US Orders and a base rate of $25.50 for international orders. To complicate matters further, they would also like to offer an option for 2nd Day Express and Standard shipping for U.S. Residents only. The express shipping option would add an additional $22.50 to the total shipping charge.

Now, let’s discuss “where” in the flow of the checkout system this include will be executed so that we know the basis of how we must author this script. The include will be executed after we have gathered the customer’s personal information and just before we display the invoice for verification using the module script pgm-checkout.php in the /shopping directory. If you have tested the shopping cart at all you may have noticed that it display’s a “shipping” step on the checkout progress bar but skips this step when using any built in shipping calculations. Once we place our shipping include into the mix, we can actually stop on the shipping step.

For this example, we will actually stop our U.S. customers to give them shipping options, whereas there is no need to stop International customers because we’re simply adding a specific amount to their total shipping charge.

At this point we need to know what session variable data is available to us so that we can program for it.

TIP: Because of security reasons, not all variable data is listed, however, you could write a temporary script that parses through $HTTP_SESSION_DATA to display all available variables.

Available session variables from within the shipping include script (Notice each line item is separated by a semi-colon in the value field):

Variable Name
Value
Description
$CART_KEYID
1;34;50

Primary Key number found in the “cart_products” system database table.

(Useful if you wish to pull any additional product data from the data table to use during display of your shipping script)

$CART_SKUNO sku-one;sku-two
Each line item sku number for this order.
$CART_CATNO
cat-one;cat-two
Each line item catalog number for this order.
$CART_PRODNAME
My product Name; Widget Pro
The name of each line item product.
$CART_SUBCAT
Red;Blue
Sub category name for each line item (If available)
$CART_VARNAME Large;Small
Variant Name for each line item (If available)
$CART_UNITPRICE 12.00;19.95
The unit price of each line item
$CART_QTY 3;1 The quantity ordered of each line item
$CART_UNITSUBTOTAL 36.00;19.95 The current sub-total of each line item (qty*unitprice)

Once our customer has completed his/her personal information all of those variables are registered in our session. For this example we are concerned with their “ship to” country:

Variable Name
Value Description
$BCOUNTRY USA
Bill to Country
$SCOUNTRY Brazil
Ship to Country


Now, let’s write the script:

<?

#############################################################################
###
### Authored by: Kenny Hefner (Worldsites, SE)
### Based on “shipping_example.inc” provided with Soholaunch Pro Edition
###
### Note: $SHIPPING_TOTAL is the system variable that the Pro Edition uses in the
### next step to database and display the FINAL shipping total for this
### order.
###
#############################################################################


$tmp_prikey = split(";", $CART_KEYID); // Place cart PRIKEYs into array
$tmp_cnt = count($tmp_prikey); // How many line items are in cart?
$tmp_qty = split(";", $CART_QTY); // What is the qty ordered for each sku


$SHIPPING_TOTAL = ""; // Reset Shipping Total for the Moment

// -------------------------------------------------------------
// MOD STEP 1: Determine which ship field to extract data from
// In the “cart_products” table, we use SHIPA to hold the U.S.// Shipping Charge per sku and SHIPB to hold International
// Ship charge per sku
// -------------------------------------------------------------

if ($SCOUNTRY == "United States") {
$TMP_DAT = "PROD_SHIPA";
} else {
$TMP_DAT = "PROD_SHIPB";
}

// -------------------------------------------------------------

for ($sc=0;$sc<=$tmp_cnt;$sc++) {

$ship_price = ""; // Reset match calc vars. Even though they are temporary
$new_add = ""; // anything can happen to the math in a loop like this.

// Pull first line item's "SHIP PRICE (A/B)" value from products table
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$result = mysql_query("SELECT $TMP_DAT FROM cart_products WHERE
PRIKEY = '$tmp_prikey[$sc]'");
$TVAL = mysql_fetch_array($result);

// NOTICE THE MOD VAR IN PLACE OF "PROD_SHIPA“ ON NEXT LINE

$ship_price = $TVAL[$TMP_DAT]; // Multiply Individual shipping price by current sku qty
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

$new_add = $ship_price*$tmp_qty[$sc];

// Add calculation to shipping total

$SHIPPING_TOTAL = $SHIPPING_TOTAL + $new_add;

} // End $sc Loop


// At this point, this is your Current total straight from the sku calculation

$SHIPPING_TOTAL = $SHIPPING_TOTAL;
// ---------------------------------------------------------
// Step 3: If this is a US order; add a 7.00 base rate
// ---------------------------------------------------------

if ($SCOUNTRY == "United States") { $SHIPPING_TOTAL = $SHIPPING_TOTAL + 7.00; }

// ------------------------------------------------------------
// Step 4: If this is NOT US order; add a 25.50 base rate
// -------------------------------------------------------------

if ($SCOUNTRY != "United States") { $SHIPPING_TOTAL = $SHIPPING_TOTAL + 25.50; }

// --------------------------------------------------------------------
// At this point the Shipping Total has the base prices added to it...
// --------------------------------------------------------------------

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// In case user decides to "back up" and change selection, unregister the
// shipping variables currently in this session. Once the user commits,
// these vars will be re-registered, don't worry.
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

if (session_is_registered("SHIPPING_TOTAL")) {
session_unregister("SHIPPING_TOTAL");
}

if (session_is_registered("OVERNIGHT_CHARGE")) {
session_unregister("OVERNIGHT_CHARGE");
}

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// -------------------------------------------------------------------
// Step 5: If this is US order; offer overnight; otherwise don't
// -------------------------------------------------------------------

if ($SCOUNTRY == "United States") {

// If they have completed the form already; don't do else statement

if ($OVERNIGHT_CHARGE != "") {

$SHIPPING_TOTAL = $SHIPPING_TOTAL + $OVERNIGHT_CHARGE;

session_register("OVERNIGHT_CHARGE");
$OVERNIGHT_CHARGE == "";

} else {

// ----------------------------------------------------------
// DISPLAY CHECKOUT ROUTINE STEPS FOR REFERENCE BY CUSTOMER
// To display output and stop on shipping step, we want to
// fill the $THIS_DISPLAY variable with HTML data. This will// indicate to the “builder” program that we need to display
// HTML options here and stop.
// ----------------------------------------------------------

$THIS_DISPLAY .= "<TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0 WIDTH=100%
CLASS=text STYLE='border: 1px inset black;'>\n";
$THIS_DISPLAY .= "<TR>\n";


$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 1:<BR>Customer Sign-in\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 2:<BR>Billing & Shipping<BR>Information\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=BLACK>\n";
$THIS_DISPLAY .= "<B>Step 3:<BR>Shipping Options</B>\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 4:<BR>Verify Order<BR>Details\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 5:<BR>Make Payment\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "<TD ALIGN=LEFT VALIGN=TOP CLASS=smtext BGCOLOR=WHITE>
<FONT COLOR=#CCCCCC>\n";
$THIS_DISPLAY .= "Step 6:<BR>Print Final<BR>Invoice\n";
$THIS_DISPLAY .= "</TD>\n";

$THIS_DISPLAY .= "</TR></TABLE><BR>\n";

// ----------------------------------------------------------
// Post our form to “pgm-checkout.php” because this is the
// program module executing this include right now!
// ----------------------------------------------------------

$THIS_DISPLAY .= "<FORM METHOD=POST ACTION=\"pgm-checkout.php\">\n";

// These hidden vars MUST be in here for proper operation

$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN NAME=STEP VALUE=\"3\">\n";
$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN NAME=customer_active VALUE=\"Y\">\n";
$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN
NAME=customernumber VALUE=\"$customernumber\">\n";

$THIS_DISPLAY .= "<P ALIGN=CENTER CLASS=text><B>Your Current Shipping Charges:
$SHIPPING_TOTAL.<BR><BR></B>
Please select your delivery preference: \n";

$THIS_DISPLAY .= "<SELECT NAME=\"OVERNIGHT_CHARGE\" CLASS=text>\n";
$THIS_DISPLAY .= " <OPTION VALUE=\"0.00\">Standard (+0.00)</OPTION>\n";
$THIS_DISPLAY .= " <OPTION VALUE=\"22.50\">Overnight (+$22.50)</OPTION>\n";
$THIS_DISPLAY .= "</SELECT>\n";

$THIS_DISPLAY .= "<BR><BR><INPUT TYPE=IMAGE SRC=\"cont_checkout.gif\" WIDTH=106
HEIGHT=25 STYLE='CURSOR: HAND;'>\n";

$THIS_DISPLAY .= "</P></FORM>\n";

}

} // END United States Check

// Do NOT use exit; on these includes because it will bomb the processing


?>

A couple of things that you may have discovered in this script is that we are modifying a variable called $SHIPPING_TOTAL. This is the variable that will ultimately determine in the next step of the checkout process, what the total shipping charge will be for our customer. This is an example of how modification of system variables within includes can work to our advantage as well as be dangerous. Test your scripts very carefully before making this “live” to the public.

Another thing that becomes apparent is the use of the $THIS_DISPLAY variable. This variable is what the “builder” program for the shopping cart module uses to display html data to the screen. Throughout this script, if this variable remains empty, the system assumes there is no need to stop and wait for input. This is exactly the case with International orders in the include example supplied here.

It should be noted as well that any posting of data requires the inclusion of some hidden operation variables. This makes sure that when the pgm-checkout.php program module is accessed, that it returns directly to the include file for further processing.

$THIS_DISPLAY .= "<FORM METHOD=POST ACTION=\"pgm-checkout.php\">\n";

// These hidden vars MUST be in here for proper operation

$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN NAME=STEP VALUE=\"3\">\n";
$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN NAME=customer_active VALUE=\"Y\">\n";
$THIS_DISPLAY .= "<INPUT TYPE=HIDDEN
NAME=customernumber VALUE=\"$customernumber\">\n";