Introduction

The Ajax Control Toolkit is an Open Source Project, managed jointly by both Microsoft and Community Developers. Currently, the project contains 30+ excellent client side components to develop Rich Internet Applications and an extensible API to develop your own control. Obviously explaining all these components in a single part is not a wise choice, so I broke it down in the following parts:

Explore

• Input Helpers - FilteredTextBox and NumericUpDown (This Part).
• Input Helpers - MaskEdit and Slider.
• Input Helpers - CascadingDropDown and Calendar.
• Input Helpers - ToggleButton, Rating and ValidatorCallout.
• Containers - Dynamic Populate and CollapsiblePanel.
• Containers -Tabs.
• Containers - Accordion.
• Popups - Popup, DropDown and ModalPopup.
• Others- NotBot and PasswordStrength.
• Others- ToolkitScriptManager.

Architecture

• Core Framework
• Animation Framework

Build

• Demonstrate how to develop a first class control on top of Ajax Control Toolkit.

In the Explore part, we will get familiar with the some of the important controls/extenders that are available in the Ajax Control Toolkit. I have excluded the AutoComplete extender intentionally as I think there are already many references available on the Internet. If you think I have missed any important controls that you would like to see, do let me know, I will include it in future article.

Next, in the Architecture part I will cover the internal details of the Ajax Control Toolkit. I have also dedicated a single part to Animation, as it is important for creating today's Web 2.0 applications.

At last, in the Build part, I will show you how to develop a professional control on top of the Ajax Control Toolkit.

Although I would recommend reading the whole series, you can skip those articles that you think are not important for you.

FilteredTextBox

The FilteredTextBox extender prevents a user from entering invalid characters in a textbox. Although it ensures that the extending textbox does not contain any invalid characters, you should never expect - on the server side - that it contains only valid characters. The extender has prebuilt support for allowing uppercase, lowercase, numbers, and it is also possible to define multiple custom characters. The following list shows the properties of this extender with their description:

• FilterType: Is an enumeration, and its values are Numbers, UppercaseLetters, LowercaseLetters and Custom, or any combination of these.
• FilterMode: Is an enumeration and its values are ValidChars or InvalidChars. This property comes into action when the FilterType property is set to Custom.
• ValidChars: This property also comes into action when the FilterType property is set to Custom and the FilterMode is set to ValidChars. With this property we can specify multiple characters that we want to allow. If the FilterType contains Custom along with other values, it will allow both.
• InvalidChars: It does the opposite job as the ValidChars property, which means the textbox will allow all others except the characters specified in this property.

Let us take few quick examples:

The above extender ensures the textbox only allows numbers.

We can set multiple values for the FilterType property. The above code snippet ensures that only uppercase characters and numeric digits are accepted by the textbox.

The above example shows how to accept only hexadecimal values in a textbox.

The above example ignores the characters including the blank space as specified in the InvalidChars property.

The FilteredTextBox extender contains two client side events:

• processKey: This event is fired when a key is pressed in the textbox. This event can be used to accept characters that are not mentioned in the properties.
• filtered: This event is fired when an invalid character is typed in the extending textbox.
• The following code snippet shows how to accept characters dynamically by leveraging this event.

NumericUpDown

The NumericUpDown extender attaches a set of Up and Down buttons to a textbox in order to increment and decrement its value. Although the name suggests it can be only used with numeric values, it can be also used to select a predefined list of values - numeric or not. If you are familiar with Windows Forms Applications then consider it as a combined version of NumericUpDown and DomainUpDown controls. The NumericUpDown extender can be used in any of the following ways:

• Setting up the Minimum, Maximum and Step properties that will work with numeric values.
• Providing values for the RefValues property in semi-colon (;) separated values.
• Setting up WebService/PageMethods calls for Up and Down button clicks.

Let us look at a few quick examples of how to set up the NumericUpDown. The first example shows how to use it for GPA values.

The following shows how to use it for predefined values:

