Global events

Global events allow you to execute custom actions when some CMS event occurs. For example, if a document is created in the CMS system, you can handle the corresponding event, get information about the new document and send its content by e-mail or use a third-party component to generate a PDF version of the document.

Handler classes

Modules with handlers contain classes with "Events" in their name, which provide the available handlers. They may also contain classes that store the handler arguments or handler results. The following are samples of classes that are available:

•<name>EventArgs - e.g. DocumentEventArgs, it is an object which contains only properties and is used to store event data. It inherits from the System.EventArgs class.

•<name>Events - e.g. DocumentEvents, it is a static class containing definitions of handlers for various events as static properties.

InfoBox_Note

Please note

If you are accustomed to using custom handler libraries, please note that these global events provide the same functionality in a much easier way. You can refer to the examples of the old handlers to see the difference between the two approaches.

Event handler registration

Registration of handlers for events can be performed by creating a custom class in the App_Code folder, which eliminates the need to add a dedicated handler library and update it when performing upgrades to new versions. The class needs to extend the CMSModuleLoader partial class and a new attribute must be added to it. In the Init() method of a private class representing the attribute, handlers can be assigned to the required events in the following format:

The definitions of the handlers can then be added directly into the attribute class as shown in the example below:

[C#]

using CMS.TreeEngine;
using CMS.SettingsProvider;

[CustomDocumentEvents]
public partial class CMSModuleLoader
{
    /// <summary>
    /// Attribute class that ensures the loading of custom handlers
    /// </summary>
    private class CustomDocumentEventsAttribute : CMSLoaderAttribute
    {
        /// <summary>
        /// Called automatically when the application starts
        /// </summary>
        public override void Init()
        {
            // Assigns custom handlers to the appropriate 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
        }
    }
}

Available events

The following list contains available event classes and their respective events. These events cover data management for both objects and documents.

•ObjectEvents - contains events fired upon any object change. Replaces the old CustomDataHandler. These events are fired for any object type in the system.

•Insert - fired upon the insertion of a new object.

•Update - fired upon the update of the existing object.

•Delete - fired upon the object deletion.

•GetContent - Provides the additional object content to the search indexer.

•<name>Info.TYPEINFO.Events - contains events that provide the same set of events as ObjectEvents, but specific for a particular object type, e.g. UserInfo.TYPEINFO.Events.

•DocumentEvents - contains events fired when changes are made to documents. These events relate to the published versions of documents, refer to WorkflowEvents for actions within editing of the documents under workflow. Replaces the old CustomTreeNodeHandler.

•Insert - fired upon insertion of a new document.

•InsertNewCulture - fired upon insertion of a new document culture version.

•InsertLink - fired upon insertion of a new document link.

•Update - fired upon update of any document.

•Delete - fired upon deletion of any document.

•Move - fired upon moving of any document.

•Copy - fired upon copying of any document.

•GetContent - provides additional document content to the search indexer.

•SystemEvents - contains general system events, replaces the old CustomExceptionHandler.

•Exception - fired when unhandled exception occurs.

•SecurityEvents - contains security and authentication events, replaces the old CustomSecurityHandler.

•Authenticate - fired upon user authentication.

•AuthorizeResource - fired upon security check for particular module permission.

•AuthorizeClass - fired upon security check for particular object type or document type permission.

•AuthorizeUIElement – fired upon permission check for particular UI element.

•WorkflowEvents – contains events related to specific workflow and versioning actions, replaces the old CustomWorkflowHandler.

•Approve – fired when the document is approved to the next step.

•Reject – fired when the document is rejected to a previous step

•Publish – fired when the document is being published.

The following events are related to document attachments:

•SaveAttachment – fired upon insertion or update of document attachment.

•DeleteAttachment – fired upon deletion of document attachment.

The following events are related to customization of document security:

•AuthorizeDocument – fired when security check for particular document is requested.

•FilterDataSetByPermissions – fired when the DataSet of documents is filtered according the document permissions.

The following events are specific to content locking within versioning.

•CheckOut – fired when the document is checked-out.

•CheckIn – fired when the document is checked-in.

•UndoCheckOut – fired when undoing the check-out is performed on the document.

The following events are specific to updating of a document version.

•SaveVersion – fired when the edited version of the document is updated.

•SaveAttachmentVersion – fired when the attachment of the edited version of the document is updated or inserted.

•RemoveAttachmentVersion – fired when the attachment of the edited version of the document is removed.

Application events

There are several sets of application events that you can leverage to customize the global behavior of the application, these are following:

•CMSSessionEvents – contains events related to session management of the application.

•Start – fired when the session starts

•End – fired when the sessions ends.

•CMSApplicationEvents – contains events related to the whole application run.

•Start – fired when the application starts. It is recommended to bind only the After handler to make sure you handler has all necessary data initialized.

•End – fired when the application ends.

•Error – fired when application error occurs. Similar to SystemEvents.Exception, except for that this one covers wider range of handling code.

•CMSRequestEvents – contains events related to each request done to the application.

•Begin – fired when the begin request method executes.

•End - fired when the end request method executes.

•Authenticate - fired when the authenticate request method executes.

•Authorize - fired when the authorize request method executes.

•MapRequestHandler- fired when the map request handler method executes.

•AcquireRequestState - fired when the acquire request state method executes.

Control and page events

The last set of events is related to the life cycle of pages and controls. These events have their respective handlers directly in the base classes of pages and controls. You can leverage them to programatically customize the UI without the need to modify the original code of the solution. Please note that these events are direct delegates and do not provide Before / After sub‑items.

•AbstractUserControl - contains events that are fired during processing of user controls.

•OnBeforeUserControlInit

•OnAfterUserControlInit

•OnBeforeUserControlLoad

•OnAfterUserControlLoad

•OnBeforeUserControlPreRender

•OnAfterUserControlPreRender

•OnBeforeUserControlRender

•OnAfterUserControlRender

•CMSPage - contains events that are fired within processing of the system pages.

•OnBeforePagePreInit

•OnAfterPagePreInit

•OnBeforePageInit

•OnAfterPageInit

•OnBeforePageLoad

•OnAfterPageLoad

•OnBeforePagePreRender

•OnAfterPagePreRender

•OnBeforePageRender

•OnAfterPageRender

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