Creating Validator Controls for the CheckBox and CheckBoxList

Introduction

There may be times, however, when you need to provide validation for a CheckBox or CheckBoxList. Many Web pages with Terms of Service include a CheckBox titled "I agree to the above terms" that must be checked before continuing. Likewise, a Web Form may contain a set of options in the form of a CheckBoxList. Perhaps the user is required to check at least one of these options before continuing. To provide such validation, we have three choices:

1. Forgo any sort of validation Web control semantics and perform the validation check using code on postback. The downside of this is that it breaks from the standard validation control metaphor and requires extra effort to include client-side validation.
2. Use the CustomValidator control and define our own server-side and client-side validation logic. The benefit of this approach is that it adheres to the validation control metaphor; however, the validation logic is tightly bound to the ASP.NET page, meaning that the server-side and client-side validation must be replicated on all pages that need to validate a CheckBox or CheckBoxList. (See Using the CustomValidator Control for more information on this topic.)
3. Create a custom, compiled validation server control that provides the functionality needed. The benefit of this approach is that we have a reusable, easily deployable custom server control that adheres to the validation control metaphor. Unfortunately, this option requires the most upfront code/effort.

The server controls provided in this article were designed using Visual Studio 2005 and the .NET Framework 2.0's base class libraries; consequently, they will only work in ASP.NET 2.0 applications. If you are still using ASP.NET 1.x, check out Creating a Validation Control for CheckBoxLists. Alternatively, you may adapt the code presented here to work in ASP.NET 1.x.

Creating CheckBox and CheckBoxList Validators in ASP.NET 1.x
The server controls examined in this article were designed using Visual Studio 2005 and the .NET Framework 2.0's base class libraries; consequently, they will only work in ASP.NET 2.0 applications. If you are still using ASP.NET 1.x, check out Creating a Validation Control for CheckBoxLists. Alternatively, you may adapt the code presented here to work in ASP.NET 1.x.

Understanding the ASP.NET Validation Workflow

In a short while we'll create our own custom validation Web controls for validating a CheckBox and CheckBoxList. These custom classes will inherit the BaseValidator class, overriding the following methods:

