ptg 1734 CHAPTER 39 Using the ASP.NET AJAX Control Toolkit Using the ASP.NET AJAX Control Toolkit The ASP.NET AJAX Control Toolkit is not included with ASP.NET 4 Framework. The Toolkit is continuously updated; a new release of the Toolkit is available every couple months. The Toolkit is maintained as a project at Microsoft CodePlex. You can download the latest release of the ASP.NET AJAX Control Toolkit at http://ajaxcontroltoolkit.codeplex.com/. The “download” link will give you the 3.5 version of the toolkit, which won’t work with our ASP.NET 4 websites. To get the toolkit that’s compatible with .NET 4, click the “other downloads” link. When you download the Toolkit, you have the choice of either (1) downloading the controls and the source code or (2) downloading the controls only. You need to unzip the download onto your hard drive. As part of the download, you get a sample website that demonstrates each of the Toolkit controls. You can open the sample website by launching Visual Web Developer, selecting File, Open Website and browsing to the SampleWebSite folder in the unzipped download. The ASP.NET AJAX Control Toolkit is not installed in the Global Assembly Cache. You must copy the AjaxControlToolkit.dll assembly from the /Bin folder of the SampleWebSite to the /Bin folder in your application. You can do this in multiple ways: . Copy the assembly by hand—You can simply copy the AjaxControlToolkit.dll assembly from the SampleWebSite /Bin folder to a /Bin folder located in a new website. . Add an assembly reference—Follow these steps: 1. Within Visual Web Developer, select Website, Add Reference. 2. Select the Browse tab. 3. Browse to the AjaxControlToolkit.dll assembly located in the SampleWebSite /Bin folder. . Add the Toolkit to your Toolbox (see Figure 39.1)—You can add the ASP.NET AJAX Control Toolkit to the Visual Web Developer Toolbox by following these steps: 1. Within Visual Web Developer, create a new ASP.NET page. 2. Right-click in the Toolbox window and select Add Tab. Create a new tab named Toolkit. 3. Right-click under the new tab and select Choose Items. 4. Click the Browse button located at the bottom of the .NET Framework Components tab. 5. Browse to the /Bin folder of the SampleWebSite and select the AjaxControlToolkit.dll assembly. 6. When you drag a control from the Toolbox onto a page, the AjaxControlToolkit.dll is copied to the Website /Bin folder automatically. From the Library of Wow! eBook ptg 1735 Using the ASP.NET AJAX Control Toolkit FIGURE 39.1 Adding the ASP.NET AJAX Control Toolkit to the Toolbox. The majority of the controls in the ASP.NET AJAX Control Toolkit are extender controls. Visual Web Developer provides additional designer features for working with extender controls. For example, if you add a standard TextBox control to the Designer, an Add Extender link appears in the Common TextBox Tasks dialog box (See Figure 39.2). 39 If you click the Add Extender link, a dialog box appears that enables you to pick an exten- der that can be applied to the TextBox control (see Figure 39.3). Different extenders appear for different controls. For example, because you can apply a ConfirmButton extender to a Button control but not a TextBox control, the ConfirmButton extender appears only when you click Add Extender for the Button control. FIGURE 39.2 The Add Extender task. From the Library of Wow! eBook ptg 1736 When you extend a control, additional properties appear for the control being extended in the extended control’s Properties window. For example, if you extend a TextBox control with the AutoComplete extender, the AutoComplete extender control’s properties appear when you open the TextBox control’s Properties window (see Figure 39.4). CHAPTER 39 Using the ASP.NET AJAX Control Toolkit FIGURE 39.3 Selecting an extender control. FIGURE 39.4 Viewing extender control properties. From the Library of Wow! eBook ptg 1737 Overview of the Toolkit Controls 39 Overview of the Toolkit Controls This section, provides you with a brief overview of each of the current Toolkit controls. I recommend that you open the ASP.NET AJAX Control Toolkit sample website and experi- ment with the controls while reading this chapter. . Accordion—Enables you to create a Microsoft Outlook-like expanding and collapsing menu. The Accordion control can contain one or more AccordionPane controls. One AccordionPane can be selected at a time. The selected pane is expanded; the other panes are collapsed. . AlwaysVisibleControl—Enables you to display content that is fixed at one location in the browser window even when you scroll the window. The control works like the position:fixed Cascading Style Sheet (CSS) attribute. However, unlike the CSS attribute, AlwaysVisibleControl works with Microsoft Internet Explorer 6.0. . Animation—Enables you to add fancy animation effects to your website. For example, you can move, resize, and fade elements in a page. We examine the Animation control in detail in the section “Using the Animation Control.” . AsyncFileUpload—Enables you to upload files asynchronously to the server. . AutoComplete—Enables you to display suggestions as a user types text into a text field. We discuss this control in detail in the section “Using the AutoComplete Control.” (This control is used in the sample application described in the last chapter.) . Calendar—Displays a pop-up calendar next to TextBox. It enables you to select a year, month, and date by clicking dates in a pop-up calendar. . CascadingDropDown—Enables you to make the list of items displayed in one DropDownList control dependent on the list of items displayed in another DropDownList control. The DropDownList items are updated by performing an asyn- chronous postback. . CollapsiblePanel—Enables you to hide or display content contained in a Panel control. When you click its header, the content either appears or disappears. . ColorPicker—Provides an interactive pop-up control that enables you to graphically choose colors. . ComboBox—Is similar to a traditional ASP.NET DropDownList, except it provides func- tionality similar to the ComboBox control found in Windows Forms, such as the ability to type in free-form text. . ConfirmButton—Enables you to display a confirmation dialog box when a user clicks a button. The confirmation dialog box can be the default JavaScript confirmation box. Alternatively, you can associate a modal dialog box with the ConfirmButton control. From the Library of Wow! eBook ptg 1738 CHAPTER 39 Using the ASP.NET AJAX Control Toolkit . DragPanel—Enables you to create a panel that you can drag with your mouse around the page. It enables you to create a virtual floating window. We discuss the DragPanel control in the section “Using the DragPanel Control.” . DropDown—Enables you to create a SharePoint-style drop-down menu. . DropShadow—Enables you to add a drop shadow to a Panel control. You can set prop- erties of the drop shadow, such as its width and opacity. . DynamicPopulate—Enables you to dynamically populate the contents of a control, such as a Label control, by performing an asynchronous call to the server. You can set up the DynamicPopulate control so that the asynchronous request is triggered by another control such as a Button control. . FilteredTextBox—Enables you to prevent certain characters from being entered into TextBox. The FilteredTextBox is discussed in the section “Using the FilteredTextBox Control.” . HoverMenu—Displays a pop-up menu when you hover over another control. . HTMLEditor—Enables you to easily create HTML through a rich WYSIWYG editor. A toolbar is provided with controls for formatting, color selections, cut and paste, and more. . ListSearch—Enables you to perform an incremental search against the items in either a ListBox or DropDownList control. . MaskedEdit—Forces a user to enter a certain pattern of characters into a TextBox control. The MaskedEdit control is discussed in the section “Using the MaskedEdit Control.” . ModalPopup—Enables you to display a modal pop-up. When the modal pop-up appears, the remainder of the page is grayed out, preventing you from interacting with the page. . MultiHandleSlider—Enables you to select multiple values through a graphical slider interface. . MutuallyExclusiveCheckBox—Enables you to treat a set of CheckBox controls like a set of RadioButton controls. Only one CheckBox can be selected at a time. . NoBot—Attempts to prevent spam robots from posting advertisements to your website. The control attempts to detect whether a human or robot is posting content. . NumericUpDown—Enables you to display up and down buttons next to a TextBox control. When you click the up and down buttons, you can cycle through a set of numbers or other items such as month names or flavors of ice cream. . PagingBulletedList—Enables you to display different content depending on the bullet clicked in a BulletedList control. From the Library of Wow! eBook ptg 1739 Using the AutoComplete Control 39 . PasswordStrength—Enables you to display a pop-up box that indicates the security strength of a password as a user selects a new password. (This control is used in the sample application described in the last chapter.) . PopupControl—Displays a pop-up window. . Rating—Enables you to rate an item on a scale. (This control is used in the sample application described in the last chapter.) . ReorderList—Enables you to render an interactive list of items that supports reordering through drag and drop. . ResizableControl—Enables you to resize images and other content contained on a web page. . RoundedCorners—Enables you to add rounded corners around an element on a page. . SeaDragon—Provides functionality to interact with an image, such as zooming in, zooming out, and making the image fill the entire browser window. . Slider—Enables you to create either a horizontal or vertical slider for selecting a particular value in a range of values. . SlideShow—Displays a slide show of images. The control can render Next, Previous, Play, and Stop buttons. . Tabs—Enables you to create a tabbed interface. Switching tabs does not require a postback. . TextBoxWatermark—Enables you to display background text inside of a TextBox control. When focus is given to TextBox, the background text disappears. . ToggleButton—Enables you to customize the appearance of a CheckBox control. Instead of displaying a check box, you can display a thumbs-up or thumbs-down image. . UpdatePanelAnimation—Enables you to display an animation while UpdatePanel is performing an asynchronous postback. We discuss the UpdatePanelAnimation control in the section “Using the UpdatePanelAnimation Control.” . ValidatorCallout—Can be used with any of the standard ASP.NET validation con- trols to create a callout effect when a validation error occurs. In the following sections, we examine six of the controls in more detail: AutoComplete, DragPanel, FilteredTextBox, MaskedEdit, Animation, and UpdatePanelAnimation. Using the AutoComplete Control The one control I use most often from the ASP.NET AJAX Control Toolkit is the AutoComplete control, which enables you to convert a standard ASP.NET TextBox control into something resembling a combo box. As you enter text into the TextBox control, a list of matching options displays beneath the control (see Figure 39.5). From the Library of Wow! eBook ptg 1740 CHAPTER 39 Using the ASP.NET AJAX Control Toolkit The cool thing about the AutoComplete control is that it retrieves the matching options from the web server, using an Ajax call, while you type. You can use the AutoComplete control to efficiently search through a database of billions of items because the entire database of items never needs to be downloaded to the browser. The AutoComplete control is smart enough to cache items on the client. If you enter the same text into a TextBox control that you enter previously, the AutoComplete control can grab the suggestions from its cache instead of performing another Ajax call to retrieve the same information. In this section, you learn how to use the AutoComplete extender control. You learn how to expose the items displayed by the AutoComplete control from a web method contained in the same page as the AutoComplete control and from a web method exposed by a separate web service. Finally, you learn how to associate hidden values (such as primary keys) with each item displayed by the AutoComplete control. Using the AutoCompleteExtender with a Page Method If you don’t need to use suggestions in more than one page, it makes sense to expose the list of auto-complete suggestions from a page method. You can create a web method that is a static method on a page. For example, the page in Listing 39.1 contains an AutoComplete extender control, which displays movie title suggestions while the user enters a movie title into a TextBox control. LISTING 39.1 AutoCompletePageMethod.aspx <%@ Page Language=”C#” %> <%@ Register TagPrefix=”ajax” Namespace=”AjaxControlToolkit” Assembly=”AjaxControlToolkit” %> <%@ Import Namespace=”System.Linq” %> FIGURE 39.5 Using the AutoComplete extender control. From the Library of Wow! eBook ptg 1741 Using the AutoComplete Control 39 <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <script runat=”server”> [System.Web.Services.WebMethod] public static string[] GetSuggestions(string prefixText, int count) { MyDatabaseDataContext db = new MyDatabaseDataContext(); return db.Movies .Where( m => m.Title.StartsWith(prefixText) ) .OrderBy( m => m.Title ) .Select( m => m.Title) .Take(count) .ToArray(); } protected void btnSubmit_Click(object sender, EventArgs e) { lblSelectedMovieTitle.Text = txtMovieTitle.Text; } </script> <html xmlns=”http://www.w3.org/1999/xhtml”> <head runat=”server”> <title>AutoComplete Page Method</title> </head> <body> <form id=”form1” runat=”server”> <div> <asp:ScriptManager ID=”sm1” runat=”server” /> <asp:Label id=”lblMovieTitle” Text=”Movie:” AssociatedControlID=”txtMovieTitle” Runat=”server” /> <asp:TextBox id=”txtMovieTitle” AutoComplete=”off” Runat=”server” /> <ajax:AutoCompleteExtender id=”ace1” TargetControlID=”txtMovieTitle” ServiceMethod=”GetSuggestions” MinimumPrefixLength=”1” runat=”server” /> <asp:Button From the Library of Wow! eBook ptg 1742 CHAPTER 39 Using the ASP.NET AJAX Control Toolkit id=”btnSubmit” Text=”Submit” OnClick=”btnSubmit_Click” Runat=”server” /> <br /><br /> <asp:Label id=”lblSelectedMovieTitle” runat=”server” /> </div> </form> </body> </html> In Listing 39.1, the AutoComplete extender control is declared like this: <ajax:AutoCompleteExtender id=”ace1” TargetControlID=”txtMovieTitle” ServiceMethod=”GetSuggestions” MinimumPrefixLength=”1” runat=”server” /> The TargetControlID property refers to the control that is extended. In this case, the AutoComplete extender extends a TextBox control named txtMovieTitle with auto- complete functionality. NOTE Notice that the extended TextBox control includes an AutoComplete=”off” attribute. This attribute is necessary to disable the built-in browser auto-complete for Internet Explorer and Firefox. Realize that there is an important difference between AutoComplete=”off” and AutoComplete=”false”. The MinimumPrefixLength property represents the number of characters that must be entered before suggestions displays. The default value for this property is 3. I’ve changed the default to 1 so that suggestions appear immediately after you start typing. The ServiceMethod property refers to the name of a web method. In this case, the web method is defined in the same page as the AutoComplete control as a static page method. The GetSuggestions() method looks like this: [System.Web.Services.WebMethod] public static string[] GetSuggestions(string prefixText, int count) From the Library of Wow! eBook ptg 1743 Using the AutoComplete Control 39 { MyDatabaseDataContext db = new MyDatabaseDataContext(); return db.Movies .Where( m => m.Title.StartsWith(prefixText) ) .OrderBy( m => m.Title ) .Select( m => m.Title) .Take(count) .ToArray(); } The GetSuggestions() method is declared as a static method—this is a requirement. Furthermore, notice that the method is decorated with the WebMethod attribute. The GetSuggestions() method must have prefixText and count parameters. The prefixText parameter represents the text entered into the TextBox being extended so far. The count parameter represents the number of suggestions to return. The GetSuggestions() method returns matching movie titles from the Movie database table. A LINQ to SQL query retrieves movie records that start with the prefix text. NOTE To learn more about LINQ to SQL, see Chapter 20, “Data Access with LINQ to SQL.” Using the AutoCompleteExtender with a Web Service Method If you prefer, you can retrieve the auto-complete suggestions from a separate web service instead of a page method. For example, the web service in Listing 39.2, the FileService web service, retrieves a list of matching filenames from the file system. LISTING 39.2 FileService.asmx <%@ WebService Language=”C#” Class=”FileService” %> using System; using System.Web; using System.Web.Services; using System.Web.Services.Protocols; using System.IO; using System.Linq; [WebService(Namespace = “http://tempuri.org/”)] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)] [System.Web.Script.Services.ScriptService] public class FileService : System.Web.Services.WebService { [WebMethod] From the Library of Wow! eBook . Control.” . ModalPopup—Enables you to display a modal pop-up. When the modal pop-up appears, the remainder of the page is grayed out, preventing you from interacting with the page. . MultiHandleSlider—Enables. appears or disappears. . ColorPicker—Provides an interactive pop-up control that enables you to graphically choose colors. . ComboBox—Is similar to a traditional ASP. NET DropDownList, except. ptg 17 34 CHAPTER 39 Using the ASP. NET AJAX Control Toolkit Using the ASP. NET AJAX Control Toolkit The ASP. NET AJAX Control Toolkit is not included with ASP. NET 4 Framework. The