Creating custom validation rules in our list field iterators

Last week we saw how to hide specific field controls or how to display them as read-only even on the edit form. In the current post I introduce a simple technique one can apply to create custom validation for SharePoint forms without InfoPath.

First, what are the main problems with the out of the box SharePoint form validation capability?

As written in the first post of this series about custom list field iterators, SharePoint 2010 made a large step to the right direction compared to its predecessor, WSS 3.0. One can define field level and form level validation rules using a syntax similar to the one used with calculated columns, based on values of other fields of the current item.

However, you can define only a single validation rule for your form having a single validation error message, and a single validation rule and error message for the fields. Furthermore, there is another serious limitation, namely one can validate only the basic field types (like text, date, numeric) and the same is true to the fields one can refer to in the validation rule.

It means, you are out of luck if you have to work with validation of lookup or user fields, managed metadata or even your custom field types.

In the validation rule you can refer to the fields of the current item, you cannot build validation rules based on field values of other, related items, custom user properties, not to mention accessing other systems, like CRM, 3rd party web services, etc.

Moreover, the validation error messages are static text, one can not built them up dynamically based on field values, for example.

I found that in real world applications customers need usually much more validation power.  All of these inflexibilities listed above lead me to create some kind of custom solution for validation. You can read another approach built on custom field types here, but in this post I illustrate the list field iterator based solution.

As you might know the BaseFieldControl class, the base class of all field controls implements the IValidator interface. In practice it means, you can use these field controls similar to standard ASP.NET validator controls.

But before working with them, we first have to get a reference to the field controls. So we extend our BaseListFieldIterator class – introduced in the previous part – with the GetFieldControlByName method. There might be multiple forms on the page, so just to be sure that the field control is within our list field iterator, we call the GetIteratorByFieldControl method and compare the ClientID values.

The SetValidationError method is to set the validation error for the specified field.

1. protected BaseFieldControl GetFieldControlByName(String fieldNameToFind)
2. {
3.     foreach (Control control in _formContext.FieldControlCollection)
4.     {
5.         if (control is BaseFieldControl)
6.         {
7.             BaseFieldControl baseField = (BaseFieldControl)control;
8.             String fieldName = baseField.FieldName;
9.             if ((fieldName == fieldNameToFind) &&
10.                 (GetIteratorByFieldControl(baseField).ClientID == ClientID))
11.             {
12.                 return baseField;
13.             }
14.         }
15.     }
16.     return null;
17. }
18.  
19. protected Microsoft.SharePoint.WebControls.ListFieldIterator GetIteratorByFieldControl(BaseFieldControl fieldControl)
20. {
21.     return (Microsoft.SharePoint.WebControls.ListFieldIterator)fieldControl.Parent.Parent.Parent.Parent.Parent;
22. }
23.  
24. protected void SetValidationError(String fieldName, String errorMessage)
25. {
26.     BaseFieldControl fieldControl = GetFieldControlByName(fieldName);
27.     fieldControl.ErrorMessage = errorMessage;
28.     fieldControl.IsValid = false;
29. }

Next we have to add the following code to our custom ListFieldIterator class.

1. protected override void OnLoad(EventArgs e)
2. {
3.     if (Page.IsPostBack)
4.     {
5.         Page.Validate();
6.         this.Validate();
7.     }
8. }
9.  
10. public void Validate()
11. {
12.     if (base.ControlMode != SPControlMode.Display)
13.     {
14.         // here comes the validation logic
15.     }
16. }

We will extend the Validate method to fulfill our fictitious business needs.

The validation messages are stored as constants:

1. public static class ValidationMessages
2. {
3.     public static readonly String TitleNotUnique = "Task title should be unique";
4.     public static readonly String UserBusy = "This user already has another task for this time";
5.     public static readonly String NoDateForAssignement = "A user can be assigned only if the start and due dates are specified";
6.     public static readonly String PredecessorsNotCompleted = "At least one of the predecessors is not yet completed";
7.     public static readonly String PredecessorSelfReference = "A task cannot be its own predecessor";
8.     public static readonly String DueDateEarlierThanStartDate = "Due date should not be earlier than start date ";
9.     public static readonly String CompletedTaskPercentage = "For a completed task the % complete should be 100";
10. }