• EvaluateIsValid() - this is the only BaseValidator class that must be overridden. It returns a Boolean value that indicates the validation control's validity.
• ControlPropertiesValid() - this method returns a Boolean indicating if the control being validated is one that can be. In the BaseValidator class, it checks to ensure that the ControlToValidate property is set and that the control referenced has a property that can be validated. We need to override this method because this method is the one that throws an exception if ControlToValidate is set to the ID of a CheckBox or CheckBoxList.
• OnPreRender(EventArgs) and AddAttributesToRender(HtmlTextWriter) - these methods inject client-side script to perform client-side validation (if the user is visiting with an uplevel browser and the validation control's EnableClientScript property is True (the default).

The remainder of this article examines the CheckBoxValidator control in detail (the CheckBoxListValidator control is not discussed in this article, but is included in the code available at the end of this download).

The Core CheckBoxValidator Custom Validation Control Members

namespace skmValidators {     public class CheckBoxValidator : BaseValidator     {        private CheckBox _ctrlToValidate = null;        protected CheckBox CheckBoxToValidate        {             get             {                 if (_ctrlToValidate == null)                    _ctrlToValidate = FindControl(this.ControlToValidate) as CheckBox;                                 return _ctrlToValidate;             }        }        protected override bool ControlPropertiesValid()        {             // Make sure ControlToValidate is set             if (this.ControlToValidate.Length == 0)                 throw new HttpException(string.Format("The ControlToValidate property of '{0}' cannot be blank.", this.ID));             // Ensure that the control being validated is a CheckBox             if (CheckBoxToValidate == null)                 throw new HttpException(string.Format("The CheckBoxValidator can only validate controls of type CheckBox."));             return true;    // if we reach here, everything checks out        }        protected override bool EvaluateIsValid()        {             // Make sure that the CheckBox is set as directed by MustBeChecked             return CheckBoxToValidate.Checked == MustBeChecked;        }               ... some methods/properties omitted for brevity ...     } }

First, note that the CheckBoxValidator class extends the BaseValidator class. Next, examine the CheckBoxToValidate property. It uses the FindControl("controlID") method to find the control with the specified ControlToValidate value. If no control with that ID is found, or if it's not a CheckBox, the property returns null.

The ControlPropertiesValid() method, which is responsible for insuring that the essential validation control properties are set and are valid, starts by checking the ControlToValidate property. If it's not specified, an HttpException is thrown. Likewise, if it cannot find a control with the specified ControlToValidate or if that control is not a CheckBox, an HttpException is thrown. If those two checks pass, then the method returns True, indicating that the control properties are valid.

The EvaluateIsValid() method is invoked whenever the validation control's validity needs to be determined. This method returns True - indicating validity - only if the CheckBox to validate's Checked property is set as dictated by the MustBeChecked property. That is, if MustBeChecked is True, the CheckBoxValidator control returns True only if its CheckBox is checked; conversely, if MustBeChecked is False, the CheckBox must be unchecked for the validation control to indicate validity.

Adding Client-Side Validation Support

These two tasks are handled in two separate methods. The client-side script used for validation should be injected in the OnPreRender(EventArgs) method, whereas the name of the validation function and any additional propeties are added in the AddAttributesToRender(HtmlTextWriter) method.

Let's start with the OnPreRender(EventArgs) method. The following code starts by calling the base class's (BaseValidator's) OnPreRender(EventArgs) method, which injects the common client-side script. Next, the RegisterClientScriptInclude() method is used to add a script include (<script src="urlToScript" ... />) to the JavaScript file embedded within the CheckBoxValidator class's assembly. (Embedding resources is an easy and efficient means of deploying and referencing external resource files with a server control library; see Accessing Embedded Resources through a URL using WebResource.axd for more information.) EvaluateIsValid() methods:

namespace skmValidators {     public class CheckBoxValidator : BaseValidator     {        ... Some methods/properties omitted for brevity ...        protected override void OnPreRender(EventArgs e)        {             base.OnPreRender(e);             // Register the client-side function using WebResource.axd (if needed)             // see: https://aspnet.4guysfromrolla.com/articles/080906-1.aspx             if (this.RenderUplevel && this.Page != null && !this.Page.ClientScript.IsClientScriptIncludeRegistered(this.GetType(), "skmValidators"))                 this.Page.ClientScript.RegisterClientScriptInclude(this.GetType(), "skmValidators", this.Page.ClientScript.GetWebResourceUrl(this.GetType(), "skmValidators.skmValidators.js"));        }     } }

The client-side validation function must accept a single input parameter (a reference to the validation control) and must return a Boolean value indicating the validity of the validation control. This function for the CheckBoxValidator control is blindingly simple:

function CheckBoxValidatorEvaluateIsValid(val) {     var control = document.getElementById(val.controltovalidate);     var mustBeChecked = Boolean(val.mustBeChecked == 'true');     return control.checked == mustBeChecked; }

The ID of the control being validated is available via the controltovalidate property of the passed-in object; a call to the document.getElementById("id") function returns a reference to the actual control. The mustBeChecked property of the validation control is then accessed. Finally, the function returns True only if the control's checked property matches up to the mustBeChecked property value.

At this point there are two questions facing us. First, how does the common script injected by the BaseValidator know to call the CheckBoxValidatorEvaluateIsValid function to validate the CheckBoxValidator control? And second, how is the MustBeChecked property value specified for the CheckBoxValidator control passed to this client-side function? If you do a View/Source of a page with validation controls on it, you'll find a JavaScript section that spells out this (and other) information. For example, a RequiredFieldValidator has a select set of its properties rendered in client-side script like so:

var RequiredFieldValidator1 = document.all ? document.all["RequiredFieldValidator1"] : document.getElementById("controlID"); RequiredFieldValidator1.controltovalidate = "controlToValidateID"; RequiredFieldValidator1.errormessage = "errorMessage"; RequiredFieldValidator1.evaluationfunction = "RequiredFieldValidatorEvaluateIsValid";

There may be more settings there, depending on what properties you've set for the RequiredFieldValidator, but the concept is the same - property values needed by the client-side validation logic must be persisted to the client-side through the page's rendered markup. This includes, at minimum, the ID of the control to validate and the function responsible for validation.

This information is injected into the page's rendered markup via the validation control's AddAttributesToRender(HtmlTextWriter) method, and can be injected in two ways:

• Using the AddAttribute method of the passed-in HtmlTextWriter object. This adds attributes to the validation Web control's rendered HTML element.
• Using the RegisterExpandoAttribute method, which adds the attributes using client-side script, like in the RequiredFieldValidator script block shown above.

Enough minutia, let's look at the code! As you can see below, two attributes are added (either via the expando or AddAttribute approaches, depending on the Helpers.EnableLegacyRendering() method's return value). The first attribute is required and specifies the name of the function to invoke to perform client-side validation. The second attribute persists the MustBeChecked property to the rendered output.

namespace skmValidators {     public class CheckBoxValidator : BaseValidator     {        ... Some methods/properties omitted for brevity ...        protected override void AddAttributesToRender(HtmlTextWriter writer)        {             base.AddAttributesToRender(writer);             // Add the client-side code (if needed)             if (this.RenderUplevel)             {                 // Indicate the mustBeChecked value and the client-side function to used for evaluation                 // Use AddAttribute if Helpers.EnableLegacyRendering is true; otherwise, use expando attributes                 if (Helpers.EnableLegacyRendering())                 {                    writer.AddAttribute("evaluationfunction", "CheckBoxValidatorEvaluateIsValid", false);                    writer.AddAttribute("mustBeChecked", MustBeChecked ? "true" : "false", false);                 }                 else                 {                    this.Page.ClientScript.RegisterExpandoAttribute(this.ClientID, "evaluationfunction", "CheckBoxValidatorEvaluateIsValid", false);                    this.Page.ClientScript.RegisterExpandoAttribute(this.ClientID, "mustBeChecked", MustBeChecked ? "true" : "false", false);                 }             }        }     } }

Using the CheckBoxValidator and CheckBoxListValidator Controls

Once you've added the controls to the Toolbox or have entered their markup manually, they should appear as any validation control when in the Designer. Moreover, their properties should be accessible through the Properties window. And most importantly, when visiting a page through a browser, they should function as expected!

The CheckBoxValidator in the Designer in Visual Studio

The CheckBoxValidator When Viewed Through a Web Page

At the end of this article you'll find links to related articles, the complete project code that includes a test project with a demo page. In this article we only examined the CheckBoxValidator control; the download includes an additional validation control designed to work with CheckBoxLists.

The CheckBoxValidator Control Has Been Upgraded!
I have upgraded the CheckBoxValidator so that it can optionally enable or disable an associated Button, LinkButton, or ImageButton control depending on its CheckBox's checked state. For more information, see Disabling the Submit Button Until a CheckBox is Checked.

Happy Programming!

Attachments