The key benefit of Ajax is responsiveness. An Ajax application, when done properly, provides a better experience for the user. Even if the user can't do anything new (or do anything faster), this improved experience can make your web application seem more modern and sophisticated. If you're creating a website that's competing against other similar sites, you just might find that Ajax allows you to distinguish your work from the rest of the pack.

Ajax can also provide genuinely new features that aren't possible in traditional web pages. For example, Ajax pages often use JavaScript code that reacts to client-side events like mouse movements and key presses. These events occur frequently, so it's not practical to deal with them using the postback model. For example, imagine you want to highlight a TextBox when the user moves the mouse over it. With the postback approach, you'd need to send the entire page back to the web server, regenerate it, and refresh it in the browser—by which point the mouse might be somewhere completely different. This approach is clearly impractical. However, an Ajax page can deal with this scenario because it can react immediately, updating the page if needed or requesting additional information from the web server in the background. While this request is under way, the user is free to keep working with the page. In fact, the user won't even realize that the request is taking place.

There are two key challenges to using Ajax. The first is complexity. Writing the JavaScript code needed to implement an Ajax application is a major feat. Fortunately, you'll sidestep this problem in this chapter, because you'll use ASP.NET's Ajax-enabled features. That means you'll let Microsoft manage the complexity instead of worrying about it yourself.

The other challenge to using Ajax is browser support. The technology that supports Ajax has existed for several years, but it's only now found consistently in all major browsers. If you use the Ajax features that ASP.NET provides, they'll work in Internet Explorer 5 and newer, Opera 7.6 and newer, Safari 1.2 and newer, Firefox, and Google Chrome. This captures the overwhelming majority of web users. (The actual percentage depends on your audience, but over 95 percent is a good, conservative assumption.)

But what about the minority of users who are using old browsers or have JavaScript switched off? It all depends on the feature you're using and the way it's implemented. If you're using the partial rendering support that's provided by ASP.NET's UpdatePanel control (which you'll learn about in this chapter), your page will continue to work with non-Ajax-enabled browsers—it will simply use full postbacks instead of more streamlined partial updates. On the other hand, if you're using a more advanced Ajax-enabled web control, you may find that it doesn't work properly or at all. The only way to know is to switch JavaScript off in your browser and try it out. Either way, there's a price to be paid for slick Ajax features, and that price is increased web browser requirements.

Finally, Ajax applications introduce a few quirks that might not be to your liking. Web pages that use Ajax often do a lot of work on a single page. This is different than traditional web pages, which often move the user from one page to another to complete a task. Although the multiple-page approach is a little more roundabout, it allows the user to place bookmarks along the way and use the browser's Back and Forward buttons to step through the sequence. These techniques usually don't work with Ajax applications, because there's only a single page to bookmark or navigate to, and the URL for that page doesn't capture the user's current state. This isn't a showstopper of an issue, but it might cause you to consider the design of your web application a little more closely.

There are a variety of ways to implement Ajax in any web application, including ASP.NET. To implement it on your own, you need to have a thorough understanding of JavaScript, because it's JavaScript code that runs in the browser, requesting the new information from the web server when needed and updating the page accordingly. Although JavaScript isn't terribly complex, it's remarkably difficult to program correctly, for two reasons:

In this chapter, you won't use JavaScript directly. Instead, you'll use a higher-level model called ASP.NET AJAX. ASP.NET AJAX gives you a set of server-side components and controls that you can use when designing your web page. These components automatically render all the JavaScript you need to get the effect you want. The result is that you can create a page with Ajax effects while programming with a familiar (and much more productive) model of server-side objects. Of course, you won't get quite as much control to customize every last detail about the way your web pages work, but you will get some great functionality with minimal effort.

In order to use ASP.NET AJAX, you need to place a new web control on your page. This control is the ScriptManager, and it's the brains of ASP.NET AJAX.

Like all ASP.NET AJAX controls, the ScriptManager is placed on a Toolbox tab named AJAX Extensions. When you can drag the ScriptManager onto your page, you'll end up with this declaration:

<asp:ScriptManager ID="ScriptManager1" runat="server"></asp:ScriptManager>

At design time, the ScriptManager appears as a blank gray box. But when you request a page that uses the ScriptManager you won't see anything, because the ScriptManager doesn't generate any HTML tags. Instead, the ScriptManager performs a different task—it adds the links to the ASP.NET AJAX JavaScript libraries. It does that by inserting a script block that looks something like this:

<script src="/YourWebSite/ScriptResource.axd?d=RUSU1mI ..."
 type="text/javascript">
</script>

This script block doesn't contain any code. Instead, it uses the src attribute to pull the JavaScript code out of a separate file.

However, the ScriptManager is a bit craftier than you might expect. Rather than use a separate file to get its JavaScript (which would then need to be deployed along with your application), the src attribute uses a long, strange-looking URL that points to ScriptResource.axd. ScriptResource.axd isn't an actual file—instead, it's a resource that tells ASP.NET to find a JavaScript file that's embedded in one of the compiled .NET 4 assemblies. The long query string argument at the end of the URL tells the ScriptResource.axd extension which file to send to the browser.

