The Order Process and Related Server Controls

This section summarizes the shopper experience using Ektron's eCommerce feature and describes the Cart and Checkout server controls used to implement the order process.

The order process

The Order Process

As a shopper, you can add items (physical goods, subscriptions, or soft goods) to your cart by clicking Add to Cart.
When you are ready to pay, click Checkout to begin the checkout process.
NOTE: Shoppers have the option of checking out using PayPal’s checkout system. Order information is exported, and you can use your PayPal account to fund the purchase. See Also: Payment Options.
When you return, you can log into your account and continue the checkout process. Your shipping and billing information appears.
Click Create Profile and Checkout and complete the Billing Page.
Click Next Page to create an account. After confirming the information, you can enter a different shipping address.
When you click Next Page, you can select the delivery method. If the cart contains a subscription or soft goods (such as downloadable software), this page is typically bypassed.
On the Review Page, you can modify the order by clicking Edit your cart. Otherwise, move forward to the Payment options page.

Specify payment information and submit the order.

An order invoice page displays to confirm the order. If the order was for a subscription or downloadable software, additional information appears.

Cart server control

Cart Server Control

The Cart server control lets a customer (site visitor) select products to purchase; an online "shopping basket." Products are added to the cart when the customer select them.

A customer typically reaches the Cart server control from a product description or list page. A product description page contains a Product Server Control. Product list pages contain server controls that create a list of products, such as ProductList, ProductSearch or Recommendation controls. These controls contain a button or link that allows a customer to add the product to the cart.

You could also create a link to the cart from a master page or menu that lets customers view their cart. This link lets a customer navigate directly to the cart when they arrive at your site.

Cart server control areas

Cart Server Control Areas

The Cart server control consists of 2 major areas. The top part (My Cart) represents the cart with which the customer is currently working. The bottom (My Saved Carts) represents a visitor’s saved carts. Saved cart information appears only when a customer is logged in. See Also: Creating a New Cart.

The My Cart area displays the Item, SKU, Quantity, List Price, Sale Price, Subtotal and Total. From this cart, a customer can remove items, update the quantity and subtotal information, apply coupons and check out. The customer can also choose to continue shopping or empty the cart.

The My Saved Cart area contains a list of carts the customer has saved and are awaiting checkout. This allows the customer to select products and save them for future purchase. This area contains:

the name of each cart
the last time it was updated
how many items in each cart
the subtotal of each cart
options to

delete a saved cart

create a new cart

continue shopping

Clicking a saved cart makes it the current cart, and displays its products in the Your Cart area. A customer can then proceed to check out.

Flow of the cart server control

Flow of the Cart Server Control

A customer typically arrives at this control by clicking Add to Cart in the Product, ProductList, ProductSearch or Recommendation server controls.

Below is an image depicting the flow of the Cart server control.

Working with a cart

Working with a Cart

This section explains how a logged-in customer would use the Cart server control. The following figure helps you locate key features of the Cart.

Create New Cart button.
Item name link.
Cart name edit button.
Item quantity field.
Delete item button.
Continue Shopping button.
Apply coupon button.
Empty cart button.
Checkout button.
Delete cart button.

Adding an item to a cart

Adding an Item to a Cart

Items are added to a cart when a customer clicks Add to Cart in the following server controls.

Product
ProductList
ProductSearch
Recommendation

When Add to Cart is clicked, the item is appended to the current cart’s list of items. If the customer does not have a cart, one is created.

Creating a new cart

Creating a New Cart

A customer automatically creates a new cart the first time a product is added to it. If needed, a customer can create multiple carts while using the Cart server control. This allows for the grouping of products being purchased. For example:

customers create carts based on concepts, such as, Son’s Birthday or Item Type.
customers use separate payment types. For example, a customer places some products on one credit card and the rest on another. By having 2 carts, a customer can proceed with 2 separate checkouts.
customer needs to prioritize purchases. For example, a customer wants to purchase certain products, but cannot afford them right now. The customer can add these products to a separate cart, then continue to purchase affordable products now. This helps customers remember purchases they want to make, driving additional sales for your site.

To create a new cart:

