ExperShop Shopping Cart

Home Contents

Please email any bug reports, comments or suggestions to ExperLog's Online Support

Overview

ExperShop Lite includes a shopping cart: items can be added and removed from the shopping cart, and the shopping cart content can be displayed in ExperShop DynHtml templates.

The shopping cart also includes facilities to calculate taxes and shipping costs.

Displaying the cart content

The shopping cart is accessible from DynHtml templates as a predefined data set, called ShoppingCart.

ShoppingCart is just like an SQL query result, except that you have no query to execute: its content is always valid.

For example, you can loop on the shopping cart content at any time: 

  $LoopOnResults ShoppingCart item
   Item Reference: $item:ProdId$ - Price: $item:Price$<br>
  $EndLoop
Shopping cart items include the following information:

  • ItemId: a unique reference to this item in the shopping cart
  • ProdId: the product's reference
  • Name: the product's name
  • Price: the item calculated unit price (0 if it's a sub-item, and the combination of the item price and all sub-item prices if it's an item with sub-items).
  • Qty: the quantity (numbers of occurrences of this item in the cart)
  • LinePrice: the item total price (Price * Qty)
  • Superior: the superior item if this item is a sub-item (empty otherwise)
  • ItemPrice: the item unit price (ignoring sub-item issues).
  • Product: an object that gives access to the EProduct table (each field of the table can be accessed, even if you added new ones: for example, if you defined a field called "color" in the EProduct table, you can reach it as Product.color).
The shopping cart itself has fields that can be accessed directly: for example, $ShoppingCart:TotalPrice$ is the total price for the shopping cart, tax and shipping costs included.

The following fields can be displayed:

  • ShoppingCart:TotalPrice: total price, tax and shipping costs included.
  • ShoppingCart:BasePrice: total price, tax and shipping costs excluded.
  • ShoppingCart:Tax: tax.
  • ShoppingCart:ShippingCost: shipping cost.
  • ShoppingCart:TaxZone: tax zone name
  • ShoppingCart:ShippingZone: shipping zone name
  • ShoppingCart:Discount: discount
  • ShoppingCart:PreorderId: pre-built internal Order ID when the cart content has been preordered.
  • ShoppingCart:SubTotal: subtotal (while looping on items).
  • ShoppingCart:ItemCount: total item count.
  • ShoppingCart:ItemIndex: While looping on items, current item index (an integer).

Adding/Removing items

The following actions can affect the shopping cart content:
  • com.expershop.actions.ESAddToCart (add an item)
  • com.expershop.actions.ESUpdateCart (update the cart content)
  • com.expershop.actions.ESEmptyCart (empty the cart)
  • com.expershop.actions.ESSaveCart/ESRestoreCart (save/restore the cart)
These actions, with their parameters, are detailed in the ExperShop Actions documentation.

To remove an item from the cart, use the ESUpdateCart action (and either specify a DEL-[ItemId] parameter equal to "y", or set the item quantity to "0").

Handling products with options (colors, sizes...)

When you add an item to the shopping cart (with the ESAddToCart action), you may define additional parameters to handle product options:

OptionNames lists the option names (comma separated): for example, 

<input type="hidden" name="OptionNames" value="Color,Size">
For each option, you must define an input control: the input's name is the option's name, and its value will set the option's value. Example: 
<select size="1" name="Color">
<option>Red
<option>Blue
</select>
<select size="1" name="Size">
<option>10
<option>20
</select>
Then, when the form is submitted, the item is added to the cart with the corresponding options set.

In the page that lists the cart content, you can retrieve the option values like this :

  $LoopOnResults ShoppingCart item
   Name=$item:Name$, Color=$item:Options.Color$, Size=$item:Options.Size$
   <br>
  $EndLoop
Note that, in the shop admin, the options will be retrieved from the order item as $item:Options$, in a less user-friendly manner: this will display a string that looks like { Color=Blue, Size=10 } - which is enough to be human-readable.

Keeping user info in the cart

