Documentation for: ASP.NET Ajax Version 1.0

This documentation is for a previous version. For the current released version, see the ASP.NET Ajax documentation on MSDN.

 

 

 

 

 

 

 

Skip Navigation Links.
Tutorials
Sample ASP.NET AJAX Application
ASP.NET AJAX and JavaScript
Extending JavaScript with ASP.NET AJAX
Creating Custom Client Script in ASP.NET AJAX
Dynamically Assigning ASP.NET AJAX Script References
Globalizing a Date by Using Client Script
Embedding a JavaScript File as a Resource in an Assembly
Embedding Localized Resources for a JavaScript File
Adding Localized Resources to a JavaScript File
Creating Custom Client Events
The UpdatePanel Control
Introduction to the UpdatePanel Control
Creating a Simple ASP.NET Page with Multiple UpdatePanel Controls
Using the UpdatePanel Control with Data-Bound Controls
Using the UpdatePanel Control with Master Pages
Using the UpdatePanel Control with User Controls
Using the UpdatePanel Control with a Web Service
Customizing Error Handling for UpdatePanel Controls
Animating UpdatePanel Controls
Canceling an Asynchronous Postback
Giving Precedence to a Specific Asynchronous Postback
Working with PageRequestManager Events
The UpdateProgress Control
Introduction to the UpdateProgress Control
Programming UpdateProgress Controls in Client Script
The Timer Control
Introduction to the Timer Control
Using the Timer Control with Multiple UpdatePanel Controls
ASP.NET Application Services
Using Forms Authentication
Using Profile Information
Web Services
Exposing Web Services to Client Script
Calling Web Services from Client Script
ASP.NET AJAX Extensibility
Creating Custom ASP.NET AJAX Non-Visual Client Components
Creating Custom ASP.NET AJAX Client Controls
Creating an Extender Control
Adding Client Capabilities to a Web Server Control
Creating a Client Component Class Using the Prototype Model
Defining Custom Component Properties and Raising PropertyChanged Events
Releasing Component Resources

Programming UpdateProgress Controls in Client Script

Introduction

In this tutorial you will extend the UpdateProgress control with client behavior by writing ECMAScript (JavaScript) code. Your code will use the PageRequestManager class that is part of the Microsoft AJAX Library. In the UpdateProgress control, you will add a button that enables users to cancel an asynchronous postback. As part of this task, you will show or hide the progress message using client script.

This topic assumes that you are familiar with the UpdateProgress control. If not, review the topic Introduction to the UpdateProgress Control.

You can see the code in action in this tutorial by clicking the Run It buttons. To implement the procedures in your own development environment you need:

  • Microsoft Visual Studio 2005 or Visual Web Developer Express Edition.

  • The latest release of Microsoft ASP.NET AJAX installed and configured. For more information, see Installing ASP.NET AJAX.

  • An ASP.NET AJAX Web site.