Click Create New Cart in the Saved Cart area. The button is replaced with a text box.
Enter the name of the new cart in the text box.
Click OK.

When the customer clicks OK, the cart is added to the list of Saved Carts and becomes the active cart. A customer can then click Continue Shopping to select products to add to the new cart.

Displaying an item's information

Displaying an Item’s Information

In the Cart server control, a product’s title is a link. When clicked, it takes you to the product’s detail page. To navigate back to the cart, click your browser's Back button.

By default, the server control uses the product’s QuickLink information to provide a path to the product. You can override this functionality by adding a new path to the TemplateProduct property.

Assigning or changing the name of the cart

Assigning or Changing the Name of the Cart

Assigning a name to a cart makes it easier for customers to identify a cart in their saved cart list. A customer can assign or change the name of a cart by clicking Edit () next to the cart’s name.

When clicked, the button and name are replaced with a text box that allows the customer to enter a new name for the cart.

Changing an item's quantity

Changing an Item’s Quantity

To change a product’s quantity, enter the new amount in the Quantity column’s textbox, located in the same row as the product you want to change. Next, click Update Subtotal. This recalculates the price of the product and updates the subtotal. The image below shows the Atrium Table quantity change to 3.

Removing an item from the cart

Removing an Item from the Cart

A customer can remove a product from the cart by clicking Remove From Cart () in the Quantity column. When the customer clicks the button, the product is removed from the cart, and the subtotal is updated.

Continuing to shop

Continuing to Shop

A customer can continue to shop by clicking Continue Shopping. This redirects the visitor to a template defined in the cart server control’s TemplateShopping property. For example, you might send the customer to a page containing a ProductList or ProductSearch server control. See Also: ProductList Server Control and Product Search Server Controls.

As a developer, you need to add the path to this page to the TemplateShopping property. If the page is in the same folder as the page that contains the Cart server control, just enter the page’s name.

Applying coupons

Applying Coupons

If coupons are defined in the Workarea and the EnableCoupons property is set to True, a customer can enter coupons to discount the purchase. How coupons affect the purchase is defined in the Workarea > Settings > Commerce > Catalog > Coupons. See Also: eCommerce Coupons

To apply a coupon, a customer clicks Apply Coupon.

The button area changes to text box where the customer can enter the Coupon Code. The customer then enters a code and clicks OK. Next , the discount appears above the Subtotal, and the customer can continue to shop, check out, view other carts, or delete the coupon by clicking Remove Coupon.

Emptying the current cart

Emptying the Current Cart

To remove all products from the current cart, a customer clicks Empty Cart. When clicked, a dialog box appears and the customer can click OK or Cancel.

Checking out

Checking Out

When a customer is satisfied that the cart contains all products they want, the quantity of each product is correct and all coupons have been applied, the customer can click Checkout. At that point, the customer is redirected to the page that hosts the Checkout server control. The path to the page is defined in the TemplateCheckout property. If the page containing the Checkout server control is in the same folder as the Cart server control, just enter the page name.

If a cart includes an item that is out of stock, the Checkout button is disabled (hidden).

Deleting a saved cart

Deleting a Saved Cart

A customer can delete a saved cart by clicking Delete Cart.

Cart server control properties

Cart Server Control Properties

The Cart server control has the following Ektron-specific properties. Native .NET properties such as font, height, width and border style are not described. For documentation of these properties, see Visual Studio^® help.

