I want to demonstrate the effectiveness of this suite of controls with at least one concrete example. In this case, I'm going to mock up a Human Resources form that might be used within a company to track information about employees. Some of the fields included are Age, Gender, Date Began With Company, Salary, etc. Some will be a bit contrived just to exercise the validators a bit.
For this scenario, I've established the following business rules:
- Full Name is required
- Age is a positive integer.
- Weight is a positive decimal number (I know, no HR person would track weight maybe it's for a sports team)
- Annual Salary must be a currency type.
- Date Began With Company is required and must be properly formatted.
- Date Terminated must follow Date Began, and must be properly formatted.
- W9 On File is a checkbox (in case this "employee" is actually a contractor). It is not required but if it is checked, then the location of the electronic W9 document must be specified.
- File Location is required, but only if the W9 On File checkbox is checked.
- Notes free text, up to 256 characters.
I implemented all of the above in less than an hour using a variety of VAM controls for data entry and validation. The Age, Weight, and Salary fields are using IntegerTextBox, DecimalTextBox, and CurrencyTextBox controls, respectively, which means only appropriate values can be entered (so the validators on these fields are generally redundant, but a good idea in case a downlevel browser or hacker avoids the masking built into the textbox controls). One of the cooler features I utilized was the Enabler property and the FieldStateController control. Using these two features, it is relatively straightforward to create dependencies between control visibility or read-only state and the value or validation status of other controls. For instance, the Required validator on the File Location field is only enabled if the W9 On File checkbox is checked. Similarly, the File Location textbox is only visible and write-enabled when the W9 On File checkbox is checked. Since I see people asking how to dynamically enable/disable validators on forums and mailing lists every day, this feature alone is one I know there is a lot of demand for.
Below are two screenshots from this sample, one of the browser and one of VS 2005.
Figure 1. Browser Screenshot.
Figure 2 VS 2005 Screenshot
(Hey, check out the number of validators on the left and the properties on the right! These things have a ton of features that I haven't covered here.)
Listing 1 Usage Example
<%
@ Page Language="C#" AutoEventWireup="true" %>
<%
@ Register Assembly="PeterBlum.VAM" Namespace="PeterBlum.VAM" TagPrefix="VAM" %>
<!
DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<
html xmlns="http://www.w3.org/1999/xhtml" >
<
head id="Head1" runat="server">
<title>ACME: Edit Employee Profile</title>
<link href="/VAM/Appearance/VAMStylesheet.css" type="text/css" rel="stylesheet" />
</
head>
<
body>
<form id="form1" runat="server">
<div>
<strong>Update Employee Profile<br />
</strong><VAM:RequiredFieldsDescription
ID="RequiredFieldsDescription1"
runat="server"></VAM:RequiredFieldsDescription><br />
<table style="width: 600px">
<tr>
<td style="width: 175px; height: 23px;">
Full Name
<VAM:RequiredFieldMarker ID="RequiredFieldMarker1"
runat="server"></VAM:RequiredFieldMarker></td>
<td style="width: 300px; height: 23px;">
<VAM:TextBox ID="FullNameTextBox" runat="server"
Width="300px"></VAM:TextBox></td>
<td style="width: 200px; height: 23px">
<VAM:RequiredTextValidator ID="RequiredTextValidator1" runat="server"
ControlIDToEvaluate="FullNameTextBox" ErrorMessage="Full name is required."
ShowRequiredFieldMarker="True">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:RequiredTextValidator>
</td>
</tr>
<tr>
<td style="width: 175px; height: 21px;">
Age
</td>
<td style="width: 100px; height: 21px;">
<VAM:IntegerTextBox ID="IntegerTextBox1" runat="server" TabIndex="1"
Width="60px"></VAM:IntegerTextBox></td>
<td style="width: 100px; height: 21px">
<VAM:DataTypeCheckValidator ID="DataTypeCheckValidator4" runat="server"
ControlIDToEvaluate="IntegerTextBox1"
DataType="Positive Integer" ErrorMessage="Age must be a positive integer.">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:DataTypeCheckValidator>
</td>
</tr>
<tr>
<td style="width: 175px">
Weight
</td>
<td style="width: 100px">
<VAM:DecimalTextBox ID="DecimalTextBox1" runat="server" TabIndex="2" Width="60px"></VAM:DecimalTextBox></td>
<td style="width: 100px">
<VAM:DataTypeCheckValidator ID="DataTypeCheckValidator5" runat="server" ControlIDToEvaluate="DecimalTextBox1"
DataType="Positive Double" ErrorMessage="Weight must be a positive decimal.">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:DataTypeCheckValidator>
</td>
</tr>
<tr>
<td style="width: 175px">
Annual Salary
</td>
<td style="width: 100px">
<VAM:CurrencyTextBox ID="CurrencyTextBox1" runat="server" TabIndex="3"></VAM:CurrencyTextBox></td>
<td style="width: 100px">
<VAM:DataTypeCheckValidator ID="DataTypeCheckValidator3" runat="server" ControlIDToEvaluate="CurrencyTextBox1"
DataType="Currency with symbol" ErrorMessage="Salary must be currency.">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:DataTypeCheckValidator>
</td>
</tr>
<tr>
<td style="width: 175px">
Date Began w/Company
<VAM:RequiredFieldMarker ID="RequiredFieldMarker2" runat="server"></VAM:RequiredFieldMarker></td>
<td style="width: 100px">
<VAM:FilteredTextBox ID="StartDateTextBox" runat="server" Digits="True" OtherCharacters="/"
TabIndex="4"></VAM:FilteredTextBox></td>
<td style="width: 100px"><VAM:RequiredTextValidator ID="RequiredTextValidator3" runat="server" ControlIDToEvaluate="StartDateTextBox" ErrorMessage="Date Began is required." ShowRequiredFieldMarker="True">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:RequiredTextValidator>
<VAM:DataTypeCheckValidator ID="DataTypeCheckValidator1" runat="server" ControlIDToEvaluate="StartDateTextBox"
DataType="Date" ErrorMessage="Invalid Date Format.">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:DataTypeCheckValidator>
</td>
</tr>
<tr>
<td style="width: 175px">
Date Terminated
</td>
<td style="width: 100px">
<VAM:FilteredTextBox ID="EndDateTextBox" runat="server" Digits="True" OtherCharacters="/"
TabIndex="5"></VAM:FilteredTextBox></td>
<td style="width: 100px">
<VAM:CompareTwoFieldsValidator ID="CompareTwoFieldsValidator1" runat="server" ControlIDToEvaluate="EndDateTextBox"
DataType="Date" ErrorMessage="End Date cannot occur before Begin Date." Operator="GreaterThanEqual"
SecondControlIDToEvaluate="StartDateTextBox">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:CompareTwoFieldsValidator>
<VAM:DataTypeCheckValidator ID="DataTypeCheckValidator2" runat="server" ControlIDToEvaluate="EndDateTextBox"
DataType="Date" ErrorMessage="Invalid Date Format.">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:DataTypeCheckValidator>
</td>
</tr>
<tr>
<td style="width: 175px">
W9 On File?
</td>
<td style="width: 100px">
<asp:CheckBox ID="W9OnFileCheckBox" runat="server" TabIndex="6" Width="111px" /></td>
<td style="width: 100px">
</td>
</tr>
<tr>
<td style="width: 175px">
File Location<VAM:RequiredFieldMarker ID="RequiredFieldMarker3" runat="server"></VAM:RequiredFieldMarker></td>
<td style="width: 100px">
<VAM:TextBox ID="W9FileLocationTextBox" runat="server"></VAM:TextBox></td>
<td style="width: 100px"><VAM:RequiredTextValidator ID="RequiredTextValidator2" runat="server" ControlIDToEvaluate="W9FileLocationTextBox" Enabler="CheckStateCondition: W9OnFileCheckBox is checked" ErrorMessage="This field is required if W9 on file is checked." ShowRequiredFieldMarker="True">
<EnablerContainer>
<VAM:CheckStateCondition ControlIDToEvaluate="W9OnFileCheckBox" Name="CheckStateCondition" />
</EnablerContainer>
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:RequiredTextValidator>
</td>
</tr>
<tr>
<td style="width: 175px">
</td>
<td style="width: 100px">
</td>
<td style="width: 100px">
</td>
</tr>
<tr>
<td style="width: 175px; height: 46px;">
Notes (256 char max)
</td>
<td style="width: 100px; height: 46px;">
<VAM:TextBox ID="NotesTextBox" runat="server" Height="71px" MaxLength="300" Rows="5"
TextMode="MultiLine" Width="299px"></VAM:TextBox></td>
<td style="width: 100px; height: 46px;">
<VAM:TextLengthValidator ID="TextLengthValidator1" runat="server" ControlIDToEvaluate="NotesTextBox"
ErrorMessage="Notes cannot exceed 256 characters." Maximum="256">
<ErrorFormatterContainer>
<VAM:TextErrorFormatter />
</ErrorFormatterContainer>
</VAM:TextLengthValidator>
</td>
</tr>
</table>
</div>
<VAM:ValidationSummary ID="ValidationSummary1" runat="server" HeaderText="Please correct the following:" />
<VAM:FieldStateController ID="W9FileLocationFieldStateController1" runat="server"
Condition="CheckStateCondition: W9OnFileCheckBox is checked" ConditionFalse-ReadOnly="True"
ConditionFalse-Visible="False" ControlIDToChange="W9FileLocationTextBox">
<ConditionContainer>
<VAM:CheckStateCondition ControlIDToEvaluate="W9OnFileCheckBox" Name="CheckStateCondition" />
</ConditionContainer>
</VAM:FieldStateController>
<br />
<VAM:Button ID="SaveButton" runat="server" Text="Save" />
</form>
</
body>
</
html>