The JavaScript files that ASP.NET AJAX uses contain hundreds of lines of highly complex, concise code that forms the basis for all the Ajax features you'll see in this chapter. However, these files are quite compact, requiring the client to download less than 200 KB of script code (depending on the features that you're using). When you're visiting an ASP.NET AJAX–powered site, the script code is only downloaded once, and then cached by the browser so it can be used in various ways by various pages in the website. (In addition, ASP.NET sends a compressed version of the script document, if the browser supports it. Currently, ASP.NET uses compression when receiving requests from Internet Explorer 7 or later.) The bottom line is pages that use ASP.NET AJAX features don't require significantly longer download times.

Each page that uses ASP.NET AJAX features requires an instance of the ScriptManager. However, you can only use one ScriptManager on a page. ASP.NET AJAX-enabled controls can interact with the ScriptManager, asking it to render links to additional JavaScript resources.

Now that you've taken a brief overview of Ajax, it's time to start building Ajax-enabled pages. In this chapter, you'll consider the following topics:

To try out the UpdatePanel, it makes sense to build a simple test page.

The following example (Figure 25-2) uses a simple page that includes two ingredients: an animated GIF image, and a shaded box that shows the current time and includes a Refresh Time button. When you click the Refresh Time button, the page grabs the current time from the web server and updates the label. However, the refresh process uses a partial update. As a result, the page won't flicker when it takes place. The animated GIF helps illustrate the point—even as you click the button to refresh the label, the lamp continues bubbling without a pause or hiccup.

Figure 25.2. Refreshing a label with a partial update

Building this page is easy. First, you need to add the ScriptManager control to the page. Like all controls that use ASP.NET AJAX, the UpdatePanel works in conjunction with the ScriptManager. If you don't have it in your page, the UpdatePanel won't work (and you'll receive an exception when you run the page). Furthermore, the ScriptManager needs to appear before the UpdatePanel, because the rendered page must have the JavaScript script block in place before the UpdatePanel can use it. It's a good idea to always place the ScriptManager at the top of the <form> section of the page.

Next, you need to add the content to the page. The animated GIF is fairly straightforward—you can use an ordinary <img> element to show it. However, the label and button require a bit more effort. To refresh the label using a partial refresh, you need to wrap it in an UpdatePanel. So start by adding an UpdatePanel to your page, and then drag and drop the button and label inside.

The UpdatePanel has one role in life—to serve as a container for content that you want to refresh asynchronously. Interestingly enough, the UpdatePanel doesn't derive from Panel. Instead, it derives directly from Control. This design causes a few quirks that you should take into account.

First, the UpdatePanel is invisible. Unlike the standard ASP.NET Panel, an UpdatePanel doesn't support style settings. If you want to display a border around your UpdatePanel or change the background color, you'll need to place an ordinary Panel (or just a plain <div> tag) in your UpdatePanel. Here's how it's done in the example shown in Figure 25-2:

<asp:UpdatePanel ID="UpdatePanel1" runat="server" UpdateMode="Conditional">
  <ContentTemplate>
    <div style="background-color:LightYellow;padding: 20px">
      <asp:Label ID="lblTime" runat="server" Font-Bold="True"></asp:Label>
      <br />
      <br />
      <asp:Button ID="cmdRefreshTime" runat="server"
        Text="Refresh Time" />
    </div>

</ContentTemplate>
</asp:UpdatePanel>

This markup reveals another difference between the UpdatePanel and an ordinary Panel—the UpdatePanel uses a template. All the controls you add to an UpdatePanel are placed in an element named <ContentTemplate>. When the UpdatePanel renders itself, it copies the content from the ContentTemplate into the page. This seems like a fairly unimportant low-level detail, but it does have one important side effect. If you want to use code to dynamically add controls to an UpdatePanel, you can't use the UpdatePanel.Controls collection. Instead, you need to add new controls to the UpdatePanels.ContentTemplateContainer.Controls collection.

Now that you have the controls you need, you're ready to add the code. This part is easy—when the button is clicked, you simply react to the Click event and update the label:

Protected Sub cmdRefreshTime_Click(ByVal sender As Object, _
  ByVal e As EventArgs) Handles cmdRefreshTime.Click

    lblTime.Text = DateTime.Now.ToLongTimeString()
End Sub

Remarkably, that's all you need to do to complete this example. Now, when you click the Refresh Time button, the label will refresh without a full postback and without any flicker.

So how does it all work? Here's a blow-by-blow analysis of what's taking place:

The most impressive aspect of the UpdatePanel control is that it allows your web page to behave in the same way it would if you weren't using any Ajax techniques. There is a bit of a price to pay for this convenience—namely, the request might take a little longer than necessary because of all the extra work that's taking place. In a more streamlined do-it-yourself approach, you'd simply ask the web server for exactly what you need. In this example, that means you'd simply ask for the current time, rather than an entire HTML document.

However, in most scenarios the UpdatePanel's more long-winded approach doesn't introduce any noticeable delay. Even better, it gives you the ability to deal with much more complex scenarios—for example, when you're modifying a section of a web page much more dramatically. You'll see an example later in this chapter, when you use the UpdatePanel to improve the greeting card maker.

As you've seen, when the UpdatePanel performs its callback, the web page code runs in exactly the same way as if the page had been posted back. The only difference is the means of communication (the page uses an asynchronous call to get the new data) and the way the received data is dealt with (the UpdatePanel refreshes its inner content, but the remainder of the page is not changed). For that reason, you don't need to make significant changes to your server-side code or deal with new error conditions.

That said, problems can occur when performing an asynchronous postback just as they do when performing a synchronous postback. To find out what happens, you can add code like this to the event handler for the Page.Load event, which causes an unhandled exception to occur when an asynchronous callback takes place:

If Me.IsPostBack Then
    Throw New ApplicationException("This operation failed.")
End If

When the web page throws an unhandled exception, the error is caught by the ScriptManager and passed back to the client. The client-side JavaScript then throws a JavaScript error. What happens next depends on your browser settings, but usually browsers are configured to quietly suppress JavaScript errors. In Internet Explorer, an "Error on page" message appears in the status bar that indicates the problem. If you double-click this notification, a dialog box appears with the full details, as shown in Figure 25-3.

Figure 25.3. Displaying a client-side message about a server-side error

There's another option for dealing with the errors that occur during an asynchronous postback. You can use custom error pages, just as you do with ordinary web pages. All you need to do is add the <customErrors> element to the web.config file.

For example, here's a <customErrors> element that redirects all errors to the page named ErrorPage.aspx:

<configuration>
  <system.web>
    <customErrors defaultRedirect="ErrorPage.aspx" mode="On"></customErrors>
    ...
  </system.web>
</configuration>

Now, when the PageRequestManager is informed of an error it will redirect the browser to ErrorPage.aspx. It also adds an aspxerrorpath query string argument to the URL that indicates the URL of the page where the problem originated, as shown here:

http://localhost/Ajax/ErrorPage.aspx?aspxerrorpath=/Ajax/UpdatePanels.aspx

You can write code in ErrorPage.aspx that reads the aspxerrorpath information. For example, you might include a button that redirects the user to the original requested page, like this:

Dim url As String = Request.QueryString("aspxerrorpath")
If url <> "" Then Response.Redirect(url)

If your website uses custom error pages but you don't want them to apply to asynchronous postbacks, you must set the ScriptManager.AllowCustomErrorsRedirect property to false.

In complex pages, you might have more than one UpdatePanel. In this case, when one UpdatePanel triggers an update, all the UpdatePanel regions will be refreshed.

If you have more than one UpdatePanel and each one is completely self-contained, this isn't necessary. In this situation, you can configure the panels to update themselves independently. Simply change the UpdatePanel.UpdateMode property from Always to Conditional. Now, the UpdatePanel will refresh itself only if an event occurs in one of the controls in that UpdatePanel.

To try this out, create a page that has several UpdatePanel controls, each with its own time display and button. Then, add code that places the current time in the label of all three controls:

Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs) _
  Handles Me.Load
    lblTime1.Text = DateTime.Now.ToLongTimeString()
    lblTime2.Text = DateTime.Now.ToLongTimeString()
    lblTime3.Text = DateTime.Now.ToLongTimeString()