Despite of the constant values used in the sample, it is easy to create dynamic messages as well. For example, you can define a message like "Task title ‘{0}’ is not unique", then substitute the current value when setting the validation error.

The first rule is to allow only unique task titles.

1. TextField titleField = GetFieldControlByName(SampleTaskListFields.Title) as TextField;
2.  
3. if (titleField != null)
4. {
5.     String title = titleField.Value as String;
6.  
7.     if (!String.IsNullOrEmpty(title))
8.     {
9.         if (ItemWithSameTitleExists(title))
10.         {
11.             SetValidationError(SampleTaskListFields.Title, ValidationMessages.TitleNotUnique);
12.         }
13.     }
14. }

We check the uniqueness through a CAML query, and use the GetFieldRefs helper method to build the value of the ViewFields property of the SPQuery instance.

1. protected bool ItemWithSameTitleExists(string title)
2. {
3.  
4.     SPQuery query = new SPQuery();
5.  
6.     query.ViewFields = GetFieldRefs(SampleTaskListFields.Title);
7.     // we should not check the ID in this case, as altering the title is not allowed
8.     // title will be validated only on new item creation
9.     // if title would be editable for existing items, then we should check
10.     // whether the ID is not the one of the current (edited) item
11.     // note, that CAML Eq for a Text field type is case insensitive
12.     query.Query = String.Format("<Where><Eq><FieldRef Name='{0}'/><Value Type='Text'>{1}</Value></Eq></Where>",
13.         SampleTaskListFields.Title, title);
14.  
15.     bool result = List.GetItems(query).Count > 0;
16.  
17.     return result;
18. }
19.  
20. private String GetFieldRefs(params String[] fieldNames)
21. {
22.     String fieldRefs = String.Concat(fieldNames.ToList().
23.         ConvertAll(fieldName => String.Format("<FieldRef Name='{0}'/>", fieldName)));
24.  
25.     return fieldRefs;
26. }

The next image shows the validator in action.

The comparison is case insensitive.

Yes, you are right it is nothing more than a custom implementation for the built-in Enforce unique values feature, but this one does not require indexed columns, and you have the chance to handle issues like leading / trailing spaces. For example, if you enable Enforce unique values, it won’t prohibit users entering ‘ Sample task 1  ‘ without any difficulties. If you don’t like this, you can trim the title parameter value and/or use Contains instead of Eq in the CAML query.

After this basic validation, let’s see a more tricky one. This one can be solved using standard field validation, although in this case it is more complicated “thanks” to the read-only Start date field when the task is not in the “Not Started” status.

1. DateTimeField startDateField = GetFieldControlByName(SampleTaskListFields.StartDate) as DateTimeField;
2. DateTimeField dueDateField = GetFieldControlByName(SampleTaskListFields.DueDate) as DateTimeField;
3.  
4. // if the task is not in 'Not Started' status, then we display the start date
5. // as read-only and value would be null
6. // in this case we should get the real value, stored in the item
7. DateTime? startDateValue = (startDateField.ControlMode == SPControlMode.Display) ? (DateTime?)Item[SampleTaskListFields.StartDate] : startDateField.Value as DateTime?;
8. DateTime? dueDateValue = dueDateField.Value as DateTime?;
9.  
10. if ((startDateValue.HasValue) && (dueDateValue.HasValue))
11. {
12.     if (dueDateValue.Value < startDateValue.Value)
13.     {
14.         SetValidationError(SampleTaskListFields.DueDate, ValidationMessages.DueDateEarlierThanStartDate);
15.     }
16. }

The illustration of the validation error:

This validation is again a simple one. We require 100% for % Complete when Status is Completed.