The shopping cart can keep user information in memory: the information is kept as long as the cart is not emptied.

To store user information in the cart, use the ESUpdateCart or ESAddToCart actions, with UINFO_ parameters.
For example, in an HTML form that triggers the ESUpdateCart action:

  <input type=text name="UINFO_FirstName">
will cause an information called "FirstName" to be stored in the shopping cart when the form is submitted.

To retrieve previously stored user information, use $ShoppingCart:UInfo.$.
For example, to retrieve the "FirstName" info defined in the previous paragraph:

  Your first name is: $ShoppingCart:UInfo.FirstName$

Calculating taxes and shipping costs

Taxes and shipping cost calculation is based on named "zones", defined in the shop configuration file.
Zones define the way taxes and shipping costs are calculated.

The shopping cart can be associated to a tax zone and a shipping zone: zones are affected using the com.expershop.actions.ESUpdateCart action.
The default behaviour for tax and shipping zones can be defined.

Different kinds of shipping cost calculation algorithms can be used:

  • Flat rate (FLAT)
  • Weight-based rate (WEIGHT or WEIGHT_TABLE)
  • Item count (whole quantity) based rate (QTY)
  • Item count-based rate (ITEMCOUNT)
  • Price-based rate (PRICE)
Concerning the taxes, a value-added tax rate can be defined.

Example: defining two shipping zones

For example, let's define a "Drive-In" zone for customers who come to the shop (with free shipping, of course), and a "Home" zone for customers who require delivery at home (we'll charge them a flat rate cost, for example 10 USD).

The definitions in the configuration file can be the following: 

  #Define a "drive-in" free zone
  shop.shippingcost.DriveIn.rate: 0
  shop.shippingcost.DriveIn.type: FLAT

  #Define a "home" zone with 10$ flat charge
  shop.shippingcost.Home.rate: 10
  shop.shippingcost.Home.type: FLAT

  #Default shipping zone is "home"
  shop.shippingcost.defaultzone: Home
In the example above, the shipping cost will be 10$ by default, except if the customer chooses the "drive-in" option.