End Sub

Now, when you click one of the Refresh Time buttons, only the label in that panel will be updated. The other panels will remain untouched.

There's one caveat with this approach. If you perform an update that takes a long time, it could be interrupted by another update. As you know, ASP.NET AJAX posts the page back asynchronously, so the user is free to click other buttons while the postback is under way. ASP.NET AJAX doesn't allow concurrent updates, because it needs to ensure that other information—such as the page view state information, the session cookie, and so on—remains consistent. Instead, when a new asynchronous postback is started, the previous asynchronous postback is abandoned. For the most part, this is the behavior you want. If you want to prevent the user from interrupting an asynchronous postback, you can add JavaScript code that disables controls while the asynchronous postback is under way, but this takes significantly more work. Another option is to use the UpdateProgress control discussed later in this chapter.

So far, the examples you've seen have used the built-in behavior of the UpdatePanel. In the next example, you'll use the UpdatePanel in a slightly more sophisticated page, and you'll learn to control its refreshes with triggers.

Earlier in this book, you learned how to build a web page that allows the user to dynamically build a greeting card. This page lets the user specify several details—such as text, font, colors, border options, and so on—and then updates a portion of the page to show the greeting card.

Chapter 6 demonstrated two versions of the greeting card maker. The first version allowed the user to specify a number of options at once, and then click a button to update the greeting card. The second version used automatic postback events, so that the greeting card was updated after every change. This second approach gave a more immediate result, but the cost was a less responsive user interface with distracting flicker. If this version of the greeting card maker was running on a slow web server (or over a slow network), the problems get even worse. That's because after every postback the user is forced to wait for the page update before making another change.

The UpdatePanel gives you the ability to get the best of both versions. You can create a greeting card page that updates its display automatically but feels more responsive and doesn't lock the user out.

