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

Using the ASP.NET UpdatePanel Control with Data-Bound Controls

Introduction

You can create a richer user experience in your Microsoft ASP.NET AJAX applications by using partial-page rendering. Partial-page rendering removes the need for the whole page to refresh as the result of a postback. Instead, you can specify only the region of the page to be refreshed. As a result, users no longer see the whole page reload with every postback.

This topic assumes that you are familiar with the UpdatePanel control. If not, review the following topics:

You can enable partial-page rendering by using the UpdatePanel and ScriptManager Web server controls. The UpdatePanel control identifies a region of a page that can be updated. The ScriptManager control keeps track of the UpdatePanel controls that are on a page and the controls that trigger the UpdatePanel controls to refresh. Controls inside an UpdatePanel control that cause a postback are automatically identified as triggers for the update panel. You can also specify controls that are external to an UpdatePanel control as triggers that cause the UpdatePanel control to refresh. External triggers can be child controls of another UpdatePanel control. For more information, see Partial-Page Rendering Overview and UpdatePanel Control Overview.

This topic contains the following:

Using Multiple UpdatePanel Controls on a Page

There is no limit to the number of UpdatePanel controls that you can put on a page. As a result, you can specify regions of a page that are refreshed independently of the whole page and independently of each other.

By default, the UpdateMode property of an UpdatePanel control is set to Always. This means that whenever a partial-page refresh is triggered, the UpdatePanel control will refresh the page region regardless of whether it was the UpdatePanel control that was triggered. To make sure that the UpdatePanel control will refresh only when it has been triggered, you can set the UpdateMode property of the UpdatePanel control to Conditional.

The following example includes two UpdatePanel controls: one control includes controls to accept user input, and the other control displays a summary of the input. Each UpdatePanel control has its UpdateMode property set to Conditional. As a result, if a user clicks the Cancel button to clear the fields of the input form, only the input form of the UpdatePanel control is refreshed. If a user clicks the Insert button to submit the form, both of the UpdatePanel controls are refreshed.

You can also nest an UpdatePanel control in the ContentTemplate template of another UpdatePanel control. If you set the UpdateMode property of both the outer and nested controls to Conditional, the outer panel will not refresh its page region if only the inner panel has been triggered. However, if a refresh of the outer panel is triggered, both the outer and inner panels will refresh their page regions.

The following example includes a GridView control inside an UpdatePanel control. For each row of the GridView control, there is a nested GridView control that is inside a child UpdatePanel control. When a new page of records is requested from an inner GridView, the page regions of the outer panel and the panels in the other rows of the outer GridView control are not refreshed. When the outer GridView control displays a new page of records, the page regions of the outer panel and the nested panels are all refreshed.

Disabling Automatic Triggers

Controls in the content template for an UpdatePanel control that cause a postback are automatically configured as triggers for that UpdatePanel control. However, you might want to disable the automatic triggers and trigger a refresh of the UpdatePanel control from an external control only. To do this, set the ChildrenAsTriggers property of the UpdatePanel control to false. Then set the UpdateMode property of the UpdatePanel control to Conditional. These property settings will cause a refresh of the panel only if triggered an external control or by a call to the Update() method.

The following example displays the categories, subcategories, and names of products from the AdventureWorks sample database. The category list rarely changes and there is no need to refresh the list of categories every time that a list of subcategories or products is displayed. Therefore, in the UpdatePanel control that contains the category list, you can set the ChildrenAsTriggers property to false and the UpdateMode property to Conditional. This makes sure that the UpdatePanel control refreshes only when explicitly requested.

Managing Triggers and Refreshing an UpdatePanel Programmatically

Controls that trigger an UpdatePanel control to refresh are registered with the ScriptManager control on the page. This occurs automatically for the child controls in an UpdatePanel control's ContentTemplate. You can specify triggers declaratively using the Triggers collection of an UpdatePanel control. Additionally, you can programmatically identify triggers and cause an UpdatePanel control to refresh in the server code of your page.

In cases where a trigger control is not available at design time, you can register the control as a trigger by using the RegisterAsyncPostBackControl(Control) method of the ScriptManager control. Controls that are programmatically identified as triggers must be registered whenever a postback occurs. We recommend that you put calls to the RegisterAsyncPostBackControl(Control) method in the Page_Load event for your page, as shown in the following example.