Authenticated (String)
Indicates if you are logged into the CMS Explorer and can use it to browse to content, collections, and so on. See Also: Browsing Your Ektron Site Using CMS Explorer.
CustomXml (Code-behind Only) (String)
Lets you inject custom XML into the generated XML before being processed by the XSLT. Enter a string of XML that you want to make available to the XSLT as follows:
```
<root><customXml>custom-xml-inserted-here</customXml></root>
```
See Also: Displaying Custom XML in Ektron’s Server Controls.
DisplayXslt (String)—If desired, enter a relative or absolute path to an Xslt that determines the display of the page. By default, the control uses Cart.xsl. This file is located in <siteroot>\Workarea\Xslt\Commerce.
IMPORTANT: If you specify an external file, do not store this file in the Workarea folder. If you store this file in the Workarea folder, the file will be lost when you upgrade.
DoInitFill (Boolean)—Controls when Fill occurs.
By default, Fill occurs during the Page_Init event. Set to false if you want to postpone the fill-action until later. In this case, Fill is automatically called during the Page Render event. You might do this if you need to set or change a property on the control in code-behind and have it render with your changes shown.
DynamicProductParameter (String)—The QueryString parameter name which is used to pass the product ID to the product details page. For example, if your QueryString parameter for products is ID, enter that in this property. Then, when customers clicks a product’s title, this parameter is passed with the product’s ID to the product details page.
EnableCoupons (Boolean)—Set to true to allow a customer to enter coupon codes for discounts. When set to false, the Apply Coupon button is hidden. See Also: Applying Coupons.
- True—coupon entry is available. (Default value is True if this property is not set.)
- False—coupon entry is not available.
See Also: eCommerce Coupons.
Hide (Boolean)—Used to hide the control in design time and run time.
- True—Hide the control
- False—Show the control
Language (Integer)—
Set a language for viewing content; shows results in design-time (in Visual Studio) and at run-time (in a browser).
LoadingImage (String)—The image to display while the cart is loading. The default is ajaxloader_circle_lg.gif. This file is located in siteroot\Workarea\images\application.
Stylesheet (String)—Specify the path to a style sheet for use with this server control. The location can be relative or absolute. Leave blank to use the default style sheet. The default is Cart.css. This file is located in: siteroot\Workarea\csslib\Commerce
IMPORTANT: If you want to edit this file, make a copy, change its name and move it outside of the Workarea folder. If you make changes to this file and do not move it out of the Workarea, this file and the changes will be lost when you upgrade.
SuppressWrapperTags (Boolean)—Suppresses the output of the span/div tags around the control. The default is False.
- True—Suppress wrap tags.
- False—Allow wrap tags.
TemplateCheckout (String)—The template that contains the Checkout server control. This is the page a customer is sent to when the customer clicks Checkout. If the template file is located in the same folder as the Web form containing this server control, just enter its name. The path can be relative or absolute. See Also: Checking Out.
TemplateProduct (String)—The template that contains the Product server control. This is the page a customer is sent to when the customer clicks the name of a product in his cart. This page provides details about the product.See Also: Displaying an Item’s Information.
When this property is left blank, the server control uses the Product’s QuickLink information.
If the template file is located in the same folder as the Web form containing this server control, just enter its name. The path can be relative or absolute. See Also: Displaying an Item’s Information.
TemplateShopping (String)—The URL to navigate to when the customer clicks Continue Shopping. This URL could lead to a template containing a ProductSearch or ProductList server control that would allow a customer to select additional products. See Also: Continuing to Shop.
For information the ProductSearch or ProductList server controls, see Product Search Server Controls or ProductList Server Control.

Checkout server control

Checkout Server Control

IMPORTANT: When using the Checkout server control, your Web site should have an SSL certificate installed. Set its IsSSLRequired property to True. This protects your customers’ payment information during transmission. Do not use a self-signed SSL certificate—obtain one from a trusted certificate authority.

The Checkout server control lets a customer navigate through the checkout process. This process includes:

adding billing and shipping information
selecting a shipping method
reviewing the order
submitting the order and credit card information
notification that checkout process is complete

Customers typically arrive at this server control by clicking Checkout on the Cart server control. They also might reach this server control from a Checkout link you create on your site.

The control provides a navigational aid that indicates the customer's step in the checkout process. At any point, the customer can move forward to the next step or back to a previous one. When appropriate, some steps do not appear. For example, if merchandise is not tangible, the shipping screen does not appear.

Logging in or setting up an account

Logging In or Setting Up an Account

The login portion of the Checkout server control accommodates these types of customers.

existing customers
customers who have not logged in before but who wish to create an account
customers who wish to make one-time only purchase and not set up an account

Existing customer's login

Existing Customers' Login

If an existing customer is not logged in when the customer reaches this server control, it prompts him to log in. Optionally, this screen could have a link that allows an existing user to recover his password. To enable this link, add a template path to the control's TemplateRecoverPassword property.

