ProductCart 4 Developer's Corner

Probably the most heavily requested new feature in ProductCart v4, One Page Checkout (OPC) represents an entire re-design of the checkout process. It was redesigned from the bottom up and incorporates years of customer feedback with tried and proven checkout features.

The first thing you will notice, as a developer, is that OPC makes extensive use of AJAX.

AJAX allows the entire checkout process to conclude on the same page where it begins (except for the page on which payment information is entered when a payment gateway is used), effectively reducing drop-offs for your clients.

Now, you may have some concerns that the additional technology will complicate your ability to modify the code. This One Page Checkout (OPC) overview aims to dispel your worries and demonstrate how the new design is easier to modify than ever before.

As you review the new file set you will notice that several of the files you have become familiar with no longer exist (new installations) or are no longer in use (existing stores that upgraded to v4). A complete list of those files is below.

Removed Files (compared to v3.x):

• pc/chooseShpmnt.asp
• pc/ggg_GiftWrap.asp
• pc/OrderVerify.asp
• pc/tax.asp

Do not be discouraged if you had become familiar with that source code, as the code contained within these files still exist today. The code has been moved into a file prefixed with “opc_”, and that is where you will need to re-apply your customizations, if any had been made to the files listed above.

For example, the file “OrderVerify.asp” has become “opc_OrderVerify.asp”. This was done intentionally for a few reasons.

1. When you update to the latest version we will not overwrite your customized checkout files
2. All OPC files follow the same nomenclature and are therefore easy to find (except for the main OPC file, which is called “OnePageCheckout.asp”)

Now that you understand the file structure we will explain the checkout flow and the basic functionality of some of the key files.

• Where checkout starts
  Checkout still begins on “checkout.asp”. You will not need to update any links to the checkout process in your header or footer.
• Login vs. Checkout
  After the customer arrives on “checkout.asp” ProductCart determines if they are in fact checking out, or simply logging in (with no items in the cart).
• OnePageCheckout.asp
  If the customer is checking out they are redirected to the new checkout page called “onepagecheckout.asp”. “Onepagecheckout.asp” is now the key file in the checkout flow. One this page the customer can log into an existing account or select “guest checkout”.
• Panels
  Customers are then guided through 3 simple panels, as follows (see details below):
  1. Address
  2. Shipping Method
  3. Payment