Note that rates are generally numbers, but you may also define intervals: for example, 

  shop.shippingcost.Home.type: PRICE
  shop.shippingcost.Home.rate: [0,100[=10;[100,+[=2;
means the shipping cost for the "Home" zone is 10$ if 0 <= total price < 100$, and 2$ if total price >= 100$

Calculating shipping costs based on a Weight database table

You can define weight-based shipping costs in a database table: the table will specify weight intervals, and corresponding costs, per shipping zone. There is also a "Rate" column, considered an exchange rate to be applied to the shipping cost (it is recommended to set its default value to 1). For example, we'll define 1 shipping zone (USA), with 2 shipping modes (Normal and Express), each Zone/Mode combination having 3 rates defined by weight intervals (0-2 kg, 2-10kg, 10-1000kg). First, declare the shipping zones in the configuration file:

  shop.shippingcost.defaultzone: USA
  shop.shippingcost.defaultmode: Normal

  shop.shippingcost.USA_Normal.type: weight_table
  shop.shippingcost.USA_Express.type: weight_table
Then, create a new table in the database, called EShippingCost. The table must include the following columns, of type Number:
  • Zone: Full zone name (Zone/Mode combination : eg. [zone-name]_[mode-name])
  • MinWeight: Minimum weight for the interval (included)
  • MaxWeight: Maximum weight for the interval (excluded)
  • Price: The shipping cost
  • Rate: a rate to be applied to the result (default 1 - eg. an exchange rate)
In our example, the table would be defined as follows (example in Postgres syntax):

  create table EShippingCost (
    Zone varchar(32),
    MinWeight float4,
    MaxWeight float4,
    Price float4,
    Rate float4 default 1,
  );
  
  insert into EShippingCost values('USA_Normal', 0, 2, 3.00, 1);
  insert into EShippingCost values('USA_Normal', 2, 10, 5.00, 1);
  insert into EShippingCost values('USA_Normal', 10, 1000, 8.00, 1);
  insert into EShippingCost values('USA_Express', 0, 2, 10.00, 1);
  insert into EShippingCost values('USA_Express', 2, 10, 15.00, 1);
  insert into EShippingCost values('USA_Express', 10, 1000, 20.00, 1);
Then, you just have to fill in the table: you can do that by yourself (writing database insert requests, or using a database GUI tool), or use the expershop bulk Loader, as follows:

Create an input file that contains the values

  $TABLE EShippingCost
  $COLUMN Zone
  $COLUMN MinWeight N
  $COLUMN MaxWeight N
  $COLUMN Price N
  $SEPARATORS ;
  $POSTFIX ;
  $BEGINDATA
  USA_Normal;0;2;3.00
  USA_Normal;2;10;5.00
  USA_Normal;10;1000;8.00
  USA_Express;0;2;10.00
  USA_Express;2;10;15.00
  USA_Express;10;1000;20.00
  $ENDDATA
This means:

Zone Weight(kg) Normal Express
USA [0,2[ 3 10
USA [2,10[ 5 15
USA [10,1000[ 8 20

Run the loader

java com.expershop.bulk.Loader inputfile

This will generate the INSERT SQL requests to fill in your table: save them into a file, and execute it as an SQL script in your database.

Discounts

Discounts can be associated to discount codes, defined in the shop configuration file. The discount can be based on the total price (proportional discount, which is the default choice), on the item count, or can be a flat discount (for example, 1$ discount).

For example, 2 discount codes (a 10% "gold" discount, and a 5% "silver" discount) can be defined as follows: 

  # Gold discount, 10 percent
  shop.discount.goldclub.rate: 0.10
  shop.discount.goldclub.type: price
  # Silver discount, 5 percent
  shop.discount.silverclub.rate: 0.05
  shop.discount.silverclub.type: price
In the above example, the discount codes to be used by customers in order to obtain their discounts are respectively "goldclub" and "silverclub".

The discount code is passed as a parameter to the com.expershop.actions.ESUpdateCart action (the parameter name is DiscountCode). Example: 

 <form method="post" action="com.expershop.lite.ExperSHOP">
 Enter your discount code:
 $Cookie
 <input type="hidden" name="Page" value="cart.tmpl">
 <input type="hidden" name="Action" value="com.expershop.actions.ESUpdateCart">
 <input type="text" name="DiscountCode" length="12">
 <input type="submit" value="Ok">
 </form>
Then, the discount can be displayed by the shopping cart, for example as follows: 
  $IfGt ShoppingCart:Discount 0
   Discount: $(.00)ShoppingCart:Discount$
  $Endif

Using multiple product database tables

This is an advanced functionality: the ExperShop shopping cart can use another table than EProduct as the reference database table for the shopping cart items.

For example, we may want to use the following table:

  create table MyProduct (
   ProdRef varchar(32),
   ProdName varchar(128),
   ProdPrice number
  );
A product table must contain at least 3 fields: a product reference (a unique ID), a product name, and a product price.
In the above example, ProdRef is the product reference, ProdName the product name, and ProdPrice the product price.

Two steps are necessary to add such a product to the shopping cart:

  • Configure the shopping cart, using the com.expershop.actions.ESConfigureCart action - to tell the shopping cart which table and fields it should use.
  • Add the product to the cart, as usual - for example, with the com.expershop.actions.ESAddToCart action.
Step 1: configuring the cart

For example, here's the code to configure the cart as described above:

  $Assign CONFIG_Table MyProduct
  $Assign CONFIG_ProdId ProdRef
  $Assign CONFIG_Name ProdName
  $Assign CONFIG_Price ProdPrice
  $Action com.expershop.actions.ESConfigureCart
To come back to the default config, just invoke the com.expershop.actions.ESConfigureCart action with no parameter.

Step 2: adding an item to the cart

If using the com.expershop.actions.ESAddToCart action: just act as usual, the "ProdId" parameter now representing "ProdRef" (this is transparent to the programmer, the action's parameter is still called "ProdId").