The simplest approach is to add a ScriptManager and wrap the entire web page—including the controls and the greeting card—in one giant UpdatePanel. Here's the markup you'd use:

<asp:ScriptManager ID="ScriptManager1" runat="server"></asp:ScriptManager>

<asp:UpdatePanel ID="UpdatePanel1" runat="server">
  <ContentTemplate>

    <!-- These are the controls for creating the greeting card. -->
    <div style="...">
      Choose a background color:<br />

<asp:DropDownList ID="lstBackColor" runat="server"
       Width="194px" AutoPostBack="True">
      </asp:DropDownList>
      <br /><br />
      Choose a foreground (text) color:<br />
      <asp:DropDownList ID="lstForeColor" runat="server"
       Height="22px" Width="194px" AutoPostBack="True" >
      </asp:DropDownList>
      <br /><br />
      Choose a font name:<br />
      <asp:DropDownList ID="lstFontName" runat="server"
       Height="22px" Width="194px" AutoPostBack="True">
      </asp:DropDownList>
      <br /><br />
      Specify a font size:<br />
      <asp:TextBox ID="txtFontSize" runat="server"
       AutoPostBack="True">
      </asp:TextBox>
      <br /><br />
      Choose a border style:<br />
      <asp:RadioButtonList ID="lstBorder" runat="server"
       Height="59px" Width="177px" Font-Size="X-Small"
       AutoPostBack="True" RepeatColumns="2">
      </asp:RadioButtonList>
      <br /><br />
      <asp:CheckBox ID="chkPicture" runat="server"
       Text="Add the Default Picture" AutoPostBack="True">
      </asp:CheckBox>
      <br /><br />
      Enter the greeting text below:<br />
      <asp:TextBox ID="txtGreeting" runat="server"
       Height="85px" Width="240px" TextMode="MultiLine"
       AutoPostBack="True">
      </asp:TextBox>
    </div>

    <!-- This is the panel that shows the greeting card. -->
    <asp:Panel ID="pnlCard" runat="server" ... >
      <asp:Label ID="lblGreeting" runat="server" Width="272px"
        Height="150px"></asp:Label>
      <br />
      <asp:Image ID="imgDefault" runat="server" Width="212px" Height="160px"
        Visible="False"></asp:Image>
    </asp:Panel>

  </ContentTemplate>
</asp:UpdatePanel>

The greeting card is then generated when the Page.Load event fires:

Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs) _
  Handles Me.Load

    If Not Me.IsPostBack Then
        ' (Initialize all the controls here.)
    Else
        ' Refresh the greeting card.
        UpdateCard()
    End If
End Sub

The UpdatePanel watches its child controls and intercepts any events that could trigger a postback. The Button.Click is an obvious example, but in this example the TextBox.TextChanged and ListBox.SelectedItemChanged events also trigger a postback, because these controls set the AutoPostBack property to True. Thus, these events are also intercepted by the UpdatePanel. If these controls didn't use the AutoPostBack property, they wouldn't trigger a postback, the UpdatePanel wouldn't get involved, and the greeting card won't be updated until another control causes a postback.

This solution achieves the desired result. Although the greeting card page looks essentially the same (see Figure 25-4), when you interact with the controls on the left, the card on the right is updated without a postback. If you make several changes in quick succession, you'll trigger several postbacks, and the result from the last postback (with the completely updated card) will be used.

Figure 25.4. The greeting card maker, Ajax style

Although this example works perfectly well, it's doing more work than necessary. Because the entire page is wrapped in the UpdatePanel, the HTML for the entire page is refreshed. A better option is to wrap just the label and image that represents the greeting card in the UpdatePanel. Unfortunately, this won't work. Once you move the other controls out of the UpdatePanel, their events won't be intercepted any longer, and they'll trigger full-page postbacks with the familiar flicker.

The solution is to explicitly tell the UpdatePanel to monitor those controls, even though they aren't inside the UpdatePanel. You can do this by adding triggers to the UpdatePanel. You add one trigger for each button.

Here's the markup you need:

<asp:ScriptManager ID="ScriptManager1" runat="server"></asp:ScriptManager>

<!-- The controls for creating the greeting card go here. -->

<asp:UpdatePanel ID="UpdatePanel1" runat="server">
  <ContentTemplate>

<!-- This is the panel that shows the greeting card. -->
    <asp:Panel ID="pnlCard" runat="server" ... >
      <asp:Label ID="lblGreeting" runat="server" Width="272px"
        Height="150px"></asp:Label>
      <asp:Image ID="imgDefault" runat="server" Width="212px" Height="160px"
        Visible="False"></asp:Image>
    </asp:Panel>
  </ContentTemplate>

  <Triggers>
    <asp:AsyncPostBackTrigger ControlID="lstBackColor" />
    <asp:AsyncPostBackTrigger ControlID="lstForeColor" />
    <asp:AsyncPostBackTrigger ControlID="lstFontName" />
    <asp:AsyncPostBackTrigger ControlID="txtFontSize" />
    <asp:AsyncPostBackTrigger ControlID="lstBorder" />
    <asp:AsyncPostBackTrigger ControlID="chkPicture" />
    <asp:AsyncPostBackTrigger ControlID="txtGreeting" />
  </Triggers>
