Knowing the best practices of setting up field and item validations can also help improve both the content authoring and developer experience.
In this blog post I will show you the basics of setting up field and item validation and also demonstrate the process of building a custom field and item validator.
The example I am going to show you is based on events for a fictitious company. Basic requirements for events are that these events will be queried and retrieved back in a list on a web page, which will enable the event to be selected from a list and clicked on in order to show a more detailed view of the event. With these basic requirements, I create my events template as seen below:
There are many fields but the required fields we need specifically validated are the following:
- Start Date
- End Date
- Location Site
- Location City
- Location State
- Location Country
- Event Type
To set up the field to be required, using start date as an example, I click on the start date field definition item and in the validation rules section I double-click on required to bring the value to the right in the treelist. I do this for quick action bar, validate vutton, validator bar, and workflow treelist fields. This ensures that the content author will visibly see where the required fields are in the content editor so they know they need to be filled in. I make sure to do this for the all of my required fields above in my bulleted list for my events template.
Validation Rules Section in Field Definition Item
Now, when I create a new event item based on my events template I will begin to see the validation come to life in the content editor.
When I right-click in the quick action bar and check the validation rules button, I can then see my event item is denoted as red indicating that the items has validation errors. In addition, if I hover over the red icon I can see what those validation errors are:
Quick Action Bar Validation
When I look over in the fields area I can see the validation bar is red next to the fields that I setup to be required.
In addition, the validation bar details are also in the upper-right hand corner indicated by red icons that give detailed information when hovered over:
Validation Bar Details
Lastly, if I click on the review tab in the contextual ribbon and then click on the validation button in the proofing chunk then I can also see what validation errors I have for this item.
Validation Button Details
Ok, now that I have setup the fields to be required, I want to ensure the content euthor cannot save the item unless they are filled in (not including start date and end date). To do this, I will use the location site field as an example. I click on the field definition item in the events template and will use the validation field and validation text field to further enhance my validation for the event item. I add in a regular expression into the validation field and the text I want to display to the content author if the input in the field doesn’t match my regular expression. The regular expression I use simply validates that the field is not blank.
Validation Fields in Data Section
After making the settings to the location site field definition item, if I try to save the item without filling in the location site field I get this popup first:
When I click on the “OK” button I get the next popup:
Enter Value Into Field To Save Item
When I click the “OK” button the page did not save and I am still able to see the red validation bar to the left of my location site field. Unless we setup a regular expression to validate the field the item will still be able to be saved by the content author as the default behavior of adding required item validation to the field. However, you will just get the first popup regarding critical errors, red icons, validation bars, etc. but still be able to save the item. Again, to stop the item from being saved we must add in the regular expression into the validation field in the field definition item along with a message to the user why they can’t save the item in the validation text field. I did not setup the start date and end date to be required because I am going to do some custom field and item validation with those fields next.
For the event start date and end date I want to ensure that the user always puts in an end date that is equal to or greater than the start date. In this case, we are not going to stop the user from saving but merely continue to display the red icons in the quick action bar and validation bar and also display a user friendly message in the validate button details area for the content author.
I referred to the following blog post by John West to help me with understanding of and development of a custom item and field validator that specifically was to validate that the value of one date time field follows another in Sitecore, and you can find that blog post here. To my surprise, it was pretty easy to build and integrate a custom field and item validator and you only need to build it once for a field item validator while still getting a 2-for-1 payout as it will function as a custom item validator as well.
To start, I created the following SubsequentEndDateValidator class:
If you want the custom validator to work with the validator button then you have to add the serializable attribute to the class in addition to explicitly defining the constructors. Unless I did that, the validator button would provide an exception when clicking on the validator button and attempting to view the details of the validation errors. As you can see in the method evaluate(), we are getting the item and the start and end date fields and if the end date is not greater than the start date then we display a message to the user. In this case, we want to return a validator result. There are several which can be returned which are as follows:
Of those mentioned above, assigning to FatalError is the only one that will stop the user from saving the item until error is resolved. In my case, I want the user to know there is a critical error but not stop them from saving the item so I chose ValidatorResult.CriticalError.
Now that I have my class put together I just need to register it with Sitecore to be able to be chosen as a validation rule. To do this I simply go to /sitecore/system/Settings/Validation Rules where I can see the validation rules that are currently in place. I want to add my new custom validation rule as a field validator so I open up /sitecore/system/Settings/Validation Rules/Field Rules folder and insert a validation rule item named “End Date Greater Than Start Date”. I drag and drop it into the /sitecore/system/Settings/Validation Rules/Field Rules/Common folder.
Field Validation Rules In Content Tree
Now I just need to fill in some basic data to register my custom validator with Sitecore for use:
Fields in Validation Rule
Since I also want to have this as an item validation rule as well I duplicated this validation rule and placed in the /sitecore/system/Settings/Validation Rules/Item Rules/Item folder.
Now, in __Standard Values for the events template I scroll down to the Validation Rules section for the item and click on edit button for validation button validation rules, which runs when clicking the validation ribbon button. I clicked on edit and added in my custom item validator in the /sitecore/system/Settings/Validation Rules/Item Rules/Item folder.
Validation Button Validation Rules in Standard Values
Now when our content author clicks the validator button, our custom item validator will give them the details of the validation error.
Lastly, I want to make sure that the end date field (not start date) is assigned this validator as well so I open up the field definition item for the end date in the events template and assign it the custom field validator in the /sitecore/system/Settings/Validation Rules/Field Rules/Common folder. Again, I assigned it in the validation rules section to quick action bar, validate button, validator bar, and workflow.
Field Validation Rules for End Date
Now we can test out our custom field and item validation with a new event item. I create a new event item and fill in the previous required fields for location site, location city, location state, location country and event type. Once those are filled in, I click and can save but I still have critical errors because I need to fill in the start date and end date, which are required fields. I fill in the start date and end date, but with the end date before the Start date and try to save:
End Date Preceding the Start Date
The item will save because as you remember in our custom validator we did not tell Sitecore to stop the user from saving by assigning ValidatorResult.FatalError. Hence, the content author can save but the field custom validator has kept the red validator bar on because the end date is preceding the start date, which is what I wanted. This is the custom field validation taking place before your eyes:
Custom Field Validation Is Validating End Date
If we now click on the validate button in the review tab of the ribbon in the proofing chunk we can see the details. This is the custom item validation taking place before your eyes:
Item Validation Results of Event Item
Once we change the end date value to a date that is greater than or equal to the start date and save the item the quick action bar changes from red icon to no icon there, the validator bar does not light up next to fields and the icon in the upper right hand corner turns green, but most importantly the details of the validation button give us the “OK” to feel that content comforting feeling as a content author:
All Green Lights Go Using Custom Validation
Using this particular approach with field and item validation in your daily Sitecore development will make you stand out as a customer-focused architect or developer. However, it will also save you time in your daily Sitecore development. For instance, if you make fields required for a content author then you know they must fill them in to save the item or if they are being validated up front with regular expressions then you know what kind of data you are getting from Sitecore and there is less ambiguity about the type of data you need to check for in your code come development time. In my experience, it pays to take the time up front to do Sitecore field and item validation to save you time during your development process. One last note, field and item validation should be based on business requirements and not every template may need validation.
All in all, custom validation is a win-win for content authors and Sitecore developers. Content authors dig it and it helps us Sitecore developers be more productive. Once you get the hang of it you will be scratching your head why you never did in the past. Happy coding!