After a customer who previously purchased from this site logs in, billing and shipping information is retrieved and appear by default. The visitor can review and edit this information. However, Ektron does not store credit card numbers, so that information must be entered each time.

Customer's first time login

Customer's First Time Login

If a customer has not purchased from your site before and wants to set up an account, the customer clicks Create Profile and Checkout. On the new screen, the customer enters billing information including a password. After completing that screen, a membership user account is created, and the customer is logged in. The new user can then proceed through the checkout. The next time this visitor logs in, the customer is treated as an existing customer.

Guest account registration

Guest Account Registration

The Checkout server control provides a guest checkout feature (circled below) for customers who don't want to set up an account on your site. To enable this feature, set the AllowGuestcheckout property of the Checkout server control to true.

If a user clicks Checkout Without Profile, the customer proceeds to a version of the billing screen that does not ask for a password. The rest of the checkout is the same.

Although the customer can proceed through the checkout like other customers, if the customer wants to checkout in the future, the customer must re-enter billing and shipping information. Customers who use the guest checkout feature can view their orders using the Order List server control if its GuestOrderView property is set to true. See Also: OrderList Server Control

Checkout server control screens

Checkout Server Control Screens

The Checkout server control has several sections, each representing a portion of the checkout process.

Billing information

Billing Information

Prompts customers to enter or update billing information, including:

Name
Company (Optional)
Street Address, City, State, Postal Code, Country

NOTE: If a customer chooses a country other than the United States, no field validation is applied to the postal code by default. To apply country-specific postal code validation, see this Ektron, Inc. Knowledge Base article:http://dev.ektron.com/kb_article.aspx?id=26072.

Phone
email address (appears when a visitor is creating a new account or doing a guest checkout)
Password (appears when a visitor is creating a new account or doing a guest checkout)

Shipping information

Shipping Information

Add or edit shipping information. By default, it uses the billing address as the shipping address. From this screen, customers can:

add new addresses
edit or delete existing addresses
if more than one address is entered, pick address for current order
proceed to the next step or back to the previous page

When a logged-in customer adds a new address, it is stored with the account information in Ektron.

Shipping method

Shipping Method

Select the type of shipping for products. Shipping methods that appear are defined in the Workarea > Settings > Commerce > Shipping > Methods. See Also: Shipping Methods.

Review order

Review Order

Displays information about products being purchased: their price, shipping charges, discounts, and taxes. At this point, if customers want to modify their cart, they click Edit your cart. For example, a customer wants to apply a coupon to the cart. For this link to work properly, add the path to the template that contains the Cart server control to the Checkout server control’s TemplateCart property.

Submit order

Submit Order

On the Submit Order page, a customer enters payment information. The customer can pay by check, credit card, or PayPal, depending on what has been set up in the eCommerce Payment Options screen. When a customer enters the information, the customer clicks Submit. At that point, the charge is submitted to the payment gateway, and the order is posted in Ektron. See Also: Orders

Order complete

Order Complete

The Order Complete page displays a Thank You note, the order ID, and links to continue shopping or view an order’s history.

The Continue Shopping link appears when you add the path of a template that allows a customer to find products to the TemplateShopping property. For example, you send them to a template containing a ProductSearch or ProductList server control.

The Order History link appears when you add the path of a template containing the OrderList server control to the TemplateOrderHistory property.

Flow of the checkout server control

Flow of the Checkout Server Control

The following chart represents the options and processes of the Checkout Server Control.

Checkout server control properties

Checkout Server Control Properties

The following are Ektron-specific server control properties. You can find information about native .NET properties such as font, height, width and border style in Visual Studio^® help.

Authenticated (String)
Indicates if you are logged into the CMS Explorer and can use it to browse to content, collections, and so on. See Also: Browsing Your Ektron Site Using CMS Explorer.
CacheInterval (Double)
The number of seconds that the server control’s data is cached. The default is 0 (zero). For example, if you want to cache the data for 5 minutes, set to 300. See Also: Caching with Server Controls.
CurrentPhase (code-behind Only) (ControlPhase)
Reports or selects the current page (or phase) of the checkout control. This lets you customize the flow of the control. For example, if you only have one shipping option, you would skip the ShippingInfoEntry phase.
For an example of working with the CurrentPhase property in code-behind, download Ektron’s Developer Sample Site and view these files.
Siteroot/Developer/Commerce/CheckoutDemo_Advanced.aspx