</asp:UpdatePanel>

These triggers tell the UpdatePanel to intercept the default event in these seven controls. (You could specify the event you want to monitor by setting the EventName property of the trigger, but you don't need to, because you're using the most commonly used default event for each one.) As a result, the page works the same as it did before—it just refreshes a smaller portion of the page after each asynchronous request.

Technically, the UpdatePanel always uses triggers. All the controls inside an UpdatePanel automatically become the triggers for the UpdatePanel. However, you need to add the triggers if the controls are placed elsewhere in the page.

You can use triggers in one other way. Instead of using them to monitor more controls, you can use them to tell the UpdatePanel to ignore certain controls. For example, imagine you have a button in your UpdatePanel. Ordinarily, clicking that button will trigger an asynchronous request and partial update. If you want it to trigger a full-page postback instead, you simply need to add a PostBackTrigger (instead of an AsynchronousPostBackTrigger).

For example, here's an UpdatePanel that contains a nested button that triggers a full postback rather than an asynchronous postback:

<asp:UpdatePanel ID="UpdatePanel1" runat="server" UpdateMode="Conditional">
  <ContentTemplate>
    <asp:Label ID="Label1" runat="server" Font-Bold="True"></asp:Label>
    <br />
    <br />
    <asp:Button ID="cmdPostback" runat="server" Text="Refresh Full Page" />
  </ContentTemplate>
  <Triggers>
    <asp:PostBackTrigger ControlID="cmdPostback" />
  </Triggers>
</asp:UpdatePanel>

This technique isn't as common, but it can be useful if you have several controls in an UpdatePanel that perform limited updates (and so use asynchronous request) and one that performs more significant changes to the whole page (and so uses a full-page postback).

When you add the UpdateProgress control to a page, you get the ability to specify some content that will appear as soon as an asynchronous request is started and disappear as soon as the request is finished. This content can include a fixed message, but many people prefer to use an animated GIF, because it more clearly suggests that the page is still at work. Often, this animated GIF simulates a progress bar.

Figure 25-5 shows a page that uses the UpdateProgress control at three different points in its life cycle. The top figure shows the page as it first appears, with a straightforward UpdatePanel control containing a button. When the button is clicked, the asynchronous callback process begins. At this point, the contents of the UpdateProgress control appear underneath (as shown in the middle figure). In this example, the UpdateProgress includes a text message and an animated GIF that appears as a progress bar, with green blocks that perpetually fill it from left to right, and then start over. When the callback is complete, the UpdateProgress disappears and the UpdatePanel is updated, as shown in the bottom figure.

Figure 25.5. A wait indicator

The markup for this page defines an UpdatePanel followed by an UpdateProgress:

<asp:UpdatePanel ID="UpdatePanel1" runat="server">
  <ContentTemplate>
    <div style="background-color:#FFFFE0;padding: 20px">
      <asp:Label ID="lblTime" runat="server" Font-Bold="True"></asp:Label>
      <br /><br />
      <asp:Button ID="cmdRefreshTime" runat="server"
       Text="Start the Refresh Process" />
    </div>
  </ContentTemplate>
</asp:UpdatePanel>
<br />

<asp:UpdateProgress ID="updateProgress1" runat="server">
  <ProgressTemplate>
    <div style="font-size: xx-small">
      Contacting Server ... <img src="wait.gif" alt="Waiting..." />
    </div>
  </ProgressTemplate>
</asp:UpdateProgress>

This isn't the only possible arrangement. Depending on the layout you want, you can place your UpdateProgress control somewhere inside your UpdatePanel control.

The code for this page has a slight modification from the earlier examples. Because the UpdateProgress control only shows its content while the asynchronous callback is under way, it only makes sense to use it with an operation that takes time. Otherwise, the UpdateProgress will only show its ProgressTemplate for a few fractions of a second. To simulate a slow process, you can add a line to delay your code 10 seconds, as shown here:

Protected Sub cmdRefreshTime_Click(ByVal sender As Object, _
  ByVal e As EventArgs) Handles cmdRefreshTime.Click
    System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10))
    lblTime.Text = DateTime.Now.ToLongTimeString()
End Sub

There's no need to explicitly link the UpdateProgress control to your UpdatePanel control. The UpdateProgress automatically shows its ProgressTemplate whenever any UpdatePanel begins a callback. However, if you have a complex page with more than one UpdatePanel, you can choose to limit your UpdateProgress to pay attention to just one of them. To do so, simply set the UpdateProgress.AssociatedUpdatePanelID property with the ID of the appropriate UpdatePanel. You can even add multiple UpdateProgress controls to the same page, and link each one to a different UpdatePanel.

The UpdateProgress control supports one other detail: a cancel button. When the user clicks a cancel button, the asynchronous callback will be cancelled immediately, the UpdateProgress content will disappear, and the page will revert to its original state.