1. DropDownChoiceField statusField = GetFieldControlByName(SampleTaskListFields.Status) as DropDownChoiceField;
2. NumberField percComplField = GetFieldControlByName(SampleTaskListFields.PercentComplete) as NumberField;
3.  
4. bool checkForPredecessorStatus = false;
5.  
6. if ((statusField != null) && (percComplField != null))
7. {
8.     String statusFieldValue = statusField.Value as String;
9.     Double? percComplValue = percComplField.Value as Double?;
10.  
11.     if (statusFieldValue == TaskStates.Completed)
12.     {
13.         checkForPredecessorStatus = true;
14.         if ((!percComplValue.HasValue) || (percComplValue.Value != 1))
15.         {
16.             SetValidationError(SampleTaskListFields.PercentComplete, ValidationMessages.CompletedTaskPercentage);
17.         }
18.     }
19. }

The screenshot of the validation:

Before you leave the post unread thinking this technique provides no additional value for validation, let’s see some more advanced example.

Using the standard Tasks list you can set an existing task as its own predecessor. That is not very nice, and in this case I found no simple OOB SharePoint tool to prohibit that.

Using this technique, you can achieve the result as shown below:

1. MultipleLookupField predecessorsField = GetFieldControlByName(SampleTaskListFields.Predecessors) as MultipleLookupField;
2.  
3. if (predecessorsField != null)
4. {
5.     SPFieldLookupValueCollection predecessorsValue = predecessorsField.Value as SPFieldLookupValueCollection;
6.  
7.     if (predecessorsValue != null)
8.     {
9.         // a task can reference itself only in edit mode
10.         if (ControlMode == SPControlMode.Edit)
11.         {
12.             if (!predecessorsValue.TrueForAll(predecessor => predecessor.LookupId != ItemId))
13.             {
14.                 SetValidationError(SampleTaskListFields.Predecessors, ValidationMessages.PredecessorSelfReference);
15.             }
16.         }
17.         if (checkForPredecessorStatus)
18.         {
19.             if (!IsAllTasksCompleted(predecessorsValue.ConvertAll(predecessor => predecessor.LookupId)))
20.             {
21.                 SetValidationError(SampleTaskListFields.Status, ValidationMessages.PredecessorsNotCompleted);
22.             }
23.         }
24.     }
25. }

And in action:

The code above contains a check of predecessors when the task is to be set Completed. (The value of checkForPredecessorStatus computed earlier when validating % Complete.) We don’t want to allow that if there is at least on uncompleted predecessor. For the check we use the IsAllTasksCompleted method, passing the task ID of all of the predecessors as parameter.

1. private bool IsAllTasksCompleted(List<int> taskIds)
2. {
3.     SPQuery query = new SPQuery();
4.     query.ViewFields = GetFieldRefs(
5.         SampleTaskListFields.Id,
6.         SampleTaskListFields.Status);
7.  
8.     query.Query = String.Format("<Where><Neq><FieldRef Name='{0}'/><Value Type='Text'>{1}</Value></Neq></Where>",
9.                     SampleTaskListFields.Status, TaskStates.Completed);
10.  
11.     bool result = true;
12.     
13.     SPListItemCollection tasksNotCompleted = List.GetItems(query);
14.  
15.     foreach (SPListItem task in tasksNotCompleted)
16.     {
17.         if (taskIds.Contains((int)task[SampleTaskListFields.Id]))
18.         {
19.             result = false;
20.             break;
21.         }
22.     }
23.  
24.     return result;
25. }

The result of the validation is shown here:

Next, we want to allow to assign a user to the task if both start and due dates are set.

