Shipping Cost Estimator for StoreFront 6
by Structured Solutions

The Shipping Cost Estimator Add-On provides a tool for customers to calculate the shipping cost of their order prior to checkout. It works with all StoreFront shipping methods and the Select Carrier Control to seamlessly apply shipping preferences to the checkout process.

Features
Tables of Contents

Installation Instructions

1. Install the Shipping Cost Estimator
  1. The product is delivered as a single program file. Run the program to extract all the files for Shipping Cost Estimator to a directory on your local computer. The installation directory will have two subdirectories called bin and sfaddons .
  2. Copy the files from the bin directory to the bin directory of your store's web site. Replace any existing files with the same name.

    Some stores are configured to use a separate bin directory for secure processing pages (sometimes called the "SSL pages"). If your store is configured this way, copy the files to the secure bin directory also.

  3. Copy the sfaddons subdirectory and everything in it to your root directory of your store. This will create a new directory on your store's web site called sfaddons . If you already have an sfaddons directory, replace any existing files and subdirectories with the same name.
  4. Copy the sfaddons directory and everything in it to the ssl directory of your store's web site. This will create a new directory called ssl/sfaddons. If you already have an ssl/sfaddons directory, replace any existing files and subdirectories with the same name.

Now you need to add a button somewhere on your site that launches the Shipping Cost Estimator. There are two common locations: near the cart list in the left or right column, and near the total box on the shopping cart page. Examples of both are shown below. You can install the launch button in one or both locations or anywhere else in your site that makes sense.

2. Example: Adding the Launch Button to the Right Column
  1. Make a backup copy of CommonControls/RightColumnNav.ascx
  2. Open RightColumnNav.ascx in a text editor and add the following line to the top of the file:
    <%@ Register TagPrefix="sfaddons" Namespace="StructuredSolutions.WebControls" Assembly="SSShippingCost" %>
  3. Add this HTML to the bottom of the file:
    <sfaddons:ShippingCostLink id="ShippingCostLink1" runat="server" ImageUrl="../sfaddons/images/shippingcost.jpg"/>
  4. Save your changes and close the file.
  5. Copy your modified RightColumnNav.ascx to the ssl/CommonControls directory.
