Return to doc.sitecore.com

Using Events

You can subscribe to a number of default events in Sitecore V5. Please refer to the <events> section of the web.config file for the list of predefined events.

1.  Events Section Code

1 <!-- EVENT MAPS -->
2 <events>
3   <event name="data:updated" />
4
5   <event name="item:added"/>
6   <event name="item:adding"/>
7   <event name="item:copied"/>
8   <event name="item:copying"/>
9
10   <event name="item:deleted">
11     <handler type="Sitecore.Links.ItemEventHandler, Sitecore.Kernel" method="OnItemDeleted"/>
12     <handler type="Sitecore.Tasks.ItemEventHandler, Sitecore.Kernel" method="OnItemDeleted"/>
13     <handler type="Sitecore.Data.Indexing.ItemEventHandler, Sitecore.Kernel" method="OnItemDeleted"/>
14   </event>
15
16   <event name="item:deleting"/>
17   <event name="item:moved"/>
18   <event name="item:moving"/>
19   <event name="item:renamed"/>
20
21   <event name="item:saved">
22     <handler type="Sitecore.Links.ItemEventHandler, Sitecore.Kernel" method="OnItemSaved"/>
23     <handler type="Sitecore.Tasks.ItemEventHandler, Sitecore.Kernel" method="OnItemSaved"/>
24     <handler type="Sitecore.Data.Indexing.ItemEventHandler, Sitecore.Kernel" method="OnItemSaved"/>
25   </event>
26
27   <event name="item:saving"/>
28   <event name="item:sortorderchanged"/>
29   <event name="item:templateUpdated" />
30   <event name="item:versionAdded" />
31   <event name="item:versionAdding" />
32   <event name="item:versionRemoved" />
33   <event name="item:versionRemoving" />
34
35   <event name="publish:begin" />
36   <event name="publish:end" />
37   <event name="publish:fail" />
38
39   <event name="security:loggingIn" />
40   <event name="security:loggedIn" />
41   <event name="security:loggingOut" />
42   
43   <event name="security:loggedOut">
44     <handler type="Sitecore.Sites.SiteContext, Sitecore.Kernel" method="OnLoggedOut" static="true"/>
45   </event>
46   
47   <!-- Example (note: method must be compatible with the EventHandler delegate)
48   <event name="example">
49     <handler type="Sitecore.Example, Sitecore.Kernel" method="OnExample"/>
50   </event>
51   -->
52 </events>

Event names are self-evident. If the verb is in the continuous form, it means that the event is dispatched before operation is performed, and the rest of the events are dispatched after the operation is completed.

 

As you can see, there's a large number of events, and some of them already have subscribers out of the box. Sitecore uses its own events to provide some of the functionality (Realtime cheking for broken links is a good example).

2.  Handling Events

This section describes how to handle an event.  As an example, we subscribe the publish:end event, which is raised when Sitecore completes the publishing process.

2.1.  Event handler implementation

1 public void OnPublishEnd(object sender, EventArgs args)
2 {
3    // 'publish:end' event provides one argument : instance of
4    // Sitecore.Publishing.Publisher class performing the actual publish.
5    Publisher publisher = Event.ExtractParameter(args, 0) as Publisher;
6
7    // Make sure that we were able to extract the publisher from event
8    // An exception is thrown otherways.
9    Error.AssertObject(publisher, "Publisher");
10
11    // Write publish information into the log.
12    Log.Info(string.Format(
13                "Publish completed. Language: {0}, Target database: {1}",
14                publisher.Options.Language.Name,
15                publisher.Options.TargetDatabase.Name),
16       this);
17 }

2.2.  Handling Event

To subscribe to the publish:end event, we need to modify the web.config file in the following way:

 

<event name="publish:end">

  <handler type="Sitecore.Sample.EventHandler, UsingEventsSample" method="OnPublishEnd" />

</event>

 

and then implement the event handler named OnPublishEnd. The method should match the regular EventHandler delegate signature.

2.3.  Event Arguments

Each event provides its own set of arguments. As described in the previous chapter, the  publish:end event passes the Sitecore.Publishing.Publisher class which performs the actual publishing. In our example, we write related information (the publishing language and the target database) to the Sitecore log.

 

The following table shows the parameters available in each predefined Sitecore event.  

Event Name

Parameter index

Parameter type

Description

data:updated

 

 

Not used by Sitecore at the moment

item:added

0

Item

Added Item

item:adding

0

String

Name of the item being added

 

1

ID

ID of the item being added

 

 2 

Item

Parent item of the item being added

item:created

0

ItemCreatedEventArgs 

Contains instance of created item

item:creating

0

ItemCreatingEventArgs

Contains item ID, name, master and template IDs, parent item

item:copying

0

Item

Item being copied

 

1

Item

Copy destination

 

2

String

Result item name

 

3

ID

Result item ID

 

4

Boolean

Shows whether it is a recursive copy (including children) or not

item:copied

0

Item

Source item (Item that was copied)

 

1

