Today I would like to show you, how you can use event receivers to check documents / items in a list and give the user immediately a feeback about an error, while he is still in the edit form of the item / document.
That can be useful for users, because they don't leave the edit form and can correct the error immediately without opening the edit mask again.
We start with an
empty SharePoint Project in Visual Studio 2010.
Set a project name ("
SPProject"), then provide the url and set the trust level ("
Farm solution").
The first step is to add the list definition with list instance to our project. That will be our list, where the event receiver will be listen on. Right-click the project name in the project explorer and choose
"Add" ->
"New Item".
From the list select
"List Defintion" and set a name for it ("
ListDefinition"), then press
"Add".
On the next screen you have to enter a name for the list definition ("
SPProject - ListDefinition"). Also you have to choose, which type the list should be. In my case it was a document library, but you can use other types as well. Ensure that the box
"Add a list instance for the list definition" is ticked.
After we have added the list defintion, we can add our event receiver. The event receiver will check our doucment and return an error to the edit form, when the item / document is not ok. So we right-click again on the project name in the project explorer and choose
"Add" ->
"New Item" again.
Now we choose
"Event Receiver" from the list and set again a name ("
EventReceiver").
On the next screen, we have to decide, which type of event receiver we would like to have. We want the event receiver to check the items of a list - so our choice is
"List Item Events".
Then we have to tell SharePoint on which list the event receiver should listen. That is our created list instance from our list definition ("
SPProject - ListDefinition").
The last point we have to decide, when the event receiver should start its work. We select
"An item is being added".
In the file "EventReceiver.cs" we can add now our code, our logic to check the item / document.
I keep it simple for this example. I will only check if the title property starts with the word "SharePoint", otherwise I want to give an error message to the user. You can put in there more complex logic according to your needs.
Open the
"EventReceiver.cs" and search for the method
"ItemUpdating". Overwrite the method with your code:
/// <summary>
/// An item is being updated.
/// </summary>
public override void ItemUpdating(SPItemEventProperties properties)
{
try
{
base.ItemUpdating(properties);
// ensure that the code will be executed only once
if ((properties.AfterProperties["vti_sourcecontrolcheckedoutby"] == null && properties.BeforeProperties["vti_sourcecontrolcheckedoutby"] != null) || (properties.AfterProperties["vti_sourcecontrolcheckedoutby"] == null && properties.BeforeProperties["vti_sourcecontrolcheckedoutby"] == null))
{
// check title property
if (properties.AfterProperties["vti_title"].ToString().StartsWith("SharePoint") == false)
{
// redirect
properties.RedirectUrl = @"EditForm.aspx?"
+ "Mode=Upload"
+ "&CheckInComment="
+ "&ID=" + properties.ListItem.ID
+ "&RootFolder=%2Fsites%2FIT%2FLists%2FSPProject-ListInstance1"
+ "&IsDlg=1"
+ "&ContentTypeId=" + properties.ListItem.ContentType.Id
+ "&IsDlg=1";
properties.Status = SPEventReceiverStatus.CancelWithRedirectUrl;
}
}
}
catch (Exception exp)
{
throw exp;
}
}
I use the property
"vti_sourcecontrolcheckedoutby" to ensure that the code is executed once and nor multiple times. If you have enabled versioning in your list, the event will be fired muliple.
Then I use the AfterProperties to check the title. If the check fails, SharePoint should redirect the user to a specific url. We set the url to our editform.aspx of the list.
Note: You have to check the bold marked area in the code (RootFolder parameter). You have to change this to your list url!
Now we can start the solution. Navigate to the list, add an item and edit the properties afterwards. You will see that the title have to start with the word "SharePoint", otherwise the popup comes up again when saving.
But we still have no error displayed to the user. The user would be confused now, because he don't knows what is wrong and why he cannot save the properties.
To display an error on the editform.aspx of the list, we create a simple visual webpart.
We add another item to our project via right-click on the project name in the project explorer.
Select "Visual WebPart" from the list and set a name ("
VisualWebPart").
To the visual webpart we add just a label ("
Label1") from the toolbox (
"VisualWebPartUserControl.ascx").
In my solution I did some small changes to the label, like red color, another font, cleared the text property of the label etc, but this is up to you, how you design the label.
Now we open the code-behind file
"VisualWebPartUserControl.ascx.cs" and modify the Page_Load method.
protected void Page_Load(object sender, EventArgs e)
{
string ErrorMessage = System.Web.HttpUtility.ParseQueryString(System.Web.HttpContext.Current.Request.Url.Query).Get("error");
this.Label1.Text = ErrorMessage;
}
Explanation:
We use the HttpUtility class to get the parameter "error" from the current url. The paramter "error" we will use later for our custom error message.
The content of the error parameter we put in our label text property.
Now we have our webpart for displaying the error message, but we still have to put in the editform.aspx of our list.
Therefore we open the file
"schema.xml" of our list definition and search for the
"<Forms>" section in it.
It should similar look like this:
Now we create our custom editform.aspx by creating a new <Form> from type "EditForm". Give a own name ("
MyEditForm.aspx") and set default = true:
Code:
<Form Type="EditForm"
SetupPath="pages\form.aspx"
WebPartZoneID="Main"
Url="Forms/MyEditForm.aspx"
Default="TRUE">
<WebParts>
<AllUsersWebPart WebPartZoneID="Main" WebPartOrder="0">
<![CDATA[
]]>
</AllUsersWebPart>
</WebParts>
</Form>
Now we have a custom editform.aspx, but we still have to put our webpart in it. Actually we have the same editform as the standard one. Open the file "VisualWebPart.webpart" from the project explorer.
Copy the complete code except the first line ("<?xml version....>) and paste it in the CDATA area in the schema.xml.
Your form code in your schema.xml should look like this now:
Code:
<Form Type="EditForm"
SetupPath="pages\form.aspx"
WebPartZoneID="Main"
Url="Forms/MyEditForm.aspx"
Default="TRUE">
<WebParts>
<AllUsersWebPart WebPartZoneID="Main" WebPartOrder="0">
<![CDATA[
<webParts>
<webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
<metaData>
<type name="SPProject.VisualWebPart.VisualWebPart, $SharePoint.Project.AssemblyFullName$" />
<importErrorMessage>$Resources:core,ImportErrorMessage;</importErrorMessage>
</metaData>
<data>
<properties>
<property name="Title" type="string">VisualWebPart</property>
<property name="Description" type="string">My Visual WebPart</property>
</properties>
</data>
</webPart>
</webParts>
]]>
</AllUsersWebPart>
</WebParts>
</Form>
Now we have embedded the webpart in our custom editform.aspx.
We have to tell the event receiver, that it should redirect to our new custom editform.aspx ("
MyEditForm.aspx") and we have to add the error parameter to our url.
Navigate back to the event receiver code file ("
EventReceiver.cs") and modify the redirect url:
properties.RedirectUrl = @"MyEditForm.aspx?"
+ "Mode=Upload"
+ "&CheckInComment="
+ "&ID=" + properties.ListItem.ID
+ "&RootFolder=%2Fsites%2FIT%2FLists%2FSPProject-ListInstance1"
+ "&IsDlg=1"
+ "&ContentTypeId=" + properties.ListItem.ContentType.Id
+ "&IsDlg=1"
+ "&error=Error in Title - Must start with SharePoint";
Changes in code are marked in bold.
We changed the aspx file from "EditForm.aspx" to
"MyEditForm.aspx" and added the
parameter "error" with a custom error message.
Let's start the solution now. Navigate to the list, add an item and edit the properties afterwards. Click "Save" with an empty title. Now you should get the error message:
If you enter a text beginning with the word "SharePoint" in the title property the popup will disappear.
Hope you enjoyed this lesson. :-)
