Working with the Add to Cart Web Part

The Add to Cart Web Part adds the product currently displayed to the shopping cart. The Add to Cart Web Part appears alongside either the Simple Property List Web Part or the Product Details Web Part on a product details page. In addition, the Add to Cart Web Part can provide an option to add the current product to an existing or new shopper list.

If there are variants for the product that is being added, the Add to Cart Web Part provides a drop-down list of the variants. The Add to Cart Web Part can also be configured to allow a quantity field to be displayed for shopper entry. Also, the Add to Cart Web Part can determine if the product selected is out of stock, and if so, display a message to that effect to the shopper, as well as disabling the Add to Cart button.

Architecture

The Add to Cart Web Part interacts with the Product Provider Web Part through a Web Part connection. The Add to Cart Web Part sends a list of properties to the Product Provider Web Part, which then returns the product to the Add to Cart Web Part.

The Add to Cart Web Part consists of the following components:

  • AddToCartWebPart/SPAddToCartWebPart. Loads all the necessary user controls dynamically. It is derived from BaseUserControlWebPart.

  • AddToCart.ascx User Control. Houses the user interface components and the corresponding event handlers. The user interface components include the variant drop-down selector, quantity box, and an Add to Cart button.

  • BaseUserControlWebPart. Encapsulates ASCX loading functionality.

  • SiteContext. Gets information about the current request, such as UserID, Channel, and so on.

Properties

The following table lists and describes the properties available on the Add to Cart Web Part property sheet.

Property

Type

Maps to

Description

Default

Display "quantity" input box

Boolean

ShowQuantityBox

If checked, a drop-down text field lets the user type in the quantity that will be added to the cart when the "add to cart" button is pressed. If unchecked, the text field is not displayed adding to cart always adds a single item.

True

Display "add to list" button

Boolean

DisplayAddToShopperList

If checked, an "Add to list" button is displayed.

True

"Add to list" adds to default list

Boolean

ShopperListButtonLabel

If checked, the "Add to list" button adds the item directly to the default list. If unchecked, a pop-up is displayed allowing the user to select the desired list to add the item to.

False

Variant list item display format

String

PriceProperty

Sets the "String.Format"-compatible format string used to display each product picker item. Default is "{0} - ${1:#.00}", where {0} represents the display name and {1} represents the price (default value uses additional formatting instructions). Note that the product properties used for display name and price are configured using other settings on this Web Part.

{0} - {1}

Layout : Horizontal alignment

Enum

ControlAlignment

Sets the horizontal alignment to use when displaying this web part.

Left

"Add to cart" button label

String

ButtonLabel

Sets the text displayed on the "add to cart" button.

Add To Cart

"Add to list" button text

String

AddToShopperListDefault

Sets the text displayed on the "Add to list" button.

Add To List

"Out of stock" message

String

OutOfStockMessage

Message displayed when adding a product that is out of stock.

Product is out of stock.

Commerce "Basket" to use

String

BasketName

Sets the name of the "Basket" that this Web Part will add items to. The default and recommended values are empty, indicating the default Basket.

Blank

Product property used as display name

String

DisplayNameProperty

Name of the property associated with the product in the Commerce Server 2009 R2 catalog to use as the display name in the selection picker.

DisplayName

Product property used as price

String

PriceProperty

Name of the property associated with the price entry in the Commerce Server 2009 R2 catalog to use as the price in the selection picker.

ListPrice

User Control name

String

UserControlName

The name of the Add to cart user control.

AddToCart.ascx

Customization

You can customize the Add to Cart Web Part by modifying the AddToCart.ascx control, including the code-behind component.

Dd442232.alert_caution(en-us,CS.95).gifImportant Note:

If you make modifications to the ASCX file to customize a Web Part, rename the modified ASCX file to avoid the risk of overwriting your Web Part customizations during an upgrade.

Error Handling

There is no design-time error handing required for this Web Part.

Run Time Validation

The following table lists the Add to Cart Web Part fields that the Product Query Web Part validates at run time.

Field to validate

Description

Occurs

System response

DisplayNameProperty

The name of the property that holds the name of the product.

When rendering the Web Part.

Displays an error that indicates that the DisplayNameProperty is required.

ListPrice

The name of the property that holds the list price of the product.

When rendering the Web Part

Displays an error that indicates that the ListPrice is required.

The Add to Cart Web Part handles the following scenarios:

  • Does not let shoppers add a product to the shopping cart with a quantity set to 0, a negative number, or a non-digit.

  • Does not let shoppers add a product to the shopping cart that is out of stock.

API Dependencies

There are no direct API dependencies for the Add to Cart Web Part. However, there are indirect dependencies to determine the following:

  • Check whether a product is out of stock

  • Retrieve the list price of the product

  • Retrieve the variant price of the product

  • Retrieve the display name of the product

See Also

Other Resources

Developing with SharePoint Commerce Services

Developing with Orders Web Parts

Add to Cart Web Part