As you can see from the first example, we have set the Minimum, Maximum and Step properties since we are using it for numeric values. For the second example, we only used RefValues to show the rainbow colors without specifying any values for the properties that we set in the first example.

Before moving to the Web Service example, I would like to mention two important things. First, in the above examples we are also specifying the Width in the extender. This width is the combined value of the textbox width and the auto generated buttons' width. If you do not specify the Width, you will find that the textbox becomes invisible at runtime, which seems very weird. Second, the auto generated buttons look very ugly and this is why the NumericUpDown extender allows custom buttons to act as the up/down buttons. The following code shows how to set up custom controls to act as up/down buttons:

Note that the Width of the extender does not have any impact when setting up custom buttons.

In some situations, we might have no upper/lower limit or the next/previous value is calculated based upon some custom logic. In these cases, the WebService binding provided by this extender is real handy. When binding with WebService/PageMethods, the following five properties come into action:

• ServiceUpPath: The path of the WebService that will be invoked when the Up button is clicked. When using PageMethods, leave it empty.
• ServiceDownPath: The path of the WebService that will be invoked when the Down button is clicked. When using PageMethods, leave it empty, as you do with ServiceUpPath.
• ServiceUpMethod: The name of the method that will be called when the Up button is pressed. This is mandatory when binding to WebService/PageMethods.
• ServiceDownMethod: The name of the method that will be called when the Down button is pressed. This is mandatory when binding to WebService/PageMethods.
• Tag: Additional data that you can pass to WebService/PageMethods. This property is very useful when the same method is bound to more than one extender. Depending upon the tag, we can determine which extender is calling the web method.

When working with WebService/PageMethods you have to keep a few things in mind. First, the WebService/PageMethods binding can be used only for Numeric values; you cannot use it for string values like the RefValues property. Second, the WebMethod must match the following signature:

The WebMethod name can be anything and the same is true for dataType as long as it is numeric. The parameters names must be the same and they are case sensitive.

Before moving to the client events let me mention a few more key points of this extender. First, when binding to WebService/PageMethods or RefValues the extended textbox becomes read-only, which ensure the user will never be able to input invalid data in that textbox. When working with the default mode (Minimum/Maximum/Step) the textbox does not become read-only and the extender does not ensure the contained value is valid. So it is up to the developer to ensure the validity in this case. I would recommend that you use the regular ASP.NET validators along with this extender even if you are working with the WebService/PageMethods or RefValues to also perform the server side validation.

The NumericUpDown extender has only one event, currentChanged. This event is fired whenever the value of the extended textbox is changed through the up/down buttons or when the user types a new value in that textbox. In case of typing, the event fires whenever the focus leaves the textbox. The following code snippet shows how to hook the event. The new value is returned in the event arguments.

Summary

In this introductory part, we have examined two important input helper controls. In the future parts we will examine more important controls and show some cool examples.

About Kazi Manzur Rashid

Kazi Manzur Rashid, Nickname Amit is a Diehard fan of Microsoft Technology. He started programming with Visual Basic 5.0 back in 1996. Since then he has developed many diversified solutions in his professional career, which spans from Anti-Spyware Tool to Personalized Start Page. Currently He is wor... This author has published 10 articles on DotNetSlackers. View other articles or the complete profile here.

---

Discussion

Subject	Author	Date
Briefly explained	Faisal Khan	1/16/2008 3:45 PM
Great effort. Reply | Permanent link
great work	Bossjantu Jantu	1/17/2008 4:10 PM
great work, very helpful. Reply | Permanent link
currentChanged Event	Joe Tozzi	1/7/2009 3:41 PM
I am confused when you say "The following code snippet shows how to hook the event.". What I am trying to do is check the user input to see if it is outside the min & max and change it to the min or max.  I would also like to have the up & down buttons loop through the range of valid numbers, so that if you had an hour field for instance, it would continually loop from 1-12 and not just stop at 1 when clicking down and 12 when clicking up. Reply | Permanent link

---

Please login to rate or to leave a comment.