Adding a cancel button is a two-step process. First you need to add a fairly intimidating block of JavaScript code, which you can copy verbatim. You should place this code at the end of your page, after all your content but just before the </body> end tag. Here's the code you need, in its rightful place:

<%@ Page Language="VB" AutoEventWireup="false" CodeFile="WaitIndicator.aspx.vb"
 Inherits="WaitIndicator" %>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    ...
</head>
<body>
  <form ID="form1" runat="server">
    ...
  </form>

  <script type="text/javascript">
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    prm.add_initializeRequest(InitializeRequest);

    function InitializeRequest(sender, args)
    {
        if (prm.get_isInAsyncPostBack())
        {
            args.set_cancel(true);
        }
    }

    function AbortPostBack()
    {
        if (prm.get_isInAsyncPostBack()) {
         prm.abortPostBack();
        }
    }
    </script>
</body>
</html>

Once you've added this code, you can use JavaScript code to call its AbortPostBack() function at any time and cancel the callback. The easiest way to do to this is to connect a JavaScript event to the AbortPostBack() function using a JavaScript event attribute. You can add a JavaScript event attribute to virtually any HTML element. For example, you can deal with client-side clicks using the onclick attribute. Here's a basic HTML button (not a server control) that uses this technique to connect itself to the AbortPostBack() function:

<input ID="cmdCancel" onclick="AbortPostBack()" type="button" value="Cancel" />

If you click this Cancel button, the client-side AbortPostBack() function will be triggered and the callback will be cancelled immediately. Typically, you'll place this button (or an element like this) in the ProgressTemplate of the UpdateProgress control, as shown in Figure 25-6.

Figure 25.6. An UpdateProgress control with a cancel button

Don't confuse this approach with server-side event handling—the client-side onclick attribute allows you to intercept an event in the browser and process it using JavaScript code. The server doesn't get involved at all. In fact, when you cancel an operation, the server continues to process the request, but the browser simply closes the connection and stops listening for the response.

To get the ASP.NET AJAX Control Toolkit, surf to http://www.asp.net/ajaxlibrary/act.ashx. You can follow the links to the download page, where you'll see several download options, depending on your version of .NET and whether you want the source code. At the time of this writing, the simplest download option is a 6.4 MB ZIP file named AjaxControlToolkit.Binary.NET4.zip, which is designed for ASP.NET 4 and doesn't include the source code. Once you've downloaded this ZIP file, you can extract the files it contains to a more permanent location on your hard drive. (If you need support for ASP.NET 3.5, you'll find a similar download that targets that version of .NET.)

Inside the ZIP file, you'll find a central assembly named AjaxControlToolkit.dll and a host of smaller satellite assemblies that support localization for different cultures. You'll also see a zipped folder named AjaxControlToolkitSampleSite, which contains a huge sample website that demonstrates all the ASP.NET AJAX Control Toolkit ingredients, and a ReadMe.html file with installation instructions.

To get started developing with ASP.NET AJAX Control Toolkit, you could simply open the AjaxControlToolkitSampleSite (or copy the contents of its Bin subfolder to the Bin subfolder in one of your web applications). However, life is much easier if you get Visual Studio to help you out by adding the new components to the Toolbox. Here's how:

Figure 25-7 shows some of the controls that will appear in the new Toolbox tab.

Figure 25.7. Adding the ASP.NET AJAX Control Toolkit to the Toolbox

Now you can use the components from the ASP.NET AJAX Control Toolkit in any web page in any website. First, begin by adding the ScriptManager control to the web page. Then, head to the new Toolbox tab you created and drag the ASP.NET AJAX control you want onto your page. The first time you do add a component from the ASP.NET AJAX Control Toolkit, Visual Studio will copy the AjaxControlToolkit.dll assembly to the Bin folder of your web application, along with the localization assemblies. It will also add a Register directive that maps the controls in AjaxControlToolkit.dll to the namespace prefix asp so they're available in your code:

<%@ Register Assembly="AjaxControlToolkit" Namespace="AjaxControlToolkit"
    TagPrefix="asp" %>

The ASP.NET AJAX Control Toolkit is stuffed full of useful components. In the following sections, you'll get your feet wet by considering just two of the controls you'll find—the Accordion and the AutoCompleteExtender.

The Accordion is a container that stacks several panels on top of one another, and allows you to view one at a time. Each panel has a header (which usually displays a section title) and some content. When you click the header of one of the panels, that panel is expanded and the other panels are collapsed, leaving just their headers visible. Figure 25-8 demonstrates the effect you'll see as you click different headers.

Figure 25.8. Choosing a panel in the Accordion

It goes without saying that the collapsing behavior happens without a full-page postback. In fact, there's no need to contact the web server at all. The first time the page is generated, all the panels are rendered to HTML, but they're hidden using CSS style attributes. When you click a header, a JavaScript routine runs and changes these style attributes. (In truth, the Accordion control is a bit more sophisticated than that. When you choose a new panel, it gradually expands into view, which is much more impressive than simply popping into existence in one step. Furthermore, you can set the FadeTransitions property to True if you want panels to fade into and out of sight when you change from one panel to another.)