To cancel an asynchronous postback in client script

  1. Create a new ASP.NET Web page and switch to Design view.

  2. In the AJAX Extensions tab of the toolbox, double-click the ScriptManager control, the UpdatePanel control, and the UpdateProgress controls to add one instance of each of them to the page.

    UpdateProgress Tutorial
  3. From the Standard tab of the toolbox, add a Label control to the UpdatePanel control, and set the label's Text property to Panel Rendered.

  4. Add a Button control to the UpdatePanel control and set its Text property to Refresh.

  5. In the UpdateProgress control, add the text Processing….

  6. From the HTML tab of the toolbox, add an HtmlButton control to the UpdateProgress control and set its Value attribute to Cancel.

    UpdateProgress Tutorial
  7. Double-click the Refresh button to add an event handler for its Click event.

  8. Add the following code to the Click handler, which artificially creates a three-second delay and then sets the label to the current server time.

    CS

    protected void Button1_Click(object sender, EventArgs e)
    {
        System.Threading.Thread.Sleep(3000);
        Label1.Text = DateTime.Now.ToString();
    }
    
    

    VB

    Protected Sub Button1_Click(ByVal sender As Object, ByVal e As System.EventArgs)
        System.Threading.Thread.Sleep(3000)
        Label1.Text = DateTime.Now.ToString()
    End Sub
    
    
    note

    The handler for the Click event intentionally introduces a delay for this tutorial. In practice, you would not introduce a delay. Instead, the delay would be the result of server traffic or of server code that takes a long time to process, such as a long-running database query.

  9. Underneath the <asp:ScriptManager> element, add the following script:

    CS

    <script language="javascript" type="text/javascript">
    <!-- 
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    function CancelAsyncPostBack() {
        if (prm.get_isInAsyncPostBack()) {
          prm.abortPostBack();
        }
    }
    // -->
    </script>
    
    

    VB

    <script language="javascript" type="text/javascript">
    <!-- 
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    function CancelAsyncPostBack() {
        if (prm.get_isInAsyncPostBack()) {
          prm.abortPostBack();
        }
    }
    // -->
    </script>
    
    

    The script gets the current instance of the PageRequestManager class. It then creates a function that calls the abortPostBack method to stop an asynchronous postback.

  10. Set the onclick attribute of the HtmlButton control to CancelAsyncPostBack, the name of the handler that you created in the previous step.

    CS

    <input id="Button2" 
           type="button" 
           value="cancel" 
           onclick="CancelAsyncPostBack()" />
    
    

    VB

    <input id="Button2" 
           type="button" 
           value="cancel" 
           onclick="CancelAsyncPostBack()" />
    
    
  11. Add the following style block to the <head> element:

    CS

    <style type="text/css">
    #UpdatePanel1 {
      width:200px; height:100px;
      border: 1px solid gray;
    }
    #UpdateProgress1 {
      width:200px; background-color: #FFC080;
      bottom: 0%; left: 0px; position: absolute;
    }
    </style>
    
    

    VB

    <style type="text/css">    
    #UpdatePanel1 {
      width:200px; height:100px;
      border: 1px solid gray;
    }
    #UpdateProgress1 {
      width:200px; background-color: #FFC080;
      bottom: 0%; left: 0px; position: absolute;
    }
    </style>
    
    

    The style settings configure the UpdateProgress control to be displayed at the bottom-left corner of the browser window.

  12. Save your changes, and then press CTRL+F5 view the page in a browser.

  13. Click Refresh.

    The progress message appears after a short delay. Allow the partial-page update to finish so that the message in the UpdatePanel control is changed to display the time.

    note

    You can configure the time for the delay by setting the DisplayAfter property. The default value is 500 milliseconds.

  14. Click Refresh again and then immediately click Cancel to stop the partial-page update.

    Notice that the time in the UpdatePanel is not refreshed.

    To see the full example in action, click the Run It button.

Displaying Update Progress Using Client Script

In the following scenarios, the UpdateProgress control will not display automatically:

  • The UpdateProgress control is associated with a specific update panel, but the asynchronous postback results from a control that is not inside that update panel.

  • The UpdateProgress control is not associated with any UpdatePanel control, and the asynchronous postback does not result from a control that is not inside an UpdatePanel and is not a trigger. For example, the update is performed in code.

The following procedure shows how to display an UpdateProgress control when the asynchronous postback does not originate inside the associated UpdatePanel control. This procedure assumes that you have completed the first part of this tutorial.