• Features
  All of the features that were included in ProductCart 3, along with new features for ProductCart 4, are dispersed within the 3 panels. Among the new features:
  • Guest checkout
    ProductCart now fully supports a “guest checkout” mode. If the same customer checks out as a guest multiple times, ProductCart will ask whether they wish to consolidate their orders under the same account (and create a full customer account in the process).
  • Real-time, field-specific validation
  • Special Customer Fields can now be ordered
  • Gift wrapping improvements
    Gift wrapping selections are now elegantly presented in a modal window, can be ordered, and made active/inactive (e.g. you don't need to remove “Halloween” gift wrapping options, but rather just make them inactive).
  • “Nickname your order” and “Order comments” are now collapsible panels, taking up minimal real estate (they are collapsed by default).
  • Multiple Gift Certificates can now be redeemed together.

The address panel is where the customer saves their billing and shipping address, or load a previously saved shipping address. Special Customer Fields and other information is presented in this panel as well.

If required for the order, the shipping panel will load all available shipping options. All real-time and custom shipping options are available.

Within the payment panel a customer can enter discounts or coupons, redeem reward points (if active), and save payment information. If the customer is new they may optionally save a password to create a customer account.

It is important to note that only offline payment methods are available in the payment panel. If the customer selects a real-time payment option they will still be directed to a separate payment gateway page. For technical reasons, we decided not to consolidate all payment gateway pages onto the OnePageCheckout page for now.

OPC introduces a new feature called “Guest Checkout”. So it is important for developers to understand how customers are handled during a shopping session. There are now three customer statuses, which are unrelated to customer categories (e.g. wholesale).

A field called “pcCust_Guest” in the “Customers” table of the database holds the customer status. The status is also set to a session called “session(“CustomerGuest”)” when the customer logs in, or creates a new account.

session(“CustomerGuest”) can have the following numeric values (0,1,2), as outlined below:

• 0: Registered Customer - Anyone who chooses “Guest Checkout” and does save the optional password has a registered status. This customer can login to view account history and order status. They also have full access to features, such as reward points.
• 1: Guest with no password - Anyone who chooses “Guest Checkout” and does NOT save the optional password has a guest status. A guest can check their order status with their email and Order Code.
• 2: Guest with password - This account type occurs when a registered customer creates a guest account, and saves an optional password. This type of customer is always prompted by the system to consolidate their accounts. They can not log in until they consolidate their accounts. A guest can check their order status with their email and Order Code.

Registered customers can log in and are handled in much the same way as ProductCart v3. The Guest Account is new in v4. A guest is created the moment a new customer saves their billing address. At this point a new customer email is optionally sent to the store and customer. The new account will have a status of “1” as outlined in the section above. If this customer had previously saved a password they will be prompted to consolidate their accounts on the order confirmation page. A guest can also optionally add a password at any time. When a guest adds a password they are updated to a status of “0” or “2”. If they have not previously created an account they will be given the status of “0”, for registered customer. If they have already registered an account with the same email they will be given a status of “2”, and will be asked to consolidate with their main account.

As a developer you may have noticed that OPC does not do a standard Post-back (the page does not reload when you click buttons). That is because OPC makes use a AJAX to send information to the server and update the HTML displayed to the customer. At first the heavy use of AJAX may be a bit intimidating. The following sections aim to give you a solid technical overview of OPC.

ProductCart has adopted jQuery for v4. JQuery is a fast and concise JavaScript Library that simplifies HTML document traversing, event handling, animating, and Ajax interactions for rapid web development. You will find that the files necessary to run jQuery have been added to the file “inc_header.asp” and “inc_footer.asp”. JQuery is behind all of the AJAX used in ProductCart OPC.

You can find a complete review of jQuery AJAX here: http://docs.jquery.com/Ajax

We are not going to explain every detail about jQuery AJAX. This section is going to give you a basic overview about how ProductCart makes AJAX calls. Lets take a look at the “Continue” button used to save the “Billing Address”.

OnePageCheckout.asp:

<input type="image" name="BillingSubmit" id="BillingSubmit" src="images/sample/pc_button_update.gif" align="absmiddle" border="0">

As you view the code you find no form action and no JavaScript events attached to this button. You may be asking yourself how this works. How will I be able to customize the form?

The answer is… “easily”! Just open the file “onepagecheckoutJS.asp”. This is where you will find all of the event handlers. Simply search down the page for the id of the button you are working with, in this case “BillingSubmit”.

You will find the following code:

$('#BillingSubmit').click(function(){
...
if ($('#BillingForm').validate().form())
		{
			$.ajax({
				type: "POST",
				url: "opc_UpdBillAddr.asp",
				data: $('#BillingForm').formSerialize(),
				timeout: 5000,
				success: function(data, textStatus){	

In pseudo terms this code is doing the following:

1. If the form passes validation
2. Post the form to “opc_UpdBillAddr.asp”
3. If successful run the function

So to edit the form all you need to do is work with the file “OnePageCheckout.asp” (for UI), “onepagecheckoutJS.asp” (for Events), and “opc_UpdBillAddr.asp” (for server processing). You will follow the same process for customizing any section of OPC. After you get the hang of it we are certain you will find the new AJAX code more compartmentalized and easier to maintain.

In One Page Checkout the checking of fields as “Required” is controlled via file pc/onepagecheckoutJS.asp.

There are three special cases at the top of the file for zip code, US State codes & State/Province/County outside the US. To make the ZIP code/postal code a required field for a customer in that country add the COUNTRY code to these fields, comma separated with a trailing comma.

var CountriesRequireZipCode="US,"
var CountriesRequireStateCode="US,"
var CountriesRequireProvince=""

For example, to make the postal code a required field in the United Kingdom

• Find:

  var CountriesRequireZipCode="US,"

• Replace with:

  var CountriesRequireZipCode="US,GB,"

For most of the rest of the fields the test is determined in a section of code featuring a comment right above it, which indicates the related panel. For example:

	//*Validate Billing Form
	var validator1=$("#BillingForm").validate({
		rules: {
			billfname: "required",
			billlname: "required",
			billaddr: "required",

For example, in version 4.0 the phone number was not required in the storefront. To make it a required field

• Open “onepagecheckoutJS.asp”
• Replace:

  billcountry: "required",

• … with:

  billcountry: "required",
  billphone: "required",

• Replace:

  billcountry: {
                  required: "<%=dictLanguage.Item(Session("language")&"_opc_js_12")%>"
              },

• … with:

  billcountry: {
                  required: "<%=dictLanguage.Item(Session("language")&"_opc_js_12")%>"
              },
              billphone: {
                  required: "<%=dictLanguage.Item(Session("language")&"_opc_js_16")%>"
              },

The code has changed a bit in version 4.1. There, to make the phone number a required field:

In the meantime, here is the fix:

• Open “onepagecheckoutJS.asp”
• Locate:

  <%
  pcv_IsBillingPhoneReq = false
  %>

• Change to:

  <%
  pcv_IsBillingPhoneReq = true
  %>

See this article.

The order is first saved when the payment panel opens. At this stage all of the necessary elements to generate the order exist (e.g. customer, billing, shipping, tax, and ship method). The order will have an incomplete status and appear in the reports section. After payment is remitted the order status is updated accordingly.

The AJAX methods will not reveal an error to the customer. You will need to login to the control panel and review the error logs. Most AJAX errors will be recorded in the log files. We also recommend that you use the Firefox browser with the FireBug Add-On. You can view all of the AJAX calls with FireBug. FireBug has several tools for inspecting and tracing JavaScript.

Download FireBug: http://getfirebug.com/

If you have customized files that initiate the shopping cart session, you must modify those files as the lenght of the array has changed in ProductCart v4. There are now 45 items in the array from 35 items in ProductCart v3.

Specifically, the code to start a ProductCart session (which is contained in the file pc/pcStartSession.asp) in ProductCart v3 looked as follows:

'*******************************
' START ProductCart Session
'*******************************
if session("idcustomer")="" then
	Dim pcv_intFlagNoLocal
	pcv_intFlagNoLocal=Cint(0)
	session("idPCStore")= scID
	session("idCustomer")=Cint(0)
	session("customerCategory")=Cint(0)
	session("customerType")=Cint(0)
	session("idAffiliate")=Cint(1)     
	session("language")=Cstr("english")
	session("pcCartIndex")=Cint(0)	
	dim pcCartArray(100,35)
	session("pcCartSession")=pcCartArray    	
end if
if session("idPCStore")<>scID then
	session.Abandon()
	session("idPCStore")= scID
	session("idCustomer")=Cint(0)
	session("customerCategory")=Cint(0)
	session("customerType")=Cint(0)
	session("idAffiliate")=Cint(1)     
	session("language")=Cstr("english")
	session("pcCartIndex")=Cint(0)
	redim pcCartArray(100,35)
	session("pcCartSession")=pcCartArray    
end if
'*******************************
' END ProductCart Session
'*******************************

In ProductCart v4, it becomes:

'*******************************
' START ProductCart Session
'*******************************
HaveNewSession=0
if session("idcustomer")="" then
	Dim pcv_intFlagNoLocal
	pcv_intFlagNoLocal=Cint(0)
	session("idPCStore")= scID
	session("idCustomer")=Cint(0)
	session("customerCategory")=Cint(0)
	session("customerType")=Cint(0)
	session("ATBCustomer")= Cint(0)
	session("ATBPercentOff")= Cint(0)
	session("idAffiliate")=Cint(1)     
	session("language")=Cstr("english")
	session("pcCartIndex")=Cint(0)	
	dim pcCartArrayORG(100,45)
	session("pcCartSession")=pcCartArrayORG
	HaveNewSession=1
end if
if session("idPCStore")<>scID then
	session.Abandon()
	session("idPCStore")= scID
	session("idCustomer")=Cint(0)
	session("customerCategory")=Cint(0)
	session("customerType")=Cint(0)
	session("ATBCustomer")= Cint(0)
	session("ATBPercentOff")= Cint(0)
	session("idAffiliate")=Cint(1)     
	session("language")=Cstr("english")
	session("pcCartIndex")=Cint(0)
	redim pcCartArrayORG(100,45)
	session("pcCartSession")=pcCartArrayORG
	HaveNewSession=1
end if
pcCartArray=session("pcCartSession")
'*******************************
' END ProductCart Session
'*******************************

We strongly recommend that you simply include pc/pcStartSession.asp in your custom files to start a ProductCart shopping cart session. That way if the file is updated, you will not run into any issues.