Siteroot/Developer/Commerce/CheckoutDemo_Advanced.aspx.cs
Phases are listed in the order which they happen within the control.
- Login—allows existing users to log in. See Also: Logging In or Setting Up an Account
- BillingInfo—displays a customer’s billing information. See Also: Billing Information
- BillingInfoEntry—allows entry of a customer’s billing information. See Also: Billing Information.
- ShippingInfo— allows entry of a customer’s shipping information.
- ShippingInfoEntry—allows entry of a customer’s shipping information. See Also: Shipping Information
- ShippingMethodSelect—allows selection of the method of shipping. See Also: Shipping Method
- ReviewOrder— displays the current order’s details for review. See Also: Review Order
- SubmitOrder—lets customers add payment information. See Also: Submit Order
- Complete—displays completion message. See Also: Order Complete
- Error_EmptyBasket— used when a cart has no items and the customer somehow enters the control.
- Error_UnhandledException—occurs when there’s an error that the control cannot resolve.
CustomXml (code-behind Only) (String)
Lets you inject custom XML into the generated XML before being processed by the XSLT. Enter a string of XML that you want to make available to the XSLT as follows:
```
<root><customXml>custom-xml-inserted-here</customXml></root>
```
See Also: Displaying Custom XML in Ektron’s Server Controls.
DefaultCountryId (Integer)
The ID of the default country that appears in the Billing Address and Shipping Address. Set this to the country from which the majority of your customers make purchases. If a customer is from a different country, the customer can change it when editing the Billing or Shipping Address.
To find a country’s numeric ID, sign into the Ektron Workarea. Then go to Settings > Commerce > Configuration > Countries. The Numeric ID is in the left column of that screen.
DoInitFill (Boolean)
By default, Fill occurs during the Page_Init event. Set to false if you want to postpone the fill-action until later. In this case, Fill is automatically called during the Page Render event. You might do this if you need to set or change a property on the control in code-behind and have it render with your changes shown.
DynamicPhaseParameter (String)
The name of the parameter on the QueryString that identifies desired phase ID.
DisplayXslt (String)
If desired, enter a relative or absolute path to an Xslt that determines the display of the page. By default, the control uses Checkout.xsl. This file is located in siteroot\Workarea\Xslt\Commerce\Checkout\Standard
IMPORTANT: If you specify an external file, do not store this file in the Workarea folder. If you store this file in the Workarea folder, the file will be lost when you upgrade.
FriendlyErrorMessage (String)
The message that is shown to a customer when an unhandled error occurs. Details are sent to the event log. The default message is “We're sorry, an error occurred while processing your request. Please try again later...”
AllowGuestCheckout (Boolean)\
Set to true if you wish to allow the Guest Checkout feature. See Also: Guest Account Registration
Hide (Boolean)
Hides or displays the output of the control in design time and run time.
- True—Hide the control output.
- False—Display the control output.
IsSSLRequired (Boolean)
When set to True, switches to an SSL encrypted URL. For the SSL encryption to work, you must have an SSL certificate installed for your site. See Also: Configuring SSL. Information on SSL can be found at the following Web sites.
- http://www.tech-faq.com/understanding-ssl.shtml
- http://www.verisign.com/ssl/ssl-information-center/how-ssl-security-works/index.html
Installing and using an SSL is one of the most important things you can do to protect your customer’s credit card data.
NOTE: Ektron, Inc. is not associated with TechFAQ or VeriSign. However, both sites offer good explanations of Secure Sockets Layer.
Language (Integer)
Set a language for viewing the checkout control. This property shows results in design-time (in Visual Studio) and at run-time (in a browser).
LoadingImage (String)
The image to display while the control is fetching data. The default is siteroot\Workarea\images \application\ajax-loader_circle_lg.gif.
Stylesheet (String)
Specify the path to a style sheet for use with this server control. The location can be relative or absolute. Leave blank to use the default style sheet.
SuppressWrapperTag (Boolean)
Suppresses the output of the span/div tags around the control.
- True—Suppress wrap tags.
- False (default)—Allow wrap tags.
TemplateCart (String)
The URL path of the template that contains the Cart server control. The path can be relative or absolute.
When a path is entered, a link appears in the Review Order part of the process that allows a user to navigate to the template containing the Cart server control. See Also: Review Order and Cart Server Control
TemplateOrderHistory (String)
The URL path of the template that contains the OrderList server control. The path can be relative or absolute. When a path is entered, a link appears at the end of checkout process that allows a user to navigate to the template containing the OrderList server control. See Also: Order Complete and OrderList Server Control.
TemplateRecoverPassword (String)
The URL path of the template that helps a customer recover a password. The path can be relative or absolute. When a path is entered and a customer has not logged in, a link appears at the beginning of checkout process that allows him to navigate to a template containing information to recover his password. The Membership server control contains an option for recovering passwords. See Also: Logging In or Setting Up an Account and Membership Server Control
TemplateShopping (String)
The URL path of the template that allows the customer to continue shopping. If a path is entered, a link appears at the end of checkout that allows a user to navigate to a template that lets him continue shopping; for example, the template containing a ProductList or ProductSearch server control. See Also: Order Complete, ProductList Server Control and Product Search Server Controls

