Updates to the TextBox Word / Character Counter Control
By Scott Mitchell
Introduction
When storing user-supplied text data into a database, it is essential that the length of the user's input does not exceed the size of the corresponding
database table field. To ensure that a user's input is within the legal bounds, you can: set the TextBox control's MaxLength property (although
this does not work for multi-line textboxes); use a validation control, such as my TextBoxLengthValidator
control or a RegularExpressionValidator; use server-side code to check the Length property of the string before storing it in the database;
or some combination of the above. The problem with these solutions is that they are not very interactive. The user doesn't know how close she is to
hitting the maximum number of characters.
In October 2007 I created a custom ASP.NET server control that uses JavaScript to interactively display the number of characters and/or words a user
has typed into a textbox, and wrote about it in an article titled Creating a TextBox
Word / Character Counter Control. In the TextBoxCounter control's initial implementation is simply reported how many words or characters the user
had entered. Because this control is most useful in scenarios where there is a limit to the number of characters or words allowed, a natural enhancement
would be to allow the page developer to specify a maximum number of characters or words allowed. With this information, the control could be updated
to show how many characters or words remain. Moreover, the appearance of the TextBoxCounter could be modified based on how close the user was to reaching
the word or character limit.
Recently, 4Guys reader David Dude implemented these future enhancements and shared his code changes with me; I've since integrated them into the code
base. This article looks at the enhancements to the TextBoxCounter control class and demonstrates how to use them in an ASP.NET page. Read on to learn more!
Specifying a Maximum Character or Word Count
The TextBoxCounter control includes two new properties (among others) that allow for the page developer to specify the maximum number of allowable characters
and/or words:
MaxCharacterLength - the maximum number of allowable characters.
MaxWordLength - the maximum number of allowable words.
Set these properties to zero to indicate that there is no maximum.
Keep in mind that the TextBoxCounter control does not restrain the user from entering more than the maximum number of allowable characters or words.
The control is intended solely for informational purposes, you still need to implement server-side logic (or use validation controls) to ensure that the
user's input is within the legal bounds. But by adding these two new properties to the TextBoxCounter control we can enhance the control's display to
include how many allowable characters or words remain and by modifying the TextBoxCounter control's style when a certain threshold is reached.
The TextBoxCounter control has a DataFormatString property that displays a message that is interactively updated as the user types into
the corresponding TextBox control. This property defaults to the value "{0} words, {1} characters", and at runtime the placeholders {0}
and {1} are replaced with the number of words and characters entered by the user, respectively. Using this default value for the
DataFormatString property, as the user types in the textbox the TextBoxCounter control will update its display, initially showing
"0 words, 0 characters", then "1 words, 1 characters" after typing in the first character, then "1 words, 2 characters" after the next, and so on.
The TextBoxCounter control has been updated to include four new placeholder values that display the maximum number of allowable characters and words, along
with the number of remaining allowable characters and words:
{2} - number of words remaining
{3} - number of characters remaining
{4} - the maximum number of allowable words
{5} - the maximum number of allowable characters
With these new placeholders you can configure the DataFormatString property to display the number of remaining characters. For example, using
the DataFormatString string "{5} total characters allowed; {3} remaining" with the MaxCharacterLength property set to 50 would
have the TextBoxCounter control initially display "50 total characters allowed; 50 remaining". After typing in the first character, the display would be updated
to "50 total characters allowed; 49 remaining".
The following screen shots show the above DataFormatString string in action.
Altering the TextBoxCounter Control's Appearance Based On The Number Of Words Entered
As we just saw, by adding properties to the control to let the page developer specify the maximum allowable number of words and/or characters we can
enhance the display to interactive show how many remaining words or characters there are. Moreover, we can have the TextBoxCounter control's appearance
update based on this information. For example, if only 20 characters are allowed, the TextBoxCounter character text might switch from black to yellow when
there are less than 10% of the available characters left, and from yellow to red once the maximum is reached.
The TextBoxCounter control includes three new properties to provide this functionality:
WarningPercentage - the percentage of used characters or words that triggers the TextBoxCounter control to display its "warning" appearance, which
alerts the user that they are approaching the maximum number of characters. Use a value of zero to disable this functionality.
CssClassForWarning - the CSS class to apply when the WarningPercentage threshold is reached. For example, if the
MaxCharacterLength property is set to 100 and the WarningPercentage property to 80, whenever the number of characters
entered is equal to or exceeds 80 the TextBoxCounter control will assume the appearance settings detailed by the CssClassForWarning
CSS class.
CssClassForMax - the CSS class to apply when the number of characters or words reaches or exceeds the maximum number allowed.
The TextBoxCounter control also includes a CssClass property, which specifies the default CSS class.
The demo available for download at the end of this article includes a TextBoxCounter control that uses these properties. The three CSS classes
are defined in the Styles.css file:
The DefaultTextBoxCounterStyle CSS class defines the default style - a maroon background with white, bold, Comic Sans MS text and a 2 pixel
padding. When the warning threshold is reached, the TextBoxCounter control's style will change to the WarningTextBoxCounterStyle CSS
class, which displays larger, yellow text. The MaxTextBoxCounterStyle CSS class is used when the user reaches or exceeds the maximum allowable
character or word count, and displays even larger red text on a gray background with a red, dashed border.
These CSS classes, along with the warning threshold, are specified via the TextBoxCounter control properties we just examined.
Note that the WarningPercentage is set to 75. This applies to both the maximum character count and the maximum word count (if both
are specified). Because this particular example specifies both the MaxCharacterLength and MaxWordLength properties, the
TextBoxCounter control will convert to its warning display when the user reaches 38 characters or 3 words, whatever comes first. Likewise, the
MaxTextBoxCounterStyle CSS style will be displayed when the user reaches or exceeds 50 characters or 4 words.
The following screen shots show the above TextBoxCounter control in action.
Changes to the TextBoxCounter Control's Source Code
Adding this new functionality did not require any major changes to the TextBoxCounter control's source code. The code for the new properties -
MaxCharacterLength, MaxWordLength, WarningPercentage, CssClassForMax, CssClassForWarning -
was added, along with the code in the OnPreRender method to pass these new property values to the skm_CountTextBox JavaScript
function. The embedded JavaScript file that contains the skm_CountTextBox function, skmControls2.js, was more heavily modified.
As noted, the skm_CountTextBox function was updated to accept the new properties as input parameters. Moreover, the function computes the
number of allowable characters and words remaining (if the maximum character or word counts are specified), incorporates the new placeholder values,
and applies the appropriate CSS class based on the thresholds.
Many thanks to David Dude, who was wrote the code and JavaScript to implement these new features.
