Custom Info provider example

The system uses Info providers to work with individual types of objects. A provider class contains methods for creating, updating, getting, and deleting the data of the corresponding objects. By customizing the appropriate Info provider, you can change or extend the functionality of nearly any object in the system.

The following example customizes the ShippingOptionInfoProvider, which the E-commerce solution uses to manage shipping options for product orders. The sample customization modifies how the provider calculates shipping costs.

You can use the same general approach to customize any standard provider, helper or manager class in Kentico (i.e. those that inherit from the AbstractProvider, AbstractHelper or AbstractManager class respectively).

Writing the custom provider

1. Open your web project in Visual Studio

2. Create a new class in the App_Code folder (or CMSApp_AppCode -> Old_App_Code if the project is installed as a web application). For example, name the class CustomShippingOptionInfoProvider.cs.

3. Edit the class and add the following using statements:

   Copy

   
   
   
    using CMS.Ecommerce;
    using CMS.Globalization;
    using CMS.Base;
   
   
    

4. Modify the class’s declaration so that it inherits from the CMS.Ecommerce.ShippingOptionInfoProvider class:

   Copy

   
   
   
    /// <summary>
    /// Customized ShippingOptionInfo provider.
    /// </summary>
    public class CustomShippingOptionInfoProvider : ShippingOptionInfoProvider
    {
   
    }
   
   
    

   Custom providers must always inherit from the original provider class. This ensures that the custom provider supports all of the default functionality and allows you to add your own customizations by overriding the existing members of the class.

5. Add the following override of the CalculateShippingInternal method into the class:

   Copy

   
   
   
    /// <summary>
    /// Calculates the shipping price for the specified shopping cart (shipping taxes are not included).
    /// Returns the shipping price in the site's main currency.
    /// </summary>
    /// <param name="cart">
    /// Object representing the related shopping cart. Provides the data used to calculate the shipping price.
    /// </param>
    protected override double CalculateShippingInternal(ShoppingCartInfo cart)
    {        
        // Checks that the shopping cart specified in the parameter exists
        if (cart != null)
        {
            // Ensures free shipping for customers who belong to the 'Gold partner' role
            if ((cart.User != null) && cart.User.IsInRole("GoldPartners", cart.SiteName))
            {
                return 0;
            }
            else
            {
                // Gets the customer's shipping address details from the shopping cart                      
                IAddress address = cart.ShoppingCartShippingAddress;
   
                if (address != null)
                {
                    // Gets the country from the shipping address
                    CountryInfo country = CountryInfoProvider.GetCountryInfo(address.AddressCountryID);
   
                    // Sets an extra shipping charge for addresses outside of the USA
                    if ((country != null) && (country.CountryName.ToLowerCSafe() != "usa"))
                    {
                        // Replace this flat charge with your own shipping calculations
                        // You can also create a custom setting and use it to dynamically load the value
                        double extraCharge = 10;
   
                        // Returns the standard shipping price with the extra charge added
                        return base.CalculateShippingInternal(cart) + extraCharge;
                    }
                }
            }
        }
   
        // Calculates the shipping price using the default method for regular customers from the USA
        return base.CalculateShippingInternal(cart);
    }
   
   
    

This override of the CalculateShippingInternal method ensures that:

• Users who belong to the Gold partner role always have free shipping.
• An extra flat charge is added for customers with shipping addresses outside of the USA.

Registering the provider class

To register your custom provider, add the RegisterCustomProvider assembly attribute above the class declaration (requires a reference to the CMS namespace):

using CMS;

[assembly: RegisterCustomProvider(typeof(CustomShippingOptionInfoProvider))]

The attribute’s parameter specifies the type of the custom provider class as a System.Type object.

Result

You can try out how the customization affects the e-commerce solution on the sample Corporate site.

1. Open the live website and log on as the Sample Gold Partner user (user name gold).
2. Navigate to the Products section and add any product to the shopping cart.
3. Go through the checkout process for the order.

In the Order preview (step 5 of the default checkout process), you can see that the shipping is always free, no matter what shipping address you entered.

If you repeat the same process as a regular user (e.g. Andy), the system calculates the shipping costs normally and adds the extra charge if the shipping address is in a different country than the USA.