Ajax Control Toolkit MaskedEdit

Modified on 2010/04/16 00:41 by Stephen Walther — Categorized as: Uncategorized

MaskedEdit is an ASP.NET AJAX extender that attaches to a TextBox control to restrict the kind of text that can be entered. MaskedEdit applies a "mask" to the input that permits only certain types of characters/text to be entered. The supported data formats are: Number, Date, Time, and DateTime. MaskedEdit uses the culture settings specified in the CultureName property. If none is specified the culture setting will be the same as the page: English (United States).

MaskedEdit Server Properties

The properties in italics are optional.

<ajaxToolkit:MaskedEditExtender
    TargetControlID="TextBox2" 
    Mask="9,999,999.99"
    MessageValidatorTip="true" 
    OnFocusCssClass="MaskedEditFocus" 
    OnInvalidCssClass="MaskedEditError"
    MaskType="Number" 
    InputDirection="RightToLeft" 
    AcceptNegative="Left" 
    DisplayMoney="Left"
    ErrorTooltipEnabled="True"/>

MaskType - Type of validation to perform:
None - No validation
Number - Number validation
Date - Date validation
Time - Time validation
DateTime - Date and time validation
Mask Characters and Delimiters
9 - Only a numeric character
L - Only a letter
$ - Only a letter or a space
C - Only a custom character (case sensitive)
A - Only a letter or a custom character
N - Only a numeric or custom character
? - Any character

/ - Date separator
<ESC>:</ESC> - Time separator
. - Decimal separator
, - Thousand separator
\ - Escape character
{ - Initial delimiter for repetition of masks
} - Final delimiter for repetition of masks

Examples 
9999999 - Seven numeric characters 
99\/99 - Four numeric characters separated in the middle by a "/"

AcceptAMPM - True to display an AM/PM symbol
AcceptNegative - True if the negative sign (-) is allowed
None - Do not show the negative sign
Left - Show the negative sign on the left of the mask
Right - Show the negative sign on the right of the mask

AutoComplete - True to automatically fill in empty mask characters not specified by the user
MaskType=Number - Empty mask characters will be filled with zeros
MaskType=Time - Empty mask characters will be filled with the current time
MaskType=Date - Empty mask characters will be filled with the current date
MaskType=DateTime - Empty mask characters will be filled with the current date/time

AutoCompleteValue - Default character to use when AutoComplete is enabled
Century - Default century used when a date mask only has two digits for the year
ClearMaskOnLostFocus - True to remove the mask when the TextBox loses focus
ClearTextOnInvalid - True to clear the TextBox when invalid text is entered
ClipboardEnabled - True to allow copy/paste with the clipboard
ClipboardText - Prompt text to use when a clipboard paste is performed
DisplayMoney - Specifies how the currency symbol is displayed
None - Do not show the currency symbol
Left - Show the currency symbol on the left of the mask
Right - Show the currency symbol on the right of the mask

ErrorTooltipCssClass - CSS class for the tooltip message
ErrorTooltipEnabled - True to show a tooltip message when the mouse hovers over an invalid TextBox
Filtered* - Valid characters for mask type "C" (case-sensitive)
InputDirection - Text input direction
LeftToRight - Left to Right
RightToLeft - Right to left

MessageValidatorTip - Message displayed when editing in TextBox
PromptChararacter - Prompt character for unspecified mask characters
UserDateFormat - Custom date format
UserTimeFormat - Custom time format

OnFocusCssClass - CSS class used when the TextBox receives focus
OnFocusCssNegative - CSS class used when the TextBox gets focus with a negative value
OnBlurCssNegative - CSS class used when the TextBox loses focus with a negative value
OnInvalidCssClass - CSS class used when the text is not valid.

CultureName - Name of culture to use (overrides the default page culture)
CultureAMPMPlaceholder - Culture override
CultureCurrencySymbolPlaceholder - Culture override
CultureDateFormat - Culture override
CultureDatePlaceholder - Culture override
CultureDecimalPlaceholder - Culture override
CultureThousandsPlaceholder - Culture override
CultureTimePlaceholder - Culture override

MaskedEdit Validator Description

MaskedEditValidator is a custom validator which attaches to the MaskedEdit extender and its associated TextBox and verifies that the input text matches the pattern specified in the MaskedEdit extender. Once associated with a validation group, server- and client-side validation can be performed and used to display messages. MaskedEditValidator Properties The control above is initialized with this code. The italic properties are optional.

<ajaxToolkit:MaskedEditValidator
    ControlExtender="MaskedEditExtender2"
    ControlToValidate="TextBox2" 
    IsValidEmpty="False" 
    MaximumValue="12000" 
    EmptyValueMessage="Number is required"
    InvalidValueMessage="Number is invalid"
    MaximumValueMessage="Number > 12000"
    MinimumValueMessage="Number < -100"
    MinimumValue="-100" 
    EmptyValueBlurredText="*" 
    InvalidValueBlurredMessage="*" 
    MaximumValueBlurredMessage="*" 
    MinimumValueBlurredText="*"
    Display="Dynamic" 
    TooltipMessage="Input a number: -100 up to 12.000"/>

ControlExtender - ID of the MaskedEditExtender attached to the TextBox
ControlToValidate - ID of the TextBox to validate

AcceptAMPM - Whether or not AM/PM is accepted on times. The default value is false.
ClientValidationFunction - Client script used for custom validation
InitialValue - Initial value of the TextBox
IsValidEmpty - True if the TextBox can be empty
MaximumValue - Maximum value of the input
MinimumValue - Minimum value of the input
ValidationExpression - Regular expression used to validate the input

TooltipMessage - Message displayed when the TextBox has focus with an empty value
EmptyValueMessage - Message displayed when empty and TextBox has focus
EmptyValueBlurredText - Message displayed when empty and TextBox does not have focus
InvalidValueMessage - Message displayed when invalid and TextBox has focus
InvalidValueBlurredMessage - Message displayed when invalid and TextBox does not have focus
MaximumValueMessage - Message displayed when maximum value exceeded and TextBox has focus
MaximumValueBlurredMessage - Message displayed when maximum value exceeded and TextBox does not have focus
MinimumValueMessage - Message displayed when minimum value exceeded and TextBox has focus
MinimumValueBlurredText - Message displayed when minimum value exceeded and TextBox does not have focus

MaskedEdit Known Issues

Opera's keyboard handling implementation causes the "." key to map to "Del" and the "Ins" key to map to "-".