3. Example: Adding the Launch Button to the Shopping Cart
  1. Make a backup copy of ShoppingCart.aspx.
  2. Open ShoppingCart.aspx in a text editor and add the following line to the top of the file:
    <%@ Register TagPrefix="sfaddons" Namespace="StructuredSolutions.WebControls" Assembly="SSShippingCost" %>
  3. Now locate the following tag (the tag is much longer than shown here. That's what the "..." means)::
    <cc1:TotalDisplay id="TotalDisplay1" runat="server" ...></cc1:TotalDisplay>
  4. Add the HTML shown in bold (note that the new HTML goes BEFORE the </td> tag):
    < table> < tr> < td> <code><cc1:TotalDisplay id= "TotalDisplay1" runat= "server"...></cc1:TotalDisplay>
    <br>
    <sfaddons:ShippingCostLink id="ShippingCostLink1" runat="server" ToolTip="Estimate Shipping Costs" ImageUrl="sfaddons/images/shippingcost.jpg"/>
    </td>
  5. Save your changes and close the file.

This concludes the installation.

Back to top

User's Guide

After installing the add-on as shown above, there will be a button at the bottom of the right column and near the bottom of the shopping cart page. Both buttons are labeled "Estimate Shipping" in the same style as the default StoreFront 6 buttons. Pressing either button will launch a pop-up Shipping Cost Estimator window. The appearance of the estimator window will depend on the shipping method you have selected for your site: carrier-based, product-based, or value-based.

Carrier-Based Estimator Window

To use this estimator you must enter the destination zip/postal code, state/ province, and country. A series of tabs are displayed in the middle of the window. There is one tab for each activated carrier in your store. The current carrier is shown by the tab that is in front of the others. There are two ways to retrieve the shipping rates for an order. Pressing the Reload Rates button will retrieve the rates for the current carrier. Selecting the tab for a different carrier will make that carrier current and retrieve the rates.

Rates are cached after they are retrieved for 1 minute. This means that customers can switch back and forth between tabs to compare rates. If they wait for longer than a minute, or add new items to their cart,  or change any of the destination information, the rates will be retrieved from the carrier again. Pressing Reload Rates will always retrieve the rates from the carrier. Depending on the carrier, retrieving rates can be slow.

Once the rates are retrieved they are displayed in a table. There is a radio button in front of each rate. The customer can select a preferred shipping method by clicking on the radio button in front of the rate. When a preferred shipping method is selected, the estimator window will calculate and display the total shipping costs for the order assuming that the entire order will be shipped to a single address. The preferred shipping method is also stored so that it can be pre-selected when the customer checks out.

Product-Based Estimator Window

The product-based estimator window will display a table of each item in the shopping cart showing the quantity, item name, and extended shipping cost. The total shipping for the order is also calculated and displayed assuming the entire order will go to one address. Press Reload Rates to recalculate the totals if new items are added to the cart.

Value-Based Estimator Window

The value-based estimator window will display the value-bases shipping rates in a table showing the break off points for each rate. The current rate band is highlighted and the total shipping for the order is calculated and displayed assuming the entire order will go to one address. Press Reload Rates to recalculate the totals if new items are added to the cart.

Back to top

Advanced Control Documentation

The tables below list the attributes that can be added to the following tags:

<sfaddons:ShippingCostLink>
This tag is used to create the Shipping Cost Estimator Launch button.
<sfaddons:ShippingCostControl>
This tag is used inside sfaddons/ShippingCost.aspx  to display the actual Shipping Cost Estimates.
Multiple attributes can be specified just like the are for standard HTML tags like <table>. Moreover, you do not need to recompile your store to see your changes. Just save your change and reload the page in your browser. This makes experimenting very easy.

<sfaddons:ShippingCostLink> Attributes

The <sfaddons:ShippingCostLink> tag is used to create a launch button for the Shipping Cost Estimator. You can place this tag anywhere in your site that you wish. It is very similar to the .NET Framework HyperLink Control except that it does not support the NavigateUrl or Target attributes since these are internally generated. A few of the most pertinent attributes are shown below. For a complete list of attributes, please refer to Microsoft's online documentation for HyperLink.

Attribute Description Example
EstimatorHeight The height, in pixels, of the Shipping Cost Estimator window. This only works when you first open the estimator window. It will not change the size of the window, so if you include the link control in multiple places, use the same value in each location.

Default: Value-based shipping: 400, carrier-based shipping: 575, product-based shipping: 325

 To open an estimator window that is 450 pixels high,

<sfaddons:ShippingCostLink EstimatorHeight="450" ...>

 
EstimatorWidth The width, in pixels, of the Shipping Cost Estimator window. This only works when you first open the estimator window. It will not change the size of the window, so if you include the link control in multiple places, use the same value in each location.

Default: Value-based shipping: 325, carrier-based shipping: 375, product-based shipping: 275

 To open an estimator window that is 450 pixels wide,

<sfaddons:ShippingCostLink EstimatorWidth="450" ...>

 
HideIfSecure A Boolean value (True or False) that determines if the link should hide itself when the page is loaded from the secure portion of the store (anywhere below the ssl directory).

Default: False

 To hide the link when it is part of a ssl page,

<sfaddons:ShippingCostLink HideIfSecure="True" ...>
ImageUrl

The path to an image to display as the launch button.

If no path is entered, the Text attribute will displayed as a link.

Default: no path

 To use the supplied smaller image,

<sfaddons:ShippingCostLink ImageUrl="../sfaddons/images/shippingcostsmall.jpg" ...>
Text

The text to display as the launch button.

If no image is entered, the text is displayed as a link.

Default: no text

 To create a text link,

<sfaddons:ShippingCostLink Text="Estimate Shipping" ...>
This rather complicated example creates an all-text launch button that is surrounded by a thin black border. When the mouse moves over the button, the background will darken and the text will lighten. When the mouse moves off of the button, the appearance returns to normal.

<sfaddons:ShippingCostLink
   id="ShippingCostLink1"
   runat="server"
   ToolTip="Estimate Shipping Costs"
   CssClass="RightColumn"
   Width="125px"
   BorderStyle="Solid"
   BorderWidth="1px"
   BorderColor="Black"
   Style="PADDING-RIGHT:3px;PADDING-LEFT:3px;PADDING-BOTTOM:3px;PADDING-TOP:3px;TEXT-ALIGN:center"
  onMouseOver="this.style.backgroundColor='#666666';this.style.color='#E7E3D7';this.style.fontWeight= 'bold'"
  onMouseOut="this.style.backgroundColor='transparent';this.style.color='black';this.style.fontWeight='normal'"
   Text="Shipping">
</sfaddons:ShippingCostLink>

<sfaddons:ShippingCostControl> Attributes

The <sfaddons:ShippingCostControl> tag is used in the sfaddons/ShippingCost.aspx page to display the actual shipping cost estimates. In fact, it is the only control in the sfaddons/ShippingCost.aspx page. If you'd like, you can use this tag in any other page of your site. This will embed the shipping cost estimates directly into the page. This might be useful if you prefer not to use pop-up windows.

The following attributes can be added to the <sfaddons:ShippingCostControl> tag to control the behavior and appearance of the shipping cost estimates:

Attribute Description Example
CarrierCode

The code for the carrier you want to be selected when the estimator is first loaded. The code can be found in the ShippingCarriers table of the store database. The code can be entered in either upper or lower case.

If no code is entered, or an incorrect code, or a code for an inactive carrier is entered, then the default carrier will be pre-selected.

Default: The 1st carrier in the list of active carriers returned from the StoreFront engine.

 To make USPS the default carrier,

<sfaddons:ShippingCostControl CarrierCode="USPS" ...>
CssClass This is the class used for all control elements that do not have another class applied. The CSS class must be defined or linked to the page.

Default: Content

 To use MyContent as the class,

<sfaddons:ShippingCostControl CssClass="MyContent" ...>
EstimatorInstructions

The text to display at the top of the estimator window.

Default: The default texts are instructions for using the estimator, written in english.

To change the estimator instructions,

<sfaddons:ShippingCostControl
  EstimatorInstructions="Do it" ...>
FreeShippingMessage The message to display if the order qualifies for free shipping.

Default: "This order qualifies for free shipping."

 To change the free shipping message,

<sfaddons:ShippingCostControl FreeShippingMessage="FREE!" ...>
InnerCssClass The CSS class applied to the instructions, the tab surrounding the rate table, and the buttons.

Default: Instructions

 To use MyInstructionsas the class,

<sfaddons:ShippingCostControl InnerCssClass="MyInstructions" ...>
NoItemsMessage

The text of the message to display when there are no items in the cart.

Default: "There are no items in your cart."

To change the "no items" message,

<sfaddons:ShippingCostControl
  NoItemsMessage="No items" ...>
NoRatesMessage

The text to display when the carrier does not return any rates.

Default: "This carrier is not available for this package."

To change the "no items" message,

<sfaddons:ShippingCostControl
  NoRatesMessage="No rates" ...>
NoShippableItemsMessage

The text of the message to display when there are no shippable items in the cart.

Default: "There are no shippable items in your cart."

To change the "no shippable items" message,

<sfaddons:ShippingCostControl
  NoShippableItemsMessage="Free Shipping" ...>
RateMessage

A list of <RateMessage> tags can be entered within the beginning and ending tags of the ShippingCostControl tag. Enter one RateMessage for each carrier you support. Each RateMessage specifies the message that should be displayed if one or more of the rates displayed has been increased or decreased by some factor. For example, if the rate for UPS Ground is multiplied by 130% before it is displayed, then the RateMessage for UPS will be displayed.

The format of each RateMessage is:

<RateMessage CarrierCode="carrierCode" Message="message">

For example,

<RateMessage CarrierCode="UPS" Message="Rates represent our cost for shipping">

Default: Only UPS has a default RateMessage.

 To define a simple RateMessage for UPS and FEDEX,
<sfaddons:ShipingCostControl  
              ...>
     <RateMessage CarrierCode=
               "UPS" Message= "MyStoreRates" />
     <RateMessage CarrierCode=
               "FEDEX" Message= "MyStoreRates" />
</sfaddons:ShippingCostControl>
RatesCssClass The CSS class to use for the shipping rate table.

Default: Content

 To use MyContent as the class,

<sfaddons:ShippingCostControl RatesCssClass="MyContent" ...>
ResidentialRates Boolean value (True or False) that determines if residential rates are displayed. The only applies to carrier based shipping, it is ignored otherwise. Set this value to True if you ship to residential addresses.

Default: False

 To display residential rates,

<sfaddons:ShippingCostControl ResidentialRates="True" ...>
SelectedRateCssClass The CSS class to use for the selected rate in the rate table. This applies to carrier and value based shipping.

The default class of "SelectedRate" is defined in the header of ShippingCost.aspx. By default this style is defined to use a background color of "WhiteSmoke". To change the definition, of "SelectedRate", please edit ShippingCost.aspx.

Default: SelectedRate

 To remove any highlighting of the selected rate,

<sfaddons:ShippingCostControl SelectedRateCssClass="" ...>

If you examine the ShippingCost.aspx page, you will see that the <sfaddons:ShippingCostControl> tag is registered to the user control file sfaddons/ShippingCost.ascx.  This file has the layout of the control which can be edited just like any other StoreFront control file. That is, you can change the layout, class and style of elements in the control to create a unique appearance. Avoid deleting or changing the type of any tag that has an "id" assigned since these are used by the code.

Back to top

Removal Instructions

To remove the Shipping Cost Estimator from your store, you will need to restore RightColumnNav.ascx, ShoppingCart.aspx, and ShipSummary.aspx. If you made a backup copy of these files prior to installing the patch, then use those in the restore steps below. Otherwise, use the original versions from the StoreFront installation directory (typically. "C:\Program Files\StoreFront 6.0\Web\Controls").

  1. Copy the backup or original RightColumnNav.ascx to the the CommonControls and ssl/CommonControls directories of your store's web site.
  2. Copy the backup or original ShoppingCart.aspx to the root of your store's web site.
  3. Remove SSShippingCost.dll from the bin directory of your store's web site.
  4. If you have no other add-on from Structured Solutions, remove the sfaddons directory.

Back to top

Support

Free email support is available from support@structured-solutions.net.

Back to top

Copyright © 2003-5 by Structured Solutions