Print
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
Please refer to the Debugging Sitecore Custom Code article for basic debugging instructions.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 }
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