CS

protected void Page_Load()
{
    ScriptManager1.RegisterAsyncPostBackControl(SurveyDataList);
}

vb

Protected Sub Page_Load()
    ScriptManager1.RegisterAsyncPostBackControl(SurveyDataList)
End Sub

To programmatically refresh the UpdatePanel control, you can call the Update() method of an UpdatePanel control. This is useful if you must perform some processing on the server before refreshing the UpdatePanel control. The following example shows how to refresh an UpdatePanel programmatically.

CS

protected void ChoicesRadioButtonList_SelectedIndexChanged(object sender, EventArgs e)
{
    SortedList answers = this.AnsweredQuestions;
    RadioButtonList r = (RadioButtonList)sender;
    answers[r.ToolTip] = r.SelectedValue;
    this.AnsweredQuestions = answers;

    ResultsList.DataSource = this.AnsweredQuestions;
    ResultsList.DataBind();

    if (this.AnsweredQuestions.Count == SurveyDataList.Items.Count)
        SubmitButton.Visible = true;

    UpdatePanel1.Update();
}

vb

Protected Sub ChoicesRadioButtonList_SelectedIndexChanged(sender As Object, e As EventArgs)
    Dim answers As SortedList = Me.AnsweredQuestions
    Dim r As RadioButtonList = CType(sender, RadioButtonList)
    answers(r.ToolTip) = r.SelectedValue
    Me.AnsweredQuestions = answers

    ResultsList.DataSource = Me.AnsweredQuestions
    ResultsList.DataBind()

    If Me.AnsweredQuestions.Count = SurveyDataList.Items.Count Then _
        SubmitButton.Visible = True

    UpdatePanel1.Update()
End Sub

The following example shows a page that registers a control as a trigger by using the RegisterAsyncPostBackControl(Control) method, and programmatically refreshes an UpdatePanel control by using the Update() method.

Enabling Partial-Page Rendering in a Custom Control

You can add an UpdatePanel to a user control or to a custom control. However, the page that contains your control might not include the necessary ScriptManager control with its EnablePartialRendering property set to true. You can add logic to your custom control to determine whether partial-page rendering is enabled by calling the static GetCurrent(Page) method of the ScriptManager control. If there is no ScriptManager control on the page, the GetCurrent(Page) method returns null. Otherwise, you can check the value of the EnablePartialRendering property of the ScriptManager control and include an UpdatePanel control if the EnablePartialRendering property returns true.

The following example shows the CreateChildControls() method of a custom control that inherits the CompositeControl class. If partial-page rendering is enabled for the page, the custom control puts its contents in an UpdatePanel control.

App_Code

protected override void CreateChildControls() {
    base.CreateChildControls();

    Control parent;
    Control container;

    // Get a reference to the ScriptManager object for the page
    // if one exists.
    ScriptManager sm = ScriptManager.GetCurrent(Page);

    if (sm == null || !sm.EnablePartialRendering)
    {
        // If partial rendering is not enabled, set the parent
        // and container as a basic control. 
        container = new Control();
        parent = container;
    }
    else
    {
        // If partial rendering is enabled, set the parent as
        // a new UpdatePanel object and the container to the 
        // content template of the UpdatePanel object.
        UpdatePanel up = new UpdatePanel();
        container = up.ContentTemplateContainer;
        parent = up;
    }

    AddDataboundControls(container);

    Controls.Add(parent);
}

App_Code

Protected Overrides Sub CreateChildControls()
    MyBase.CreateChildControls()

    Dim parent As Control
    Dim container As Control

    ' Get a reference to the ScriptManager object for the page
    ' if one exists.
    Dim sm As ScriptManager = ScriptManager.GetCurrent(Page)

    If sm Is Nothing OrElse Not sm.EnablePartialRendering Then
        ' If partial rendering is not enabled, set the parent
        ' and container as a basic control. 
        container = New Control()
        parent = container
    Else
        ' If partial rendering is enabled, set the parent as
        ' a new UpdatePanel object and the container to the 
        ' content template of the UpdatePanel object.
        Dim up As UpdatePanel = New UpdatePanel()
        container = up.ContentTemplateContainer
        parent = up
    End If

    AddDataboundControls(container)

    Controls.Add(parent)
End Sub

The following example shows a custom control that includes an UpdatePanel control if partial-page rendering is enabled.