1. UserField userField = GetFieldControlByName(SampleTaskListFields.AssignedTo) as UserField;
2.  
3. if (userField != null)
4. {
5.     String userFieldValue = userField.Value as String;
6.  
7.     if (!String.IsNullOrEmpty(userFieldValue))
8.     {
9.  
10.         if ((startDateValue.HasValue) && (dueDateValue.HasValue))
11.         {
12.             if (startDateValue.Value <= dueDateValue.Value)
13.             {
14.                 SPFieldUserValue userValue = new SPFieldUserValue(Web, userFieldValue);
15.                 int? taskId = (base.ControlMode == SPControlMode.Edit) ? ItemId : (int?)null;
16.                 if ((userValue.LookupId != -1) && (UserIsBusy(userValue.LookupId, taskId, startDateValue.Value, dueDateValue.Value)))
17.                 {
18.                     SetValidationError(SampleTaskListFields.AssignedTo, ValidationMessages.UserBusy);
19.                 }
20.             }
21.         }
22.         else
23.         {
24.             SetValidationError(SampleTaskListFields.AssignedTo, ValidationMessages.NoDateForAssignement);
25.         }
26.     }
27. }

On the screenshot below, I “forgot” to set the start date, that is not allowed in this case.

Finally, using the method described in this post, we allow to assign the user for the task, if (s)he has no other assignment for that time interval. In this case we should ignore the task being edited when doing the validation.

1. protected bool UserIsBusy(int userId, int? taskId, DateTime startDate, DateTime dueDate)
2. {
3.  
4.     SPQuery query = new SPQuery();
5.     query.ViewFields = GetFieldRefs(
6.         SampleTaskListFields.Id,
7.         SampleTaskListFields.AssignedTo,
8.         SampleTaskListFields.StartDate,
9.         SampleTaskListFields.DueDate);
10.  
11.     // NOTE: you can add filter for Status Neq 'Completed' as well if you wish
12.     // I have not included that for the sake of simplicity
13.     if (taskId.HasValue)
14.     {
15.         // it is editing an existing task, so we should exclude the task itself
16.         query.Query = String.Format("<Where><And><And><Neq><FieldRef Name='{0}'/><Value Type='Integer'>{1}</Value></Neq><Eq><FieldRef Name='{2}' LookupId='TRUE' /><Value Type='Lookup'>{3}</Value></Eq></And>{4}</And></Where>",
17.                         SampleTaskListFields.Id, taskId.Value,
18.                         SampleTaskListFields.AssignedTo, userId,
19.                         BuildDateRangeOverlapFilter(startDate, dueDate));
20.     }
21.     else
22.     {
23.         // it is a new task, we don't have to check te task ID
24.         query.Query = String.Format("<Where><And><Eq><FieldRef Name='{0}' LookupId='TRUE' /><Value Type='Lookup'>{1}</Value></Eq>{2}</And></Where>",
25.                         SampleTaskListFields.AssignedTo, userId,
26.                         BuildDateRangeOverlapFilter(startDate, dueDate));
27.     }
28.  
29.     bool result = List.GetItems(query).Count > 0;
30.  
31.     return result;
32. }
33.  
34. protected String BuildDateRangeOverlapFilter(DateTime startDate, DateTime endDate)
35. {
36.  
37.     StringBuilder sb = new StringBuilder();
38.     sb.Append(String.Format("<And>{0}{1}</And>",
39.         BuildSimpleDateFilter(SampleTaskListFields.StartDate, endDate, "Leq"),
40.         BuildSimpleDateFilter(SampleTaskListFields.DueDate, startDate, "Geq")));
41.  
42.     return sb.ToString();
43.  
44. }
45.  
46. protected String BuildSimpleDateFilter(String dateFieldName, DateTime filterDate, String relation)
47. {
48.     String datePattern = "yyyy-MM-ddT00:00:00Z";
49.  
50.     return String.Format("<{0}><FieldRef Name='{1}'/><Value Type='DateTime'>{2}</Value></{0}>", relation, dateFieldName, filterDate.ToString(datePattern));
51.  
52. }

And that is the outcome of the validation in this case:

Note: Other validation possibilities for Person or Group field type are to check the number of users set (you can allow a single user or multiple ones using the standard tools, but you can not expect exactly three of them), or to check if the specified users are from a specific Active Directory group.

Although the technique illustrated in this post require coding and not so straightforward as specifying a simple formula on the UI, I hope you can use it  effectively if the customer requirements demand something more sophisticated.

You can download the sample application from here.