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.

 

 

 

 

 

 

 

UpdatePanel Control Overview

Introduction

ASP.NET UpdatePanel controls enable you to build rich, client-centric Web applications. By using UpdatePanel controls, you can refresh selected parts of the page instead of refreshing the whole page with a postback. This is referred to as performing a partial-page update. A Web page that contains a ScriptManager control and one or more UpdatePanel controls can automatically participate in partial-page updates, without custom client script.

This topic contains information about the following:

Scenarios

The UpdatePanel control is a server control that helps you develop Web pages with complex client behavior that makes a Web page appear more interactive to the end user. Coordinating between server and client to update only specified parts of a Web page usually requires in-depth knowledge of ECMAScript (JavaScript). However, by using the UpdatePanel control, you can enable a Web page to participate in partial-page updates without writing any client script. If you want, you can add custom client script to enhance the client user experience. When you use an UpdatePanel control, the page behavior is browser independent and can potentially reduce the amount of data that is transferred between client and server.

Background

UpdatePanel controls work by specifying regions of a page that can be updated without refreshing the whole page. This process is coordinated by the ScriptManager server control and the client PageRequestManager class. When partial-page updates are enabled, controls can asynchronously post to the server. An asynchronous postback behaves like a regular postback in that the resulting server page executes the complete page and control life cycle. However, with an asynchronous postback, page updates are limited to regions of the page that are enclosed in UpdatePanel controls and that are marked to be updated. The server sends HTML markup for only the affected elements to the browser. In the browser, the client PageRequestManager class performs Document Object Model (DOM) manipulation to replace existing HTML with updated markup. The following illustration shows a page that is loaded for the first time, and a subsequent asynchronous postback that refreshes the content of an UpdatePanel control.

Partial-Page Rendering Overview
Partial-page rendering overview

Enabling Partial-Page Updates

The UpdatePanel control requires a ScriptManager control in the Web page. By default, partial-page updates are enabled because the default value of the EnablePartialRendering property of the ScriptManager control is true.

The following example shows markup that defines a ScriptManager control and an UpdatePanel control on a page. The UpdatePanel control contains a Button control that refreshes the content inside the panel when you click it. By default, the ChildrenAsTriggers property is true. Therefore, the Button control acts as an asynchronous postback control.

Specifying UpdatePanel Control Content

You add content to an UpdatePanel control declaratively or in the designer by using the ContentTemplate property. In markup, this property is exposed as a <ContentTemplate> element. To add content programmatically, you use the ContentTemplateContainer property.

When a page that contains one or more UpdatePanel controls is first rendered, all the contents of the UpdatePanel controls are rendered and sent to the browser. On subsequent asynchronous postbacks, the content of individual UpdatePanel controls might be updated. Updates depend on the panel settings, on what element caused the postback, and on code that is specific to each panel.

Specifying UpdatePanel Triggers

By default, any postback control inside an UpdatePanel control causes an asynchronous postback and refreshes the panel's content. However, you can also configure other controls on the page to refresh an UpdatePanel control. You do this by defining a trigger for the UpdatePanel control. A trigger is a binding that specifies which postback control and event cause a panel to update. When the specified event of the trigger control is raised (for example, a button's Click event), the update panel is refreshed.

The following example shows how to specify a trigger for an UpdatePanel control.

The trigger is defined by using the <asp:AsyncPostBackTrigger> element inside the <Triggers> element of the UpdatePanel control. (If you are editing the page in Visual Studio, you can create triggers by using the UpdatePanelTrigger Collection Editor dialog box.)

A trigger's control event is optional. If you do not specify an event, the trigger event is the default event of the control. For example, for the Button control, the default event is the Click event.

How UpdatePanel Controls Are Refreshed

The following list describes the property settings of the UpdatePanel control that determine when a panel's content is updated during partial-page rendering.

  • If the UpdateMode property is set to Always, the UpdatePanel control’s content is updated on every postback that originates from anywhere on the page. This includes asynchronous postbacks from controls that are inside other UpdatePanel controls, and postbacks from controls that are not inside UpdatePanel controls.

  • If the UpdateMode property is set to Conditional, the UpdatePanel control’s content is updated when one of the following is true:

    • When the postback is caused by a trigger for that UpdatePanel control.

    • When you explicitly call the UpdatePanel control's Update() method.

    • When the UpdatePanel control is nested inside another UpdatePanel control and the parent panel is updated.

    • When the ChildrenAsTriggers property is set to true and any child control of the UpdatePanel control causes a postback. Child controls of nested UpdatePanel controls do not cause an update to the outer UpdatePanel control unless they are explicitly defined as triggers for the parent panel.

If the ChildrenAsTriggers property is set to false and the UpdateMode property is set to Always, an exception is thrown. The ChildrenAsTriggers property is intended to be used only when the UpdateMode property is set to Conditional.

Using UpdatePanel Controls in Master Pages

