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.

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 simpler way. You can refer to the Global events (obsolete) topic to see the difference between the two approaches.

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, is an object that contains only properties and is used to store event data. It inherits from the System.EventArgs class.

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

Registering event handlers

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.DocumentEngine;
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
}
}
}

Events that you can handle

You can use the following 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.

•LogChange - allows you to alter how the system logs object changes for the purposes of staging and integration.

•<name>Info.TYPEINFO.Events - provides the same set of events as ObjectEvents, but specific for a particular object type, for example UserInfo.TYPEINFO.Events.

•ColumnTranslationEvents - contains handlers that you can use to store objects' IDs to ensure the IDs' translation during import/export and staging.

•RegisterRecords - using this handler you can provide additional information for your custom field translation.

•TranslateColumns - using this handler you can translate the field value using the provided info.

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

•LogChange - allows you to alter the way document changes are being logged.

•NewsletterEvents [Only available after applying hotfix 7.0.52 or newer]

•ResolveMacro - fired when all newsletter text macros are being resolved.

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

•ActivityEvents [Only available after applying hotfix 7.0.46 or newer]

•ActivtyLogged - fired immediately when on-line marketing activities of any type occur in the system. The event does not trigger for custom activities logged using the ActivityInfoProvider.SetActivityInfo method.

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

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

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

•Publish – fired when a document is being published.

•Archive – fired when a document is being archived.

•Action – fired when a workflow action step is being executed.

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

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

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 After handlers to make sure your 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/7_0/devguide/index.html?event_handlers_overview.htm