What's in this post:
- How to build a Event Handler in SharePoint 2010 from scratch
- How to leverage a custom error page when canceling an event
Example leveraged: This walkthrough builds an event handler that executes when a site is being deleted in a site collection. When such as action occurs, the handler cancels the action and redirects the user to a custom error page where it informs them that sites shouldn't be deleted, but rather they should be archived.
STEP 1) Create a new Visual Studio 2010 project. Use the Empty Project template and specify the .NET 3.5 framework:
STEP 2) Type the URL to the Site Collection you want to deploy your project to as well as specify you want to deploy as a full-trust solution:
STEP 3) In the newly created solution, open the Feature and the feature designer will appear. Change the Scope to Site. This will make it so the event handler will be deployed across the entire site collection:
STEP 4) Add the event handler to the project. Right click the project and choose Add, New Item…
Select the Event Handler item template:
Select which event you want the handler to listen for (for this demo, we're capturing the Site Deleting event under Web Events):
STEP 5) Add code to the event handler. Open the code file, and enter your logic. For example:
properties.Cancel = true;
properties.Status = SPEventReceiverStatus.CancelWithRedirectUrl;
properties.RedirectUrl = "/_layouts/CustomEventErrorHandler/CustomErrorPage.aspx"
In this example, the Site Deletion is terminated and the user is redirected to a custom error page. This is accomplished by specifying the Status property and assigning it to the CancelWithRedirectUrl enumeration within SPEventReceiverStates. Other options include:
- SPEventReceiverStatus.CancelNoError, cancel action but don't raise an error to the user
- SPEventReceiverStatus.CancelWithError, cancel action and show default error dialog box (default)
- SPEventReceiverStatus.CancelWithRedirectUrl, cancel error and redirect user to custom error page. Note that a RedirectUrl MUST be specified
- SPEventReceiverStatus.Continue, do not cancel the action, even if properties.Cancel is set to true…
To Setup the Custom Error Page, Continue… (otherwise Deploy)
STEP 6) Add new application page by right clicking the project, and choose Add, New Item. Select Application Page:
Notice it creates a Layouts "Mapped Folder" that gets packaged up in the Feature/Solution…
STEP 7) Add page verbiage and other logic. In my example, I add some language that describes to end users that they need to archive sites (through some external process) rather than delete them:
STEP 8) Deploy and test the new Feature. Right click the project, and click Deploy:
Note – this will automatically activate the feature on the Site collection specified in Step 2.
Now, attempt to delete a site within that Site Collection:
SO EASY!
Phil