To display an UpdateProgress control programmatically

  1. In the page you created earlier, switch to Design view.

  2. Select the UpdateProgress control, and in the Properties window, set the AssociatedUpdatePanelID property to UpdatePanel1.

    UpdateProgress Tutorial
  3. Add a Button control anywhere outside the UpdatePanel and UpdateProgress controls.

  4. Set the button's Text property to Trigger and its ID to Panel1Trigger.

    UpdateProgress Tutorial
  5. Select the UpdatePanel control, and in the Properties window, click the ellipsis (…) in the box for the Triggers property.

    The UpdatePanelTrigger Collection Editor dialog box is displayed.

  6. Create an AsyncPostBackTrigger object and set its ControlID property to Panel1Trigger.

    UpdateProgress Tutorial
  7. Click OK to close the collection editor.

  8. Double click the Trigger button to add an event handler for its Click event.

  9. Add the following code to the Click handler, which artificially creates a three-second delay. It then displays the server time and a message that states that the postback was caused by a trigger.

    CS

    protected void Panel1Trigger_Click(object sender, EventArgs e)
    {
        System.Threading.Thread.Sleep(3000);
        Label1.Text = DateTime.Now.ToString() + " - trigger";
    }
    
    

    VB

    Protected Sub Panel1Trigger_Click(ByVal sender As Object, ByVal e As System.EventArgs)
        System.Threading.Thread.Sleep(3000)
        Label1.Text = DateTime.Now.ToString() & " - trigger"
    End Sub
    
    
  10. In Source view, add the following client script underneath the <script> block already in the page.

    CS

    prm.add_initializeRequest(InitializeRequest);
    prm.add_endRequest(EndRequest);
    var postBackElement;
    function InitializeRequest(sender, args) {
        if (prm.get_isInAsyncPostBack()) {
            args.set_cancel(true);
        }
        postBackElement = args.get_postBackElement();
        if (postBackElement.id == 'Panel1Trigger') {
            $get('UpdateProgress1').style.display = 'block';                
        }
    }
    function EndRequest(sender, args) {
        if (postBackElement.id == 'Panel1Trigger') {
            $get('UpdateProgress1').style.display = 'none';
        }
    }
    
    

    VB

    prm.add_initializeRequest(InitializeRequest);
    prm.add_endRequest(EndRequest);
    var postBackElement;
    function InitializeRequest(sender, args) {
        if (prm.get_isInAsyncPostBack()) {
            args.set_cancel(true);
        }
        postBackElement = args.get_postBackElement();
        if (postBackElement.id == 'Panel1Trigger') {
            $get('UpdateProgress1').style.display = 'block';                
        }
    }
    function EndRequest(sender, args) {
        if (postBackElement.id == 'Panel1Trigger') {
            $get('UpdateProgress1').style.display = 'none';
        }
    }
    
    

    The script does the following:

    • It defines a handler for the initializeRequest event of the PageRequestManager class. The handler code cancels any asynchronous postbacks that are already in progress. Otherwise, if the postback originates in the Panel1Trigger<div> element, the code displays the UpdateProgress template.

    • It defines a handler for the endRequest event of the PageRequestManager class. If the postback originates in the Panel1Trigger<div> element, the handler code hides the progress control.

    The following example shows the complete script block.

    CS

    <script language="javascript" type="text/javascript">
    <!-- 
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    function CancelAsyncPostBack() {
        if (prm.get_isInAsyncPostBack()) {
          prm.abortPostBack();
        }
    }
    prm.add_initializeRequest(InitializeRequest);
    prm.add_endRequest(EndRequest);
    var postBackElement;
    function InitializeRequest(sender, args) {
        if (prm.get_isInAsyncPostBack()) {
            args.set_cancel(true);
        }
        postBackElement = args.get_postBackElement();
        if (postBackElement.id == 'Panel1Trigger') {
            $get('UpdateProgress1').style.display = 'block';                
        }
    }
    function EndRequest(sender, args) {
        if (postBackElement.id == 'Panel1Trigger') {
            $get('UpdateProgress1').style.display = 'none';
        }
    }
    // -->
    </script>
    
    

    VB

    <script language="javascript" type="text/javascript">
    <!-- 
    var prm = Sys.WebForms.PageRequestManager.getInstance();
    function CancelAsyncPostBack() {
        if (prm.get_isInAsyncPostBack()) {
          prm.abortPostBack();
        }
    }
    prm.add_initializeRequest(InitializeRequest);
    prm.add_endRequest(EndRequest);
    var postBackElement;
    function InitializeRequest(sender, args) {
        if (prm.get_isInAsyncPostBack()) {
            args.set_cancel(true);
        }
        postBackElement = args.get_postBackElement();
        if (postBackElement.id == 'Panel1Trigger') {
            $get('UpdateProgress1').style.display = 'block';                
        }
    }
    function EndRequest(sender, args) {
        if (postBackElement.id == 'Panel1Trigger') {
            $get('UpdateProgress1').style.display = 'none';
        }
    }
    // -->
    </script>
    
    
  11. Save your changes, and then press CTRL+F5 to view the page in a browser.

  12. Click the Refresh button.

    The progress message appears after a short delay. Allow the partial-page update to finish so that the message in the UpdatePanel control displays the time.

  13. Click the Trigger button.

    Notice that the progress message is displayed.

    To see the full example in action, click the Run It button.

Review

This tutorial showed ways you can extend the behavior of the UpdateProgress control by writing JavaScript code. You can use events and methods of the PageRequestManager class to cancel an asynchronous postback and to show and hide an UpdateProgress control programmatically.