Saturday, July 1, 2017

Introducing the Scissors Validation Framework

You may download the Scissors Validation Framework from GitHub.

Validations is an essential part of interactive software development. We can get away without it, but unexpected things may happen when a user starts entering unexpected data. Having said that, validation is an oft neglected part of the development process. It's rarely an interesting part of writing software, and when developer's fatigue starts to creep in, becomes the least prioritized task. The system works with or without it, so lazy developers see it as an optional component, not an essential one.

To help combat this repetitive task of implementing validations to data entry modules, I've developed this validations framework to automate the configurations required to validate each field. This handles both client-side scripts validation as well as server-side validation. As there are varieties of jQuery-based validation libraries available, the framework has the flexibility to use one's preferred library, or even custom solutions.

The primary goals of this framework are:
  1. to automate some aspects of page validation across an entire project, and
  2. to ensure these validations are uniform, making it easier to make project-wide changes
The framework has similarities to .NET's built-in StringValidatorAttribute and other similar attributes, and in fact I thought I had found an out-of-the-box solution to what I wanted, but alas, this attribute is usable only for custom configuration sections. It could not be used for our own custom codes.

To start, consider a class named Employee, containing basic employee information.

For this class, we define validation rules using the StringValidatorAttribute (and other corresponding attributes) of the validations framework. To apply size validations to the name fields, we define them as follows:

The above definition indicates that the FirstName field should be between 5 to 50 characters in length, inclusive, and is a required field, while the MiddleName field should be between 5 to 20 characters in length, inclusive, but this time is an optional field as the IsRequired property is not set.

All the validator attributes have the same first constructor argument: the FieldLabel. The FieldLabel is the friendly display name when referring to this property during validation operations. For StringValidatorAttribute, the second and third arguments define the minimum and maximum text lengths. There are other optional settings for the various attributes, like the IsRequired, which defines the property as a required input, among others.

Below is the entire Employee class with appropriate validator attributes defined.

This configures the validation rules to be used for each field in the data entry pages of our application.

Of note is IntValidationAttribute, whose minimum/maximum values are overridden internally as needed, depending on the scope of the Int type decorated. For example, if this attribute is decorating an Int16 property but was defined with a maximum value more than the maximum value of an Int16, internally the validator shall override the defined maximum to instead use Int16.MaxValue.

On the web page where we receive input for Employee details, place textboxes for each of the Employee fields. Place a button to trigger the validation on postback. Additionally, we add a Repeater control to display any validation errors found. We use BootStrap framework for the design.

First, let's check the server-side validations. Best practice is to validate on the server no matter how well written our client-side validations are written, as client-side validations is dependent on so many variables. To validate the inputs, we call the function ScissorValidations.Validator.Validate(), which accepts an instance of the Employee class (can be a new or existing instance) and the mapping definition Dictionary<String, Validator.FieldMap>.

The fieldMapping variable defines how the class properties map to the page controls. Each element in the map holds the name of the property, and the FieldMap, which holds the page control as well as it's value to be validated. The Validate() function returns all validation results found, which can be used as a data source for a repeater control, for example. If none are returned, then it means that the inputs passed validation based on the defined rules, and can now be safely saved.

As a shortcut, it is also possible to let the Validate() function auto-assign the validated values directly into the data class instance that was passed. This is to minimize the need to assign and perform any casting needed which were already done internally during the validation process. Note that this only passes any values deemed valid by the validation process. To enable this functionality, set the global setting ScissorValidations.Validator.Settings.CopyValuesOnValidate to true. For ASP.NET, this can be set during the ApplicationStart() event in global.asax as below.

Now for client-side validations. Scissors Validation Framework acknowledges that client-side validations can have many strategies, be it custom Javascript validations or other established frameworks like BootStrap Validations. Due to this, it is normally advisable to implement one's own implementor, which implements the IValidationImplementor interface. For simplicity, let us use a built-in implementor already in the framework named BootstrapValidationImplementor, found in the ScissorValidations.ValidationImplementors namespace. This implementor uses simple validation configurations based on the BootStrap Validation library.

To wire up the page input controls with the required attributes to work with BootStrap Validations, we use the function InitializeClientValidators(), which accepts another fieldMapping variable, but using a slightly different Dictionary definition. Additionally, generic types need to be defined for the data class type containing the validator attributes we need, as well as an implementor class like BootstrapValidationImplementor.

Similar to the fieldMappings on the server-side validation, the client-side requires mapping the data class properties to their corresponding page input control, but is simpler as it only requires the property name and the target control instance.

Shown in the top half is the plain BootStrap-designed row for the FirstName field. This is how a field would typically look like before the client-side validators are added. After the InitializeClientValidators() function has been called and the FirstName field has been found to contain a validator attribute, then the framework uses the provided implementor class to decorate the input tag with the necessary HTML attributes as required by BootStrap Validations library. The bottom half in the snippet above shows the new attributes added to the input tag with the rules for this field's validations.

In case the built-in implementor is not exactly right to your needs, or you are using a totally different client-side validation strategies, you may use your own implementor by implementing the IValidationImplementor interface. The snippet below shows the contents of the BootstrapValidationImplementor class, which you may base your own off of (each function handles the insertion of required attributes depending on their validator types).

And that sets up both client-side and server-side validations on an ASP.NET page.

There will be more validator attributes to be added in the future, as well as a few more implementors. If you like what you see and wish to make some suggestion, do leave a comment. To get the codes, you may download it from GitHub.