Item

Result item (Result of copy operation)

item:deleted

0

Item

Deleted item

 

1

ID

Parent item ID

item:deleting

0

Item

Item being deleted

item:moved

0

Item

Result Item

 

1

ID

ID of the old parent

item:moving

0

Item

Item being moved

 

1

ID 

ID of the old parent 

 

 2 

ID 

ID of the new parent. This parameter is available in CMS 6.4.1 Update-4 and later. 

item:renamed

0

Item

Result item

 

1

String

Item name before renaming

item:saved

0

Item

Saved item

item:saving

0

Item

Item being saved

item:sortorderchanged

0

Item

Sorted item

 

1

String

Old sortorder value

item:templateUpdated

0

ID

ID of the item being changed

 

1

DataManager

Instance of the datamanager class handling the template

item:versionAdded

0

Item

Item new version was added to

item:versionAdding

0

Item

Item new version is being added to

item:versionRemoved

0

Item

Item with version been removed

item:versionRemoving

0

Item

Item with version being removed

publish:begin

0

Publisher

Instance of publisher class performing the actual publish

publish:end

0

Publisher

Instance of publisher class performing the actual publish

publish:fail

0

Publisher

Instance of publisher class performing the actual publish

 

1

Exception

Exception that resulted in publish failure

security:loggingIn

0

UserItem

User logging in

security:loggedIn

0

UserItem

User that logged in

security:loggingOut

0

UserItem

User that logs out

security:loggedOut

0

UserItem

User that logged out

 

Although the parameters for the predefined events are defined in the documentation, the Visual Studio debugger can also provide information about parameters passed to an event. Set a breakpoint in your code and inspect the instance of EventArgs to see what parameters it has. Then you can extract the one you need using the Event.ExtractParameter() method.

 

You can also use the following snippet to log the event and its arguments:

2.4.  Event Arguments Code

1 public void LogEvent(object sender, EventArgs args)
2 {
3    SitecoreEventArgs scArgs = args as SitecoreEventArgs;
4    StringBuilder result = new StringBuilder();
5    if (scArgs == null)
6    {
7       result.Append("Failed to cast EventArgs to SitecoreEventArgs");
8       return;
9    }
10
11    result.Append("Event: " + scArgs.EventName + ". ");
12    foreach(object parameter in scArgs.Parameters)
13    {
14       result.Append(string.Format("Parameter: "));
15       result.Append(parameter.ToString());
16       result.Append(".");
17    }
18    Log.Info(result.ToString(), this);
19 }
Please refer to the Debugging Sitecore Custom Code article for basic debugging instructions.

2.5.  Cancelling Operations

When handling an event which takes place before the actual operation is performed, you can choose to cancel the operation. The following handler will prevent any Items from being moved away from the "UntouchableFolder".  

 

public void OnItemMoving(object sender, EventArgs args)

{

   // get the item that is being moved

   Item item = Event.ExtractParameter(args, 0) as Item;

   if (item != null)

   {

      // If item is moved from the 'UntouchableFolder'

      // then cancel the operation.

      if (item.Parent.Name == "UntouchableFolder")

      {

         ((SitecoreEventArgs)args).Result.Cancel = true;

      }

   }

}

 

2.6.  Subscribing to Events at Runtime

You can also subscribe to the Events at runtime instead of modifying the web.config file:  

 

 

//Subscribe 'OnItemMoving' method to the item:moving event

Event.Subscribe("item:moving", new System.EventHandler(this.OnItemMoving));

3.  Defining Your Own Events

You may not only subscribe to the existing events, but also define your own events. This can be useful for both Sitecore module developers (providing the same level of extensibility as Sitecore itself) and the solution developers (using own events to implement business logic and design loosely coupled components).

 

Say, we want to fire an event when we finish handling the publish::end event. We will name the event ”publish:end:handled” and subscribe to it with another handler.

 

First, we will modify the OnPublishEnd handler method to raise the ’publish:end:handled’ event once the original ’publish:end’ event is handled.

 

// Raise the 'publish:end:handled' event and pass two

// event parameters

Event.RaiseEvent("publish:end:handled", publisher, this);

 

Then, to make this extensible, we will create a new event definition in the web.config and subscribe to this event.

 

<event name="publish:end:handled">

  <handler type="Sitecore.Sample.EventHandler, UsingEventsSample" method="OnPublishEndHandled" />

</event>

 

Finally, we will implement the event handler itself:

 

public void OnPublishEndHandled(object sender, EventArgs args)

{

   object handler = Event.ExtractParameter(args, 1);

   Log.Info(string.Format(

         "publish:end event was handled by instance of the {0} class",

         handler.GetType().Name),

      this);

}

 

The logs then display lines similar to the following:

 

ManagedPoolThread #18 15:05:06 INFO  Publish completed. Language: en, Target database: web

 

ManagedPoolThread #18 15:05:12 INFO  publish:end event was handled by instance of the EventHandler class

 


Download Example
Click here to download ready sample source code.