Print

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.

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

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

1.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	ID	ID of the master or template used to create new item
	3	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:

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

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

      }

   }

}

 

1.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));