Get Started!

Using Ecommerce

How to use the Ecommerce DynAss

Canvas has a Net4orce.Canvas.General.Ecommerce assembly that contains all the logic required for an ecommerce site including the ablity to pass of to PayPal, WorldPay and other providers.

1 - Install

The Assembly can be installed via the Dynamic Assemblies page.

This adds the sections and generates the nessasary Pre Processors for the assembly.


2 - Update Default.aspx

Add using Net4orce.Canvas.General.Ecommerce; to the defaultaspx.cs

Make sure your defualt aspx for the site in herits from EcomPageBase.

Add the following to your ASPX to include the JavaScript for the basket pages

<%if( INC_BASKET_JS ){%>
  <script src="<%=BasketJSFile%>"></script>


Add the Following to your Default.aspx

<%/* Placeholder for ecommerce TX forms */%>
<asp:placeholder runat="server"

3 - Add a Data Item Type

Now you can create a DataType that will be sold, Kites in my example.

To enable the type to work with the ecommerce logic the following settings mush be set on the DataItem :


using Net4orce.Canvas.General.Ecommerce;
using Net4orce.Canvas.General.Ecommerce.Products;

Base Class


Remember to change the inherited class of the DataItem in the <T>-extend.cs C#.


4 - App App.cs

Add a static to your App.cs like this :

static KiteShopApp(){


  EcommerceApp.cOrderNoPrefix = "TX-";

  Net4orce.Canvas.General.Ecommerce.Gateway.Controller.CONFIRMED_ORDER_REF_FMT = "KT/00000";
  Net4orce.Canvas.General.Ecommerce.Gateway.Controller.Mode = Net4orce.Canvas.General

  // Register Class Maps



The Register Class Maps portion above creates class maps for the difference serializers.

PayPal Credentials

private static void setupPayPalCredentials(){

  var ctx = HttpContext.Current;
  var request = ctx.Request;

  Net4orce.Canvas.General.Ecommerce.Gateway.PayPal.Controller.Mode = "sandbox";
  Net4orce.Canvas.General.Ecommerce.Gateway.PayPal.Controller.Username = "USERNAME";
  Net4orce.Canvas.General.Ecommerce.Gateway.PayPal.Controller.Password = "PASSWORD";
  Net4orce.Canvas.General.Ecommerce.Gateway.PayPal.Controller.Signature = "SIGNATURE";

  // Set the schema
  Net4orce.Canvas.General.Ecommerce.Gateway.PayPal.Controller.Host = request.Url.Host;
  Net4orce.Canvas.General.Ecommerce.Gateway.PayPal.Controller.Schema = request.Url.Scheme + "://";


The PayPal credentials can be obtained via the PayPay Developer Accounts page. You must create a Merchant account, selecting the account & opening the "Profile" modal :

PayPal Credentials


WorldPay Credentials

private static void setupWorldPayCredentials(){

  var ctx = HttpContext.Current;
  var request = ctx.Request;

  Net4orce.Canvas.General.Ecommerce.Gateway.WorldPay.Controller.InstallationId = "INSTALL_ID";
  Net4orce.Canvas.General.Ecommerce.Gateway.WorldPay.Controller.InfoServletPassword = "SERVLET_PASSWORD";
  Net4orce.Canvas.General.Ecommerce.Gateway.WorldPay.Controller.PaymentResponsePassword = "RESPONSE_PASSWORD";

  // Set the schema 
  Net4orce.Canvas.General.Ecommerce.Gateway.WorldPay.Controller.Host = request.Url.Host;
  Net4orce.Canvas.General.Ecommerce.Gateway.WorldPay.Controller.Schema = request.Url.Scheme + "://";

  // Debug & Helpers

  //Net4orce.Canvas.General.Ecommerce.Gateway.WorldPay.Controller.CallBackRenderTime = 10;
  //Net4orce.Canvas.General.Ecommerce.Gateway.WorldPay.Controller.CallBackIncDebug = true;


The WorldPay Credentials are accessible via the WorlPay Dev settings page.


5 - Create some items

If you don't have already, create some dataitems for the new product type.


6 - List / View / Add To Basket

To support adding to basket there's an "Add Button" which can be rendered into any location via an PlaceHolder.

public PlaceHolder phAddBtn;
public AddButton oAddButton;

protected override void initialize()

  oKite = oDataItem as Kite;


private void render(){

private void renderAddToBasketBtn()
  // Create an instance of the button control
  oAddButton = LoadDynamicControl<AddButton>();

  // Assign the Product (Kite)
  oAddButton.oProduct = oKite;

  // Set visual information
  oAddButton.Text = "Add to Basket";
  oAddButton.CssClass = "btn btn-primary";

  // Assign Func<int> callback to gather Qty info
  oAddButton.GetQty = () => {
    return 1;

  // Append to the UI

See Add to Basket - Get Qty post for some greater detail on the GetQty function.

This add button handles all of the logic required for injecting & rendering the "Added to basket" modal that appers when clicking the add button.


7 - Clean up UI

The installer will have created a number of sections that require some styling, notably the following pages :

  • /basket.html
  • /payment-failed.html
  • /payment-success.html
  • /my-orders/
  • /my-orders/{order-no}.html

Although none of these will conform to design of other sections on the site.

These sections need to be updated, adding your templates and moving the controls or replacing them with bespoke ones.


None of these Sections will be updated on subsequent executions of the installer. Whereas the Admin sections will be. This is so that any changes suchas as suggested above are lost.

Mini Basket

Now's a good time to include the MiniBasket control into a persistant location somehwere on your site's layout, the heasder for example. The control to include is :



8 - Settings, Rewrites & Email setup

The Email references a logo via the following static:


By default the path is : /img/logo.png.

Other aspects of the emails & order processing are extracted from the Site Settings, for example Company Name and the Email address used are all taken from here.