Create and implement event receivers

Using event receivers you can hook into several predefined SharePoint site/web/list etc. events, get access to event information and run custom code when one occurs.

There’s a basic walkthrough with lots of useful information on MSDN, be sure to check it out.

I wouldn’t list all possible events and sources of events here, the URL above does a nice job in that. Basically you can create an event receiver by subclassing the appropriate class and overriding the self-explanatory virtual methods it provides. There are five classes you can use:

  • SPWebEventReceiver: provides events for SPSites and SPWebs.
  • SPListEventReceiver: events for SPLists and SPFields, basically to the schema.
  • SPItemEventReceiver: events for SPListItems, to the data.
  • SPEmailEventReceiver: one event for e-mail enabled lists and webs..
  • SPWorkflowEventReceiver: events for workflows.

Most implementations have two types of events: before and after events. This resembles Windows Forms or WPF programming, where you had Clicking and Clicked events. Before events occurs before the event takes place (before SharePoint updates the content database), run on the same thread as the event itself, and provides cancellation and access to the event data. You can access almost every piece of information that will be stored in the After property of the SPItemEventProperties class, except the new item’s (if any) id, which hasn’t been generated yet at this point.

After events lets you run your code after a specific event occurred. By default they run on a background thread, and there aren’t any guarantees that they’ll be runned by the time your page posts back to you. You can control this behavior by setting the synchronization state of your event receiver to synchronous. Then after events will run on the same thread as the event itself.

It’s easy to trigger a stack overflow with event receivers. Imagine that you’ve subscribed to the updating of an SPListItem, and set a property on the same list item from your event receiver. This’ll cause to recursively call the receiver again, until you run out of stack space. To prevent this, there’s a protected property called EventFiringEnabled. Just set it to false, and to true after you’re done. Note that this works only in your own event receiver subclass, not from the outside.

The before events are appropriate candidates for validation. And, if validation fails, you’ll definitely like to cancel further processing of the event. Event receivers provide a way for that. First, you’d like to set the Status of the SPItemEventProperties class to one of the values that indicates cancellation. This by itself won’t cancel the event, after you’ve done this you’ll need to set the Cancel property of this class to true. You can also provide an error message or redirect to another URL using the same class.

Manage a solution in Visual Studio 2010

Visual Studio has some nice built-in support for developing custom SharePoint solutions. I personally tend to use the SharePoint Module project template, so this post will describe its workings as well.

First the most straightforward: how to make a solution sandboxed/farm level? In the project properties there’s one called Sandboxed solution. Simply set it to true to make your solution sandboxed, otherwise false.

To customize the features which will be added to your package simply open the Package folder. It has a nice editor in which you can add and remove features in your solution.

To deal with assemblies just select the Advanced tab on the package editor surface. There you can add assemblies from your solution output, or from other locations as well. You can also specify if you want individual assemblies to get deployed to the GAC or just to the web application.

You can also map folders in your project to their counterparts in the SharePoint 14 folder (this is only allowed in farm level solutions). Just right click on your SharePoint project and select “SharePoint mapped folder” from the Add context menu. To deal with resources add a mapped folder to the SharePoint Resources folder, and put your .resx files in there. Make sure to set their Build Action to Content, otherwise you won’t be able to use them.

All of the settings I specified above will be merged into a single file called Manifest.xml. If you feel brave, you can edit this xml file by hand. You just need to enter  the package editor, select the Manifest tab, expand Edit options, and click on the link  starting Overwrite generated XML. Visual Studio will try to persuade you not to do so, but this change is reversible any time. If you clicked through these items, the package editor will be disabled, and you can edit the XML file by hand. The schema is pretty self-explanatory, so I wouldn’t describe it here.

Implement a dialog by using the Dialog Framework

Dialogs are a conventional way of notifying a user or prompting for input. Like them or not, SharePoint uses them a lot, so users are accustomed to them, thus there’s a high chance that you have to develop custom ones.

Fortunately there’s a simple entry point when you construct dialogs: the SP.UI.ModalDialog class. You can construct a dialog many ways, and show it using the showModalDialog function. There are a bunch of options you can pass in, such as the title of the dialog, the url of the content, callback function, etc. Here’s a brief list:

  • Title: the title of the dialog. If not specified, the target page’s title will be used. If used with custom html content, then the term ‘Dialog’ will be used.
  • x, y, width, height: the position and size of the dialog.
  • allowMaximize, showClose: show or hide these buttons, respectively.
  • showMaximized, autoSize: note the fantastic naming convention. Showmaximized indicates whether or not to show the dialog “full screen”, autoSize needs no comment.

The remaining properties are more important, so let’s review them here. If you want to use your custom HTML content, then you can pass a DOM element as the html parameter. Now since I mostly use jQuery to generate my HTML markup when it comes to dialogs, here’s a little trick to convert a jQuery object to make it usable for showModalDialog:

var html = “<div>My markup</div>”;
var htmlAsDomElement = $(html).get(0);

More interesting is the dialogReturnValueCallback parameter. You can pass in a function to be called when the user finishes with the dialog. Two parameters will be needed, one for the result (eg. closed, canceled, ok’d) and one for the return value (if any) of the dialog.

For a real hardcore in-depth introduction of SharePoint dialogs, check out this blog post.