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.
Important 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