LOGIN NAME:

PASSWORD:

:: Web Services :: XWebCheckOut :: Implementation Guides ::

Build Your Own XML/SOAP Web Service Based Shopping Cart
Add An Item To The Basket

The procedures in this implementation guide require that you have some knowledge of XML and ASP.NET web development with the Microsoft Visual Basic.NET development tool.

The steps in this "how-to" implementation guide are:

• Add a "Web Reference" to the XWebCheckOut Web Service
• Add a "Web Form" to the web application
• Write code in the "Codebehind" of the web form to add an item to the Basket by consuming the XWebCheckOut Web Service

To download the source code for this "how-to" implementation guide, as well as for additional hints and tips, please read our Final Notes.

Add a "Web Reference" to the XWebCheckOut Web Service

• In your web project, add a Web Reference to the XWebCheckOut web service. Here are 2 ways you can accomplish this:

  • Browse the Solution Explorer, right click on References and select Add Web Reference... from the drop down menu.
  • From the File Menu, select Project - Add Web Reference....

• The Add Web Reference pop-up window will open. In the URL textbox, enter the following URI:

  https://ws.xwebservices.com/XWebCheckOut/XWebCheckOut.asmx?wsdl

• Hit the Enter key or click the Go button located to the right of the URL textbox.
• Change the Web reference name to XWebCheckOut for easier reference.
• Click the Add Reference button to complete this step.

Add a "Web Form" to the Web Application

• In your web project, add a Web Form. This Web Form has no HTML and will add an item to the basket. Here are 2 ways you can accomplish this:

  • Browse the Solution Explorer, right click the name of your project, and select Add - Add Web Form....
  • From the File Menu, select Project - Add Web Form....
• Change the Name textbox in the Add New Item pop-up provided to order.aspx.

Write code in the "Codebehind" of the web form to add an item to the Basket by consuming the XWebCheckOut Web Service

Before we begin talking about code, we must lay out the sequence of events that take place during the checkout process. All websites that list products/services for sale feature a product/service page which contains the standard Add To Cart link. Because in Step 2 of this guide we created a page named "order.aspx", the Add To Cart link should reference the "order.aspx" page with the product id/sku of that particular product/service as a querystring parameter. For example:

order.aspx?pid=item238

When the website visitor clicks the link, our code must check to see if an Order ID has already been created for this particular visitor. We do this by checking whether or not a cookie with the Order ID has already been set. If it has not, we set one.

Dim strOrderID As String

' check for the order id
If Request.Cookies("OID") Is Nothing Then
  ' generate a new order id
  strOrderID = Replace(Guid.NewGuid.ToString, "-", "")

  ' generate a new order id cookie
  Dim objCookie As New HttpCookie("OID", strOrderID)
  Response.Cookies.Add(objCookie)

Else
  strOrderID = Request.Cookies("OID").Value

End If

Next, we use the LoadOrder SOAP method of the XWebCheckOut Web Service to retrieve the order record's details and store them into an XML DOM. Based on the documentation for the LoadOrder SOAP method, if the record has not already been created, the method still returns the <Order> root node; therefore, no extra code is required to account for new versus already existent records.

• Since the web service requires SOAP Headers for authentication purposes, we must first create a new instance of the class representing the SOAP Header and then populate the SOAP Header values:

  ' handle authentication
  Dim objAuth As New XWebCheckOut.AuthHeader
  objAuth.LoginName = "<my_login_name>"
  objAuth.Password = "<my_password>"

  NOTE***: Instead of hard-coding the LoginName and Password values, you may want to dynamically read them from the web.config file (LOGIN_NAME and PASSWORD must be added to the <AppSettings> section of the web.config file):

  objAuth.LoginName = System.Configuration.ConfigurationSettings.AppSettings("LOGIN_NAME")
  objAuth.Password = System.Configuration.ConfigurationSettings.AppSettings("PASSWORD")

• Next, we need to create a new instance of the proxy class and assign the SOAP Header object to the member variable of the proxy class representing the SOAP Header:

  ' create the XWebCheckOut web service proxy
  Dim objOrder As New XWebCheckOut.XWebCheckOut
  objOrder.AuthHeaderValue = objAuth

• We are now ready to call the method on the proxy class that communicates with the Web Service SOAP Method and returns the Order record we requested. Since the method returns the Order record in the form of an XML string, we load an XML DOM with it:

  ' load the xml string into a DOM
  Dim orderDOM As New System.Xml.XmlDocument
  orderDOM.LoadXml(objOrder.LoadOrder(strOrderID))

