Custom Info provider

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.

Example

The following example customizes the ShippingOptionInfoProvider, which the E-commerce module 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 or helper class in Kentico CMS (i.e. those that inherit from the AbstractProvider or AbstractHelper class respectively).

Writing the custom provider

1. Open your web project in Visual Studio and create a new class in the App_Code folder (or Old_App_Code if the project is installed as a web application). For example, name the class CustomShippingOptionInfoProvider.cs.

2. Edit the class and add the following references:

[C#]

using CMS.Ecommerce;
using CMS.SettingsProvider;
using CMS.SiteProvider;

3. Modify the class's declaration so that it inherits from the CMS.Ecommerce.ShippingOptionInfoProvider class:

[C#]

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

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

[C#]

/// <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
AddressInfo address = AddressInfoProvider.GetAddressInfo(cart.ShoppingCartShippingAddressID);

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

Note: The override gets the standard shipping price by calling the base method from the parent class. This allows you to calculate the default price based on the shipping option settings, and then modify it as needed.

Registering the provider class

Use the following steps to register your custom provider directly in App_Code:

1. Extend the CMSModuleLoader partial class. You can either create a new App_Code class file for this purpose or add the partial class declaration directly into the file containing your custom provider (CustomShippingOptionInfoProvider.cs in this case).

[C#]

public partial class CMSModuleLoader
{
}

2. Create a new attribute class inside the CMSModuleLoader that inherits from CMSLoaderAttribute. Add the attribute to the CMSModuleLoader partial class:

[C#]

using CMS.SettingsProvider;

[CustomProviderLoader]
public partial class CMSModuleLoader
{
/// <summary>
/// Attribute class that ensures the loading of custom providers.
/// </summary>
private class CustomProviderLoader : CMSLoaderAttribute
{
}
}

3. Override the Init method inside the attribute class and assign a new instance of the CustomShippingOptionInfoProvider class into the ProviderObject property of the original ShippingOptionInfoProvider.

[C#]

using CMS.Ecommerce;
using CMS.SettingsProvider;

[CustomProviderLoader]
public partial class CMSModuleLoader
{
/// <summary>
/// Attribute class that ensures the loading of custom providers.
/// </summary>
private class CustomProviderLoader : CMSLoaderAttribute
{
/// <summary>
/// Called automatically when the application starts.
/// </summary>
public override void Init()
{
// Registers the 'CustomShippingOptionInfoProvider' class as the ShippingOptionInfoProvider
ShippingOptionInfoProvider.ProviderObject = new CustomShippingOptionInfoProvider();
}
}
}

Result

You can try out how the customization affects the e-commerce module 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 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.

Help URL: http://devnet.kentico.com/docs/7_0/devguide/index.html?custom_providers_info_example.htm