Handling object events

✖
Copy to clipboard

Objects include all data structures used within Kentico, for example user accounts, forums, page templates, search indexes, or setting keys. By handling the events that occur during the life cycle of objects, you can add custom functionality to almost any part of the system. In the API, objects are represented by Info classes.

Use the following classes to access the object events:

  • ObjectEvents - events triggered for all object types
  • <name>Info.TYPEINFO.Events - events triggered only for a specific object type, for example: UserInfo.TYPEINFO.Events

See the Global event reference for information about the available events.

Note: Within the context of event handling, objects do NOT include documents (pages in the website content tree). Use the DocumentEvents class to assign handlers to events that the system triggers for documents.

Example

The following example demonstrates how to use event handlers to customize the behavior of a specific type of object.

The sample code extends the functionality of forum groups by creating a handler for the Insert.After event of the ForumGroupInfo object type. This event occurs whenever a forum group is created. The custom logic automatically adds an initial child forum for every new forum group.

  1. Open your web project in Visual Studio.
  2. Create a new class in the App_Code folder (or CMSApp_AppCode -> Old_App_Code on web application installations) with the following code:



using CMS.Base;
using CMS.Forums;
using CMS.DataEngine;
using CMS.Helpers;

/// <summary>
/// Partial class that allows you to register custom handler methods and classes.
/// Adds the CustomForumGroupHandlers attribute to the partial class.
/// </summary>
[CustomForumGroupHandlers]
public partial class CMSModuleLoader
{
    /// <summary>
    /// Custom attribute class.
    /// </summary>
    private class CustomForumGroupHandlers : CMSLoaderAttribute
    {
        /// <summary>
        /// Called automatically when the application starts
        /// </summary>
        public override void Init()
        {
            // Assigns a handler to the Insert.After event for the ForumGroupInfo object type
            // This event occurs after the creation of every new forum group
            ForumGroupInfo.TYPEINFO.Events.Insert.After += ForumGroup_InsertAfterEventHandler;
        }

        /// <summary>
        /// Automatically creates a child forum for new forum groups
        /// </summary>
        private void ForumGroup_InsertAfterEventHandler(object sender, ObjectEventArgs e)
        {
            // Checks that the forum group was successfully created
            if (e.Object != null)
            {
                // Gets an info object representing the new forum group
                ForumGroupInfo forumGroup = (ForumGroupInfo)e.Object;

                // Creates the child forum object
                ForumInfo newForum = new ForumInfo() 
                {
                    // Sets the child forum's properties
                    ForumDisplayName = forumGroup.GroupDisplayName + " - General",
                    ForumName = forumGroup.GroupName + "_General",
                    ForumGroupID = forumGroup.GroupID,
                    ForumSiteID = forumGroup.GroupSiteID,

                    ForumOpen = true,
                    ForumModerated = false,
                    AllowAccess = SecurityAccessEnum.AllUsers,
                    ForumThreads = 0,
                    ForumPosts = 0
                };

                // Saves the child forum to the database
                ForumInfoProvider.SetForumInfo(newForum);
            }
        }
    }
}

To try out the functionality of the custom event handler, create a new forum group on any website:

  1. Open the Forums application.
  2. Click New forum group.
  3. Type a name into the Group display name field of the new forum group.
  4. Click Save.

The system automatically creates a child forum named after the forum group (with a ” - General” suffix).