Since different websites have differently behaving Baskets, the XWebCheckOut web service provides great flexibility by storing the contents of a Basket as one 5000 character field. For this guide, we will store the contents as XML, consisting of a list of items the visitor has added to his/her basket as well as the order's total.

' create a new DOM for the Basket contents
Dim basketDOM As New System.Xml.XmlDocument

' check if Basket was previously created in the order DOM
If orderDOM.DocumentElement.SelectSingleNode("Basket") Is Nothing Then
  ' add root node
  basketDOM.AppendChild(basketDOM.CreateElement("Basket"))

  ' create the <Items> node
  Dim itemsNode As System.Xml.XmlNode =
  basketDOM.DocumentElement.AppendChild(basketDOM.CreateElement("Items"))

  ' create the <Item> node
  Dim itemNode As System.Xml.XmlNode =
     itemsNode.AppendChild(basketDOM.CreateElement("Item"))

  ' add attributes and elements to the <Item> node as required
  ' NOTE*** - we are only adding the Price element, but the item node should
  '                 consist of at least Item_ID, Name, Description, Quantity and Price.

  ' create the <Price> element and append to <Item> node
  Dim priceNode As System.Xml.XmlNode = basketDOM.CreateElement("Price")
  priceNode.InnerText = price_of_the_product i.e. 4.99
  itemNode.AppendChild(priceNode)

Else
  ' load the saved <Contents> into a DOM
  basketDOM.LoadXml(orderDOM.DocumentElement.
     SelectSingleNode("Basket/Contents").InnerText)

  ' check if this <Item> is being added a second time
  If basketDOM.DocumentElement.SelectSingleNode("Items/Item[@Item_ID =
  '" & product_id/sku i.e. item238 & "']") Is Nothing Then
    ' add attributes and elements to the <Item> node as required (same as above)

  Else
    ' increment the quantity by 1

  End If

End If

' add the <Total> element using XPathNavigator, XPathExpression
Dim xpathNav As System.Xml.XPath.XPathNavigator =
   basketDOM.CreateNavigator
Dim xpathExpression As System.Xml.XPath.XPathExpression =
   xpathNav.Compile("sum(Basket/Items/Item/Price)")
Dim totalNode As System.Xml.XmlNode = basketDOM.CreateElement("Total")
totalNode.InnerText = xpathNav.Evaluate(xpathExpression)
basketDOM.DocumentElement.AppendChild(totalNode)

For our last step, we consume the ProcessOrder SOAP method to store the Basket's contents.

' recreate the order DOM for data manipulation
orderDOM = New System.Xml.XmlDocument
orderDOM.AppendChild(orderDOM.CreateElement("Order"))

' add the Order_ID attribute
Dim oidAttribute As System.Xml.XmlAttribute =
   orderDOM.CreateAttribute("Order_ID")
oidAttribute.InnerText = strOrderID
orderDOM.DocumentElement.Attributes.Append(oidAttribute)

' create the <Basket> node
Dim basketNode As System.Xml.XmlNode =
orderDOM.DocumentElement.AppendChild(orderDOM.CreateElement("Basket"))

' add the <Contents> node
Dim contentsNode As System.Xml.XmlNode =
   orderDOM.CreateElement("Contents")
contentsNode.InnerText = basketDOM.DocumentElement.OuterXML basketNode.AppendChild(contentsNode)

' call the ProcessOrder SOAP method
Dim strResult As String =
   objOrder.ProcessOrder(orderDOM.DocumentElement.OuterXml)
If strResult <> "" Then Throw New Exception(strResult)

Final Notes

The source code for this "how-to" implementation guide can be downloaded by clicking the link below (zip file, contains the source code for all "how-to" implementation guides for the XWebCheckOut Web Service)

XWebCheckOutClient.zip

A non-persistent cookie was used to keep track of the Order ID - therefore, when the user closes the browser, the association of the basket with that particular visitor will be lost. If you would like to offer a "save basket" feature, simply create a persistent cookie by setting its expiration date to 1 year from today.

We recreated the orderDOM object instead of using the one we may have already had because we wanted to show how each node of the Order record (i.e. Basket, Shipping, Billing, etc) can be handled independently of the others.

It's always good practice to implement a Try...Catch... error handling technique to handle some or all possible errors that may occur while the code is executing. We strongly recommend that you implement such a technique.