Kentico CMS 6.0 Developer's Guide

Customizing providers from the App_Code folder

Customizing providers from the App_Code folder

Previous topic Next topic Mail us feedback on this topic!  

Customizing providers from the App_Code folder

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

Custom providers can be defined in the App_Code folder, without the need to be compiled into an additional assembly. This process consists of two basic steps: creating a custom class and then registering it so that it is dynamically loaded when required. To see an example of how to properly write the provider class itself, please see the Custom E-mail provider topic in this chapter.

 

The steps below describe how you can register a custom class in the App_Code folder:

 

1. Open your project in Visual Studio and expand the App_Code folder (or Old_App_Code if you installed Kentico CMS as a web application). Then, navigate to the Samples\Modules\ directory and open the SampleClassLoaderModule.cs file. You can examine the code of this file to learn how to load a custom class and use it as inspiration for writing your own loaders.

 

[C#]

 

/// <summary>

/// Sample class loader. The CMSModuleLoader partial class ensures correct registration.

/// </summary>

[SampleClassLoaderModuleLoader]

public partial class CMSModuleLoader

{

   /// <summary>

   /// Attribute that ensures the loading of custom classes.

   /// </summary>

  private class SampleClassLoaderModuleLoaderAttribute : CMSLoaderAttribute

   {

       ...

   }

}

 

Loading classes in App_Code is done by extending the CMSModuleLoader partial class and adding attributes to it. Individual attributes are then defined as private classes that inherit from CMS.SettingsProvider.CMSLoaderAttribute.

 

2. When this type of attribute is processed, its Init() method is called, so you can override it to load the classes that you need. The most direct way to register a custom class is to use the API as shown below:

 

[C#]

 

/// <summary>

/// Initializes the loading of a custom class. Called by the CMSModuleLoader when the attribute is processed.
/// </summary>
public override void Init()

{          

  // Assigns an object of the CustomSiteInfoProvider class as the provider.

  SiteInfoProvider.ProviderObject = new CustomSiteInfoProvider();

}

 

Specifically, this is done by assigning a new object of your class into the ProviderObject property of the provider that you wish to customize. The same applies when customizing helper classes, with the difference that the object must be assigned as the value of the HelperObject property instead. Remember to add a reference to the namespace that contains the given provider or helper.

 

3. An alternative approach is to use the Init() method's override to assign a handler for the OnGetCustomClass event of the CMS.SettingsProvider.ClassHelper, which can then be defined to return an object of the appropriate class. For example:

 

[C#]

 

/// <summary>

/// Initializes the loading of a custom class. Called by the CMSModuleLoader when the attribute is processed.
/// </summary>
public override void Init()
{
  // Assigns a handler that registers custom provider or helper classes from App_Code via the cms.extensibility web.config section.
  ClassHelper.OnGetCustomClass += ClassHelper_OnGetCustomClass;
}
 
 

/// <summary>

/// Gets a custom class object based on the given parameters.

/// </summary>

private void ClassHelper_OnGetCustomClass(object sender, ClassEventArgs e)

{

  if (e.Object == null)

   {

      // Passes on an object of the appropriate custom class.

      switch (e.ClassName)

       {

          // Gets an object of the CustomSiteInfoProvider class inheriting from the SiteInfoProvider.

          case "CustomSiteInfoProvider":

               e.Object = new CustomSiteInfoProvider();

              break;

 

          // Gets an object of the CustomCacheHelper class inheriting from the CacheHelper.

          case "CustomCacheHelper":

               e.Object = new CustomCacheHelper();

              break;

 

          // Gets an object of the CustomEmailProvider class inheriting from the EmailProvider.

          case "CustomEmailProvider":

               e.Object = new CustomEmailProvider();

              break;
 

       }

   }

}

 

The handler checks the name of the requested provider or helper and then returns an instance of the corresponding custom class. The OnGetCustomClass event is only fired if you specify that a custom class should be used for the given provider or helper via a special extensibility section of the application's web.config file. There, the value of the ClassName property of the handler's ClassEventArgs parameter is also set. For details about how you can assign a custom class in the web.config, please see Registering custom classes via the web.config.

 

For more examples, you can check the code of the various files in the ~/App_Code/Samples folder of your web project.