Adding a custom field to the checkout control

Adding a Custom Field to the Checkout Control

This example demonstrates how to add a custom field to the Checkout control's Billing Info entry screen.

Step1: Add a field to the XSL

Step1: Add a Field to the XSL

In the workarea/XSLT/Commerce/Checkout/ folder, look for the Checkout_BillingInfo.xsl file. In the file, locate EktronCheckout_BillingInfo_Company_. Under the bulleted list item for company, add the following:

<li class="EktronCheckout_Required EktronCheckout_SerializableContainer">
      <label class="EktronCheckout_Row_LeftContents">		
	  <xsl:attribute name="for">
           EktronCheckout_BillingInfo_CustomField_<xsl:value-of select="$ControlId"/>
          </xsl:attribute>
        <span class="EktronCheckout_RequiredSymbol">*</span>
        A custom field
      </label>
      <input class="EktronCheckout_Company EktronCheckout_Row_RightContents" >
         <xsl:attribute name="name">
           EktronCheckout_BillingInfo_CustomField_<xsl:value-of select="$ControlId"/>
         </xsl:attribute>
         <xsl:attribute name="id">
            EktronCheckout_BillingInfo_CustomField_<xsl:value-of select="$ControlId"/>
          </xsl:attribute>
         <xsl:attribute name="value">ABCXYZ</xsl:attribute>
      </input>
 </<li>

Important notes:

EktronCheckout_Required—Denotes that the field is required and will impose validation. EktronCheckout_NotRequired is also acceptable.
EktronCheckout_SerializableContainer—Tells the checkout control to process and include the field in this <li> tag with the callback.
EktronCheckout_BillingInfo_CustomField_ —The name of the field, where EktronCheckout_BillingInfo is replaced with param__ internally. The last portion, CustomField, is how the field will be referenced (see below).

Step2: Get the value of the field

Step2: Get the Value of the Field

In the codebehind of the page with the Checkout control, you need the following imports:

using Ektron.Cms.Controls;
using Ektron.Cms.Controls.ECommerce;
using Ektron.Cms.Controls.ECommerce.Checkout;

Next, place the following into the Page_Init method:

cmsCheckout.FilterAjaxCallback += this.HandleFilterAjaxCallback;

Then implement the HandleFilterAjaxCallback method:

protected void HandleFilterAjaxCallback(object sender, 
FilterAjaxCallbackEventArgs e)
{
     string callbackParameters = e.EventArgs;
     System.Collections.Specialized.NameValueCollection data =
Ektron.Cms.Common.EkFunctions.ConvertToNameValueCollection(callbackParameters, true);

      string customFieldValue = data["param__customfield"];
}

Upon completing the Billing Info screen, the data is returned as part of the EventArgs, with the prefix param__ (note the double underscore).

It can then be obtained directly by converting the string to a NameValueCollection (or other construct). Developers are free to call their own methods from here.