To use an UpdatePanel control in a master page, you must decide how to include the ScriptManager control. If you include the ScriptManager control on the master page, it can act as the ScriptManager control for all content pages. (If you want to register scripts or services declaratively in a content page, you can add a ScriptManagerProxy control to that content page.)

If the master page does not contain the ScriptManager control, you can put the ScriptManager control individually on each content page that contains an UpdatePanel control. The design choice depends on how you intend to manage client script in your application. For more information about how to manage client script, see ScriptManager Control Overview. For more information about master pages, see ASP.NET Master Pages Overview.

If the ScriptManager control is on the master page and you do not need partial-page rendering capabilities for a content page, you must programmatically set the EnablePartialRendering property of the ScriptManager control to false for that content page.

The following example shows markup for a ScriptManager control on the master page and an UpdatePanel control on a content page. In this example, a property named LastUpdate is defined on the master page and is referenced from inside the UpdatePanel control.

Using Nested UpdatePanel Controls

UpdatePanel controls can be nested. If the parent panel is refreshed, all nested panels are refreshed also.

The following example shows markup that defines an UpdatePanel control inside another UpdatePanel control. A button in the parent panel triggers an update of the content in both the parent and the child panel. The button in the child panel triggers an update of only the child panel.

The following example shows a nested UpdatePanel control with a GridView control. The GridView control is inside an UpdatePanel control, and each GridView row contains a nested GridView control inside another UpdatePanel control.

When an inner GridView control displays a new page of records, 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 outer panel and the nested panels are all refreshed.

Refreshing an UpdatePanel Programmatically

The following example shows how to refresh an UpdatePanel control programmatically. In this example, a page registers a control as a trigger by calling the RegisterAsyncPostBackControl(Control) method. The code refreshes the UpdatePanel control programmatically by calling the Update() method.

Creating UpdatePanel Controls Programmatically

To add an UpdatePanel control to a page programmatically, you create a new instance of the UpdatePanel control. You then add controls to it by using the ContentTemplateContainer property and the Add(Control) method. Do not add controls directly to the ContentTemplate property.

When an UpdatePanel control is added programmatically, only postbacks from controls in the same naming container as the UpdatePanel control can be used as triggers for the panel.

The following example shows how to programmatically add an UpdatePanel control to a page. The example adds a Label and a Button control to the update panel by using the ContentTemplateContainer property. Because the ChildrenAsTriggers property is true by default, the Button control acts as a trigger for the panel.

Controls that Are Not Compatible with UpdatePanel Controls

The following ASP.NET controls are not compatible with partial-page updates, and are therefore not supported inside an UpdatePanel control:

Controls that are incompatible with partial-page rendering can still be used on a page outside UpdatePanel controls. Additionally, in some cases you can use the controls in a specific way to make them compatible with partial-page updates. For example, you can use the Login, ChangePassword, or PasswordRecovery controls inside an UpdatePanel control if you can convert their contents to templates. (If you are using Visual Studio, in Design view you can convert the controls by using smart-tag menu commands such as Convert to Template or Customize Create User Step.) When you convert these controls into editable templates, the validation controls that are used in the control are defined declaratively by using markup in the page. To make the validators compatible with an UpdatePanel control, set the EnableClientScript property of the validators to false. This disables the client script that would ordinarily be used to perform validation in the browser. As a result, during an asynchronous postback, the validators perform validation on the server. However, because only the content of the UpdatePanel is refreshed, the validators can provide the kind of immediate feedback that is ordinarily provided by client script.

To use a FileUpload control inside an UpdatePanel control, set the postback control that submits the file to be a PostBackTrigger control for the panel.

All other controls work inside UpdatePanel controls. However, in some circumstances, a control might not work as expected inside an UpdatePanel control. These circumstances include the following:

  • Registering script by calling registration methods of the ClientScriptManager control.

  • Rendering script or markup directly during control rendering, such as by calling the Write(String) method.

If the control calls script registration methods of the ClientScriptManager control, you could use corresponding script registration methods of the ScriptManager control instead. In that case, the control can work inside an UpdatePanel control.

Code Examples

The following sections include examples that show how to create and use UpdatePanel controls.

How-to and Walkthrough Topics

Class Reference

The key server classes for UpdatePanel controls are shown in the following table.

Class

Description

UpdatePanel

A server control that specifies the parts of a Web page that can participate in partial-page updates.

ScriptManager

A server control that manages partial-page rendering. The ScriptManager control registers script components to send to the browser. It also overrides page rendering so that only specified regions of the page are rendered.

ScriptManagerProxy

A server control that enables nested components (such as content pages or user controls) to add script and Web-service references. This control is useful if the parent element already contains a ScriptManager control.

PageRequestManager

A class in the Microsoft AJAX Library that coordinates partial-page rendering in the browser. The PageRequestManager class asynchronously exchanges information with the server, and exposes events and methods for custom client script development.

Additional Topics

ASP.NET Page Life Cycle Overview