SEARCH

SHOPPING CART

0 Products - $0.00

Shipper Products BV Commerce Components Support

Tell a friend   Print  

How to Create a BVC5 Offer Plugin

BV Commerce 5 includes support for plugins to provide custom order processing (workflow), product workflow, payment methods, shipping rate methods, discounts, and more. This article walks through the steps to create a custom offer with the following rule: if the customer purchases at least X amount, then up to Y quantity of products Z are free.

Step 1 - Pick a Name

This offer is going to have an editor so you can set X, Y, and Z in the rule shown above. For BVC5 to find the editor, you need to create a subdirectory with the same name as the offer. This offer is called "Sample Offer", so create a directory in the BVModules/Offers directory called "Sample Offer".

Step 2 - Create the Offer Code

To create a custom offer, you just need to implement a new public class that inherits from BVSoftware.Bvc5.Core.Marketing.OfferTaskProcessorBase, then override Execute, GetSettings, and GetPriority. To create the Sample Offer, copy the attached copy of SampleOffer.vb to the App_Code directory of your web site.

GetPriority is called by BVC5 to determine the order in which multiple offers are processed. Lower values are processed first. There are several "standard" values that you can use include: Shipping (20), Product (40), BuyOneGetOne (60), and OrderTotal (80). Since Sample Offer affects the order totals, GetPriority returns OrderTotal.

    Public Overrides Function GetPriority() As Byte

        Return PriorityLevels.OrderTotal

    End Function

GetSettings is called by BVC5 before Execute and is used to retrieve the specific settings for the custom offer. The Sample Offer has 3 specific settings:

1. The minimum order amount which must be greater than $0. This offer will not apply if the order amount is less than the minimum order amount.
2. The list of products that are being offered for free.
3. The maximum quantity which must be greater than 0. This is the maximum number of each free product that will be offered in each order.

These are retrieved using the following code:

    Public Overrides Sub GetSettings(ByVal context As OrderTaskContext)

        _maximumQuantity = SettingsManager.GetIntegerSetting("MaximumQuantity", 1)

        _minimumAmount = SettingsManager.GetDecimalSetting("MinimumAmount", 0)

        _products = SettingsManager.GetSettingList("FreeProducts")

    End Sub

Execute is called by BVC5 to calculate the actual discount. Execute is responsible for figuring out if the order meets the specific requirements of the offer and then calculating the discount:

    Public Overrides Function Execute(ByVal context As OrderTaskContext) As DiscountQueue

        Dim discounts As New DiscountQueue

        ' This offer is only good if the order total is equal to or above

        ' a set amount. This code calculates the order amount, not including

        ' the free products.

        Dim subtotal As Decimal = context.Order.SubTotal

        For Each lineitem As LineItem In context.Order.Items

            For Each setting As ComponentSettingListItem In _products

                If String.Compare(setting.Setting1, lineitem.ProductId, True) = 0 Then

                    subtotal -= lineitem.BasePrice

                End If

            Next

        Next

        ' If the minimum order amount is met, then mark each free item

        ' in the order by adding a discount up to the maximum quantity.

        If subtotal >= _minimumAmount Then

            For Each lineitem As LineItem In context.Order.Items

                For Each setting As ComponentSettingListItem In _products

                    If String.Compare(setting.Setting1, lineitem.ProductId, True) = 0 Then

                        Dim quantity As Decimal = 0

                        quantity = Math.Min(lineitem.Quantity, _maximumQuantity)

                        discounts.AddDiscount("OrderDiscounts", _

                          lineitem.BasePrice * quantity, _

                          DiscountQueueItemType.Order)

                    End If

                Next

            Next

        End If

        Return discounts

    End Function

When you add a discount you can use a lineitem bvin if you want the discount to apply to a specific line item (but it will apply to every occurrence of the line item), "OrderDiscounts" if you want the discount to apply to the order subtotal, or "ShippingDiscounts" if you want the discount to apply to the shipping amount. Our Sample Offer applies to the order subtotal (not the lineitem since there is a maximum quantity that is discounted).

Step 3 - Tell BVC5 to Load the Custom Offer Code

Edit App_Code/TaskLoader.vb, find the LoadOrderTaskProcessors method and add the custom offer:

result.Add(New ProcessorComponentPair("Sample Offer", GetType(SampleOffer)))

Step 4 - Create the Offer Editor Code

The editor is used by BVC5 to edit the settings of the offer. Every offer has some common settings such as the effective dates, and some specific settings. The Special Offer editor only needs to edit the specific settings.

To create the Sample Offer editor, copy the attached files called Edit.ascx and Edit.ascx.vb into the directory called BVModules/Offers. Edit.ascx has 3 fields called MinimumAmountField, MaximumQuantityField, and FreeProducts. To build the list of FreeProducts, Edit.ascx includes the ProductPicker user control that is included with BVC5.

Edit.ascx.vb has the code used to read and save the specific settings for our offer. To be recognized by BVC5, the offer editor must inherit from OfferTemplate and then override three methods: Initialize, Save, and Cancel. Initialize is called before the editor is displayed and is used to read the settings. Save is called when the merchant clicks on the Save Settings button and is used to save the settings. Cancel is callled when the merchant clicks on the Cancel button and can be used to reset values. The Sample Offer editor code also overrides the DataBind method to display the list of free products.

Step 5 - Create a Custom Offer

1. Select the Marketing tab from the BVAdmin page.
2. Select Offers from the Marketing menu.
3. Select Sample Offer and then click on the New button.
4. Enter the minimum order amount and maximum free quantity, then pick the free products.
5. Click on the Save Changes button to create the offer.

Step 6 - Test the Custom Offer

1. Go to the store and start a new order that includes the free products and not free products.
2. Adjust the quantity of the not free products until the order total meets the minimum order amount.

Attachments

SampleOffer.zip

This site looks much better in a browser that supports current web standards, but it is accessible to any browser. Download one now