Using the Accordion control is a bit like using the MultiView control you learned about in Chapter 10. The Accordion control contains a collection of AccordionPane controls. Each AccordionPane represents a separate panel in the Accordion.

Here's an example that illustrates this structure by putting two AccordionPane objects inside the Accordion:

<asp:Accordion ID="Accordion1" runat="server">
  <Panes>
    <asp:AccordionPane runat="server">

...
    </asp:AccordionPane>

    <asp:AccordionPane runat="server">
      ...
    </asp:AccordionPane>
  </Panes>
</asp:Accordion>

Each AccordionPane consists of two sections. The Header section is used for the clickable header of the panel, while the Content holds the details inside. Here's the markup you need to create the example shown in Figure 25-6:

<asp:Accordion ID="Accordion1" runat="server"
  HeaderCssClass="accordionHeader"
  HeaderSelectedCssClass="accordionHeaderSelected"
  ContentCssClass="accordionContent">

  <Panes>
    <asp:AccordionPane ID="paneColors" runat="server">
      <Header>Colors</Header>
      <Content>
        Choose a background color:<br />
        <asp:DropDownList ID="lstBackColor" runat="server"
         Width="194px" AutoPostBack="True">
        </asp:DropDownList>
        <br /><br />
        Choose a foreground (text) color:<br />
        <asp:DropDownList ID="lstForeColor" runat="server"
         Height="22px" Width="194px" AutoPostBack="True" >
        </asp:DropDownList>
      </Content>
    </asp:AccordionPane>

    <asp:AccordionPane ID="paneText" runat="server">
      <Header>Text</Header>
      <Content>
        Choose a font name:<br />
        <asp:DropDownList ID="lstFontName" runat="server"
         Height="22px" Width="194px" AutoPostBack="True">
        </asp:DropDownList>
        <br /><br />

Specify a font size:<br />
        <asp:TextBox ID="txtFontSize" runat="server"
         AutoPostBack="True">
        </asp:TextBox>
        <br /><br />
        Enter the greeting text below:<br />
        <asp:TextBox ID="txtGreeting" runat="server"
         Height="85px" Width="240px" TextMode="MultiLine"
         AutoPostBack="True">
        </asp:TextBox>
      </Content>
    </asp:AccordionPane>

    <asp:AccordionPane ID="paneExtras" runat="server">
      <Header>Other</Header>
      <Content>
        Choose a border style:<br />
        <asp:RadioButtonList ID="lstBorder" runat="server"
         Height="59px" Width="177px" Font-Size="X-Small"
         AutoPostBack="True" RepeatColumns="2">
        </asp:RadioButtonList>
        <br /><br />
        <asp:CheckBox ID="chkPicture" runat="server"
         Text="Add the Default Picture" AutoPostBack="True">
        </asp:CheckBox>
        </Content>
    </asp:AccordionPane>
  </Panes>
</asp:Accordion>

Along with the content, this example adds three properties: HeaderCssClass, HeaderSelectedCssClass, and ContentCssClass. These properties take the names of CSS styles that the Accordion uses to format the appropriate region. The styles are defined in a separate style sheet, and look like this:

.accordionHeader
{
    border: 1px solid #2F4F4F;
    color: white;
    background-color: #2E4d7B;
    padding: 5px;
    margin-top: 5px;
    cursor: pointer;
}

.accordionHeaderSelected
{
    border: 1px solid #2F4F4F;
    color: white;
    background-color: #5078B3;
    padding: 5px;
    margin-top: 5px;
    cursor: pointer;

}

.accordionContent
{
    background-color: #D3DEEF;
    border: 1px dashed;
    border-top: none;
    padding: 5px;
}

Chapter 12 has more about styles. You don't need to use them with the Accordion—after all, you could just set the formatting properties of your controls, or wrap each separate section in a formatted Panel or <div> element—but the style approach is pretty convenient once you get used to it.

You can really fine-tune the display that the Accordion uses by setting a few more properties. TransitionDuration sets the number of milliseconds that the collapsing and expanding animation lasts. FramesPerSecond controls how smooth the transition animation is—a higher value produces better quality, but requires more work from the browser. Finally, AutoSize lets you control how the Accordion expands when you show a panel with a large amount of content. Use a value of None to let the Accordion grow as large as it needs (in which case other content underneath the Accordion is simply bumped out of the way). Use Limit or Fill to restrict the Accordion to whatever you've set in the Height property (the difference is the Limit allows the Accordion to shrink smaller, while Fill keeps it at the maximum height by leaving any unused space blank). With Limit or Fill, the Accordion panels will use scrolling if they can't fit all their content into the available space.

Clearly, the Accordion is a simple-to-use, yet impressive way to deal with dense displays of data and groups of information. If you want to have a similar collapsing and expanding effect with a single panel, you might want to try another one of the components in the ASP.NET AJAX Control Toolkit—the CollapsiblePanelExtender.

