SiteGenesis Choice of Bonus Product Discount Implementation

Review the files within the latest version of the SiteGenesis application to implement the choice of bonus product discount feature within your storefront application.

Note: The example implementation of Bonus Choice relies on jQuery UI, a separate library from jQuery, if you copy code verbatim, make sure you include it in your templates.
Note: As SiteGenesis changes, the files names used to implement this feature might change as well.

Pipelines

Cart.xml - required start nodes:
  • AddProduct – check to see if a product that was added triggers a bonus product.
  • AddBonusProduct – add bonus product to cart.
  • AddBonusProductBundle – add a subproduct to the bonus product bundle.
  • NewBonusDiscountLineItem – when adding a new product to the cart, check to see if it has triggered a new bonus discount line item

Product.xml - required start nodes:

  • AddBonusProduct – adds a bonus product.
  • GetBonusProducts – Renders a list of bonus products for a bonus discount line item.

JavaScript

The app.js file is located in the SiteGenesis Storefront cartridge. This file handles how the storefront processes user interface elements such as page and product navigation, swatch hover, zoom, image display, page cache initialization, the email subscription box, animation, sliders, carousel scrolling, tool tip display, site currency code/symbols, buttons, and links.

This file also handles handles the core processing of the bonus product window for selection and adding to the cart of bonus items. Search on the term "bonus" in this file to view how bonus items are handled.

Salesforce B2C Commerce Script

The following B2C Commerce script files, located in the Storefront Core cartridge, process choice of bonus product discounts.
  • cart/GetBonusDiscountLineItem.ds – gets a bonus discount line item by UUID. Used in the following pipelines:
    • Product-GetBonusProducts
    • Cart-AddBonusProduct
  • cart/ParseBonusProductsJSON.ds – converts an HTTP parameter map to a JSON object. Used in the Cart-AddBonusProduct pipeline.
  • cart/RemoveBonusDiscountLineItemProducts.ds – deletes all products associated with a bonus discount line item. Used in the Cart-AddBonusProduct pipeline.
  • cart/CalculateCart.ds – when a customer selects bonus products, these products appear in the cart beneath the corresponding bonus discount line item.
    • For a free bonus product discount, the word BONUS appears.
    • For the defined price choice of products discount, the prices appear.
      Note: To implement a defined price choice of products discount, you must change all your application display logic that assumes bonus products are free.

Templates

The following templates, located in the Storefront Core cartridge, process bonus products:
  • checkout/billing/billing.isml – accesses the resource: billing.bonusproductalert.
  • checkout/cart/bonusdiscountlineitems.isml – accesses the resource: product.selectbonusproduct.
  • checkout/cart/cart.isml – handles order bonus products, skips bonus discount line items for display cart line items, and shows bonus discount line items. Accesses the resources: cart/updatebonusproducts.

    When a bonus discount applies in the basket, SiteGenesis will show a line item in the cart even before customer selects bonus products. When the customer has selected bonus products and closed the bonus selection page, the selected items appear at the bottom of the cart grouped together with the line item representing the discount itself.

    An Update Bonus Products button appears allowing the customer to change their selection.

  • checkout/cart/minicart.isml – shows the minicart, including bonus items.
  • checkout/components/minilineitems.isml – implements the custom tag isminilineitems, which shows the line items in the minicart.
  • checkout/summary/summary.isml – visualizes the last step of the checkout, the order summary page prior to the actual order placing. It shows the complete content of the cart including product line items, bonus products, redeemed coupons and gift certificate line items.
  • components/order/orderdetails.isml – renders the order details. If it's a bonus product, renders the word Bonus.
  • components/order/orderdetailsemail.isml – renders the quantity in the email. If it's a bonus product, renders the word Bonus.
  • product/components/bonusproduct.isml – renders a bonus product. Used in the product/bonusproductgrid.isml template.

    SiteGenesis provides a link to a bonus selection page where the customer can choose bonus products. On this page, the bonus products to choose from are in the main list view and the selected products are listed at the bottom of the page. The customer can select products in the list view by entering a quantity, and configuring the product (for variation products, option products, and bundles), and then clicking Select. The selected products at the bottom have remove links.

    The page shows the number of bonus items allowed and the currently selected number. The page prevents the customer from selecting more than the maximum allowed.

    The customer must click the Add to Cart button to add the products to the cart, after which the window closes and the cart page appears.

  • product/bonusproductgrid/bonusproductgrid.isml – is the main rendering template that shows all bonus products used in the bonus product dialog. While it might be necessary to use the jQuery UI, if you are going to use an alternative method, you will likely need to delete that styling.
  • product/components/ subbonusproduct/subbonusproduct.isml – renders any subproduct of a bundle or product set. Used in the product/components/bonusproduct.isml template.
  • product/bonusproductjson.isml – renders a bonus discount line item in JSON format. Not used in any template.
  • product/pt_productdetails.isml – provides messaging that is similar to product bonus discount messaging. If a product is in the qualifying product list or the bonus product list of a given promotion, the promotion appears on the product details page. This means that the API method PromotionPlan.Collection getProductPromotions(Product product) returns a promotion if the product is on the qualifying list of the promotion, or if the promotion contains a choice of bonus products discount that grants the product as a bonus.

    A message appears telling the customer that a bonus promotion is currently active. The customer can click Select Bonus Product(s) or No Thanks.

The following template is located in the Storefront Rich UI cartridge:
  • resources/appresources.isml – moves product constants, resource, and messages from product.isml to a common template, and adds new bonus product messages.

Resource Files

These resources are used to show bonus product messages:

checkout.properties

billing.bonusproductalert=You are eligible for a bonus product.
  Click the "Select" button  to return to the cart to select your products or "No Thanks"
  to continue placing the order.
cart.bonusmaxitems=This discount entitles you to {0} bonus item(s).
cart.bonusnumselected=You have selected {0} item(s).
cart.updatebonusproducts=Update Bonus Products
cart.updatebonusproduct=Update Bonus Product
cart.selectbonusproducts=Select Bonus Products
cart.selectbonusproduct=Select Bonus Product

product.properties

product.bonusproducts=Bonus Product(s)
product.bonusproduct=Bonus Product
product.bonusproducttext=Select 1 or more, Bonus Products:
product.bonusproductsmax=The maximum number of bonus products have been selected. Remove one in order to add additional bonus products.
product.bonusproductalert=You are eligible for a bonus product(s).

locale.properties

global.bonus=Bonus
global.bonusitem=Bonus Item

Resource.Msg Calls Within Templates

The following table shows the resource.msg keys that are referenced in the following templates:

Template Resource.msg key Resource file
checkout/billing.isml

billing.bonusproductalert

checkout.properties

checkout/cart/bonusdiscountlineitem.isml

product.selectbonusproduct

product.bonusproducts

product.properties
checkout/cart/bonusdiscountlineitem.isml

global.nothanks

locale.properties

checkout/cart/cart.isml

checkout/components/minilineitems.isml

checkout/summary/summary.isml

components/order/orderdetails.isml

components/order/ordetailsemail.isml

global.bonus

locale.properties

checkout/cart/cart.isml

global.applied

global.notapplied

locale.properties
checkout/cart/cart.isml

cart.updatebonusproducts

cart.updatebonusproduct

cart.selectbonusproducts

cart.selectbonusproduct

cart.bonusmaxitems

cart.bonusnumselected

checkout.properties

checkout/cart/minicart.isml product.bonusproductalert product.properties

product/components/bonusproductgrid.isml

product.selectbonusproducts

product.properties
none

The following key is in the resource file, but not referenced by a template:

global.bonusitem

locale.properties

none

The following keys are in the resource file, but not referenced by a template:

product.bonusproduct

product.bonusproducttext

product.bonusproductsmax

product.properties

CSS

In style.css, search for:

  • Bonus Products section
    /* bonus products */ /* ------------------------------------- */
     .select-bonus-btn,
     .no-bonus-btn{float:left;margin:0 5px 0 0;}
     .buttonbar{margin:11px 0;overflow:hidden;width:336px;}
     .bonus-product-list
     .bonus-product-item{border-bottom:1px solid #E0E0E0;clear:both;}
     .bonus-product-list
     .product-name{float:none;margin:1em 0;}
     .bonus-product-list
     .product-add-to-cart button{float:left;margin-top:24px;}
     .bonus-product-list-footer{clear:both;}
     .bonus-product-list-footer button{float:right;}
  • .cart-promo lines (there are two)