Handling global events

Global events allow you to execute custom code whenever specific actions occur within the system. Events can be raised as a result of both user interaction and the logic of the application itself (default or custom). When you assign a method as a handler for an event, the system automatically executes the code whenever the corresponding action occurs.

For example, when a new page is added to your website, you can use an event handler to load the page’s data, send out the content by e-mail, and use a third-party component to generate a PDF version of the page.

Assigning handlers to events

Use code in the following format to register handlers for global events:

<event class>.<event action>.<event type> += <handler method name>

  • Event class – event classes are containers of events related to groups of functionality
  • Event action – represents a specific action that occurs within the system
  • Event type – determines when exactly the event takes place, typically Before or After the action. Some actions only have one type: Execute

For example:

DocumentEvents.Update.After += Document_Update_After;

The event handlers provide parameters derived from EventArgs, which you can use to access data related to the action that occurred. The exact type of the parameter depends on the event.

For full information about the available event classes, actions, event types and handler parameters, see: Reference - Global system events

You need to register event handlers at the beginning of the application’s life cycle. Choose one of the following options:

  • When initializing custom modules – override the OnInit method of your module class.
  • During the initialization process of the application itself – use the CMSModuleLoader partial class in the App_Code folder.


The following steps describe how to register methods as global event handlers in the App_Code folder:

Note: Registering event handlers using the CMSModuleLoader class only works in the App_Code folder of the Kentico web project (CMS or CMSApp). If you wish to register handlers in a separate assembly (custom project), you need to use the custom module approach.

  1. Open your project in Visual Studio.
  2. Create a class file in the App_Code folder (or CMSApp_AppCode -> Old_App_Code on web application projects).
  3. Add a using statement for the CMS.Base namespace.
  4. Extend the CMSModuleLoader partial class.
  5. Create a new class inside CMSModuleLoader that inherits from CMSLoaderAttribute.
  6. Add the attribute defined by the internal class before the definition of the CMSModuleLoader partial class.
  7. Override the Init method inside the attribute class and assign handler methods to the required events.

using CMS.Base;
using CMS.DocumentEngine;

public partial class CMSModuleLoader
    /// <summary>
    /// Attribute class that ensures the loading of custom handlers.
    /// </summary>
    private class CustomDocumentEventsAttribute : CMSLoaderAttribute
        /// <summary>
        /// The system executes the Init method of the CMSModuleLoader attributes when the application starts.
        /// </summary>
        public override void Init()
            // Assigns custom handlers to events
            DocumentEvents.Insert.After += Document_Insert_After;
            DocumentEvents.InsertLink.Before += Document_InsertLink_Before;

        private void Document_Insert_After(object sender, DocumentEventArgs e)
            // Add custom actions here

        private void Document_InsertLink_Before(object sender, DocumentEventArgs e)
            // Add custom actions here

See the child pages in this chapter for examples of event handling.