The Accordion is an example of a completely new control that has ASP.NET AJAX features baked in. Although this is a perfectly reasonable approach to integrating Ajax techniques with the web control model, it's not the most common solution that you'll see used in ASP.NET AJAX Control Toolkit. In fact, the ASP.NET AJAX Control Toolkit includes just a few new controls, and a much larger set of control extenders.

A control extender is a .NET component that adds features to an existing ASP.NET control. Control extenders allow you to use the same Ajax effects with countless different controls. This is useful when you're dealing with multipurpose features such as automatic completion, drag-and-drop, animation, resizing, collapsing, masked editing, and so on.

One of the many control extenders in the ASP.NET AJAX Control Toolkit is the AutoCompleteExtender, which allows you to show a list of suggestions while a user types in another control (such as a text box). Figure 25-9 shows the AutoCompleteExtender at work on an ordinary TextBox control. As the user types, the drop-down list offers suggestions. If the user clicks one of these items in the list, the corresponding text is copied to the text box.

Figure 25.9. Providing an autocomplete list of names

To create this example, you need an ordinary text box, like this:

Contact Name:<asp:TextBox ID="txtName" runat="server"></asp:TextBox>

Next, you need to add the ScriptManager and an AutoCompleteExtender control that extends the text box with the autocomplete feature. The trick is that the list of suggestions needs to be retrieved from a specialized code routine called a web method, which you need to create in your page.

Here's an example of how you might define the AutoCompleteExtender. It uses the TargetControlID property to bind itself to the txtName text box, and it sets the MinimumPrefixLength property to 2, which means autocomplete suggestions won't be provided until the user has entered at least two characters of text. Finally, the ServiceMethod property indicates the web method you're going to use is named GetNames(). Before you can run this page, you need to create that method.

<asp:AutoCompleteExtender ID="autoComplete1" runat="server"
  TargetControlID="txtName" ServiceMethod="GetNames" MinimumPrefixLength="2">
</asp:AutoCompleteExtender>

The next step is to create the GetNames() web method. Here's the basic method you need to add to the code-behind class of your web page:

<System.Web.Services.WebMethod> _
<System.Web.Script.Services.ScriptMethod> _
Public Shared Function GetNames(ByVal prefixText As String, _
  ByVal count As Integer) As List(Of String)
    ...
End Function

The web method accepts two parameters, which indicate the text the user has typed so far and the desired number of matches (which is ten by default). It returns the list of suggestions. The two attributes that precede the GetNames() method indicate that it's a web method (meaning the client should be allowed to call it directly with HTTP requests) and that it supports JavaScript calls (which is what the AutoCompleteExtender uses).

Actually writing the code that retrieves or generates the suggestion list can be quite tedious. In this example, the code retrieves the list of name suggestions from the Northwind database. To ensure that this step is performed just once (rather than every single time the user hits a key in the text box), the name list is cached using the techniques you learned about in Chapter 23:

Dim names As List(Of String)

' Check if the list is in the cache.
If HttpContext.Current.Cache("NameList") Is Nothing Then
    ' If not, regenerate the list. The ADO.NET code for this part
    ' isn't shown (but you can see it in the downloadable examples
    ' for this chapter.
    names = GetNameListFromDB()

    ' Store the name list in the cache for sixty minutes.
    HttpContext.Current.Cache.Insert("NameList", names, Nothing, _
      DateTime.Now.AddMinutes(60), TimeSpan.Zero)
Else
    ' Get the name list out of the cache.
    names = CType(HttpContext.Current.Cache("NameList"), List(Of String))
End If
...

With the list in hand, the next step is to cut down the list so it provides only the ten closest suggestions. In this example, the list is already sorted. This means you simply need to find the starting position—the first match that starts with the same letters as the prefix text. Here's the code that finds the first match:

...
Dim index As Integer = -1
For i As Integer = 0 To names.Count - 1
    ' Check if this is a suitable match.
    If names(i).StartsWith(prefixText) Then
        index = i
        Exit For
    End If
Next

' Give up if there isn't a match.
If index = −1 Then Return New List(Of String)()
...

The search code then begins at the index number position and moves through the list in an attempt to get ten matches. However, if it reaches the end of the list or finds a value that doesn't match the prefix, the search stops.

...
Dim wordList As New List(Of String)()
For i As Integer = index To (index + count - 1)
   ' Stop if the end of the list is reached.
   If i >= names.Count Then Exit For

   ' Stop if the names stop matching.
   If Not names(i).StartsWith(prefixText) Then Exit For

   wordList.Add(names(i))
Next
...

Finally, all the matches that were found are returned:

...
Return wordList

You now have all the code you need to create the effect shown in Figure 25-9.

The Accordion and AutoCompleteExtender only scratch the surface of the ASP.NET AJAX Control Toolkit, which currently includes about 50 components. The easiest way to start experimenting with other controls is to surf to http://www.asp.net/ajaxlibrary/act_tutorials.ashx, where you'll find a reference that describes each control and lets you try it out online.

Table 25-1 highlights some of the more interesting control extenders that are currently available in the ASP.NET AJAX Control Toolkit, and Table 25-2 lists the controls.