5.2. Event Handling

WSS v2 offered developers the ability to catch certain user actions in code and react programmatically. These user actions triggered a set of asynchronous events that happened after the user had completed the action. An example is the act of adding a document to a document library. A developer could catch the DocumentAdded event and perform some action. Unfortunately for v2 developers, all of the event handlers were "after-the-fact" handlers. You can't stop a user from performing an action with an event handler. Another limitation of v2 event handlers is that you can only catch events on document and forms libraries.

Fortunately for you, all of this has changed. Now, WSS v3 has a vastly increased number of events developers can take advantage of. These events include "before-the-fact" or synchronous events as well as "after-the-fact" or asynchronous events as illustrated in Figure 5-8. As a developer interested in catching SharePoint events, you are no longer limited to only document libraries and forms libraries. Now you have the ability to catch events on practically every list type that SharePoint offers, as well as at the site level, list, or library level, and at the individual file level. Combine the increase in available functionality of event handlers with Workflow and you'll really have a flexible system.

Figure 5.8. Figure 5-8

5.2.1. Receiving SharePoint Events

To catch SharePoint events at an item level, your classes must inherit from the SPItemEventReceiver base class. From this inheritance, your class will be able to take advantage of the methods shown in the following table.

You can also catch events at the List (SPListEventReceiver), Web (SPWebEventReceiver), Email (SPEmailEventReceiver), and Feature (SPFeatureReceiver) levels.

5.2.2. Write Code to Cancel an Item Deletion

Let's look at a sample event handler to help understand the core concepts behind handling events. Since your previous levels of functionality left you completely unable to prevent an action on a non-document-library list, in this example you'll stop someone from deleting an announcement. While you will be working with the AnnouncementsList type, the following table is a list of available list template types:

To find these list IDs and the IDs of additional list template types, navigate to the Features directory under the 12TEMPLATE folder on your SharePoint server. Find the folder for the list you are looking for in the Features directory and open the List Templates folder under that. If you were looking for the AnnouncementsList type, you'd navigate to C:Program FilesCommon FilesMicrosoft Sharedweb server extensions12TEMPLATEFEATURESAnnouncementsListListTemplates. Open the XML file in here to find the code represented by Listing 5-4. Pick out the Template ID Type value (Type = 104).

Example 5.4. Listing 5-4

Announcements.xml
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <ListTemplate
        Name="announce"
        Type="104"
        BaseType="0"
        OnQuickLaunch="TRUE"
        SecurityBits="11"
        Sequence="320"
        DisplayName="$Resources:core,announceList;"

Description="$Resources:core,announceList_Desc;"
        Image="/_layouts/images/itann.gif"/>
</Elements>

To create and use your sample event handler, you'll need to do two things. First, you'll need to create the code that will run whenever you catch your desired event. Then you'll need to create a Feature to activate your event handler. Features are described in more depth in Chapter 4, so you won't be focusing on this portion of the task in great detail.

Open Visual Studio and start a new C# Class Library project called EventHandlerExample1. Since event handlers are part of the object model, the first thing you'll need to do is to add a reference to the Microsoft.SharePoint namespace.

You're now ready to begin writing your code.

The CancelAnnouncementDeleteHandler class needs to inherit from the SPItemEventReceiver class to function, so next to the class name put: SPItemEventReceiver. This will give you access to the methods listed in the previous table. You are trying to prevent an item from being deleted, so you will be overriding the ItemDeleting method, as shown in Figure 5-9.

In the ItemDeleting method, you'll cancel the deletion before it happens. Your code should look like Listing 5-5.

Example 5.5. Listing 5-5

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;

namespace EventHandlerExample1
{
    class CancelAnnouncementDeleteHandler: SPItemEventReceiver
    {
        public override void ItemDeleting(SPItemEventProperties properties)
        {
            string HandledMessage = ("Announcements can not be deleted from
this list");
            properties.ErrorMessage = HandledMessage;
            properties.Cancel = true;
        }
    }
}

Figure 5.9. Figure 5-9

The next step in getting your event handler to work is to compile your DLL and deploy it to the GAC. Deploying an assembly to the GAC requires a strongly named assembly, so in the Project Properties dialog, click the Signing tab and check the box to sign the assembly, as in Figure 5-10. Be sure to create a new key file if you haven't already. Build the project and deploy it to the GAC by entering the following command into the SDK command prompt, as in Figure 5-11.

gacutil /i "C:Documents and SettingsAdministratorMy DocumentsVisual Studio 2005ProjectsEventHandlerExample1inDebugEventHandlerExample1.dll"

Verify successful deployment by finding your file in the C:Windowsassembly folder. Normally, this GAC deployment would be automated with post-build steps or batch files, but it is presented in manual detail here as a learning exercise.

Figure 5.10. Figure 5-10

Figure 5.11. Figure 5-11

5.2.3. Create a Feature to Enable the Event Handler

The next task is to create and deploy a Feature that activates your event handler.

Now go to your site and create an Announcements list and put a few items in it. I've done so with my Sample Announcements list. Select an item and try to delete it. You should get an error message that reads "Announcements can not be deleted from this list" (see Figures 5-15 and 5-16).

Figure 5.15. Figure 5-15

Figure 5.16. Figure 5-16