The first step in adding Ajax functionality to a Web site is to add a ScriptManager control to your Web
pages. Next, you add server controls such as Updatepanel controls to enable partial-page rendering and dynamic controls such as those supplied in the AJAXControl Toolkit to add usability and glitz to your application. You may also add client-side code, and you can use the AJAXLibrary for further assistance in customizing and enhancing the functionality of your application.
In this section, you learn about the functionality you can add using server controls. Later in the chapter you look at client-side techniques.
The ScrlptManager Control
As mentioned earlier in the chapter, the ScriptManager control must be included on all pages that use
partial-page postbacks and several other aspects of ASP.NETAJAXfunctionality.
A great way to ensure tha: all the pages in your Web application contain the ScriptManager control is to add this control to the master page (or master pages) tha! your application uses .
As well as enabling ASP.NETAJAXfunctionality, you can also use properties to configure this control. The simplest of these properties is EnablePartialRendering, which is true by default. If you set this property to false, you will disable all asynchronous postback processing, such as that provided by
update panel controls. This can be useful, for example, if you want to compare your AJAX-enabled Web site with a traditional Website, perhaps if you are giving a demonstration to a manager.
You can use the ScriptManager control for several reasons, such as in the following common situations:
¤ To determine whether server-side code is being called as a result of a partial-page postback
¤ To reference Web services
¤ To return error messages to the client
These configuration options are covered in the following sections
Detect Partial-Page Postbacks
The ScriptManager control includes a Boolean property called IsInAsyncpostBack. You can use this property in server-side code to detect whether cartel-page postback is in progress. Note that the ScriptManager for a page may actually be on master page. Rather than accessing this control through the master page, y.oucan obtain a reference to the current ScriptManager instance by using the static.
GetCurrent () method, for example:
You must pass a reference to a Page control to the GetCurrent () method. For example, if you use this method in a Page_Load () event handler for an ASP.NETWeb page, you can use this as your Page reference. Also, remember to check for a null reference to avoid exceptions.
CIIent-5lde JavaScrlpt References
Rather than adding code to the HTML page header, or in <script> elements on the page, you can use the Scripts property of the ScriptManager class. This centralizes your script references and makes it easier to maintain them. You can do this declaratively by adding a child <Scripts> element to the <UpdatePanel> control element, and then adding <asp: ScriptReference> child control elements to <Scripts>. You use the Path property of a ScriptReference control to reference a custom script.
The following sample shows how to add references to a custom script file called MyScript . j s in the
root folder of the Web application:
Web Service References
The ServiceReference class also has a property called InlineScript, which defaults to false. When this property is false, client-side code obtains a proxy class to call the Web service by requesting it from the server. To.enhance performance (particularly if you use a lot of Web services on a page), you can set InlineScript to true. This causes the proxy class to be defined in the client-script for the page.
ASP.NETWeb services use a file extension of . asDIX.Without wanting to get into too much detail, to add a reference to a Web service called MyService. asDIXin the root folder of a Web application, you would use code as follows,
You can only add references to local Web services (that is, Webservices if(the same Web application as the calling code) in this way.You can call remote Web services indirectly via local Web methods.
code that uses proxy classes generated in this way.
Client-Side Error Messages
If you want to override the default behavior and display a message in a different way, you must handle
Using UpdatePanel Controls
The UpdatePanel control is perhaps the control that you will use most often when you write ASP.NET
AJAX-enabled Web applications. This control, as you have seen in the simple example earlier in the chapter, enables you to wrap a portion of a Web page so that it is capable of participating in a partiall”‘
poostback operation. To do this, you add an UpdatePanel control to the page and fill its child <ContentTemplate> element with the controls that you want it to contain.
The contents of the <ContentTemplate> template are rendered in either a <di v» or <span> element according to the value of the RenderMode property of the UpdatePanel. The default value of this property is Bleck, which will result in a <d iv> element. To use a <span> element, set RenderMode to Inline.
Multiple UpdatePanel Controls on a Single Web Page
You can include any number of UpdatePanel controls on a page. If a postback is caused by a control that is contained in the <ContentTemplate> of any ‘updatePanel on the page, a partial-page postback will occur instead of a full-page postback. This will cause all the UpdatePanel controls to update according to the value of their UpdateMode property. The default value of this property is Always, which means that the UpdatePanel will update for a partial-page postback operation on the page, even if this operation occurs in a different UpdatePanel control. If you set this property to Condi tional, the updatepal1el updates only when a control that it contains causes a partial-page postback or when a trigger that you have defined occurs. Triggers are covered shortly.
If you have set UpdateMode to Conditional, you can also set the ChildrenASTriggers property to false to prevent controls that are contained by the UpdatePanel from triggering an update of the panel. Note, though, that in this ease these controls still trigger a partial-page update, which may result in other Upda t.e Parie L controls on the page being updated. For example, this will update controls that have an UpdateMode property value of Always. This is illustrated in the following code:
In this code, the updatepane12 control has an UpdateMode property of Always; the default value. When the button is clicked, it will cause a partial-page postback, but only Updatepanel2 will be updated. Visually, you will notice that only the “Panel 2 render time” label is updated .
Server-Slde Update Panel Updates
Sometimes when you have multiple updatePanel controls on a.page, you might decide not to update one of them unless certain conditions are met. In this case, you would configure ‘the UpdateMode property of the panel to Condi tional as shown in the previous section and possibly also set the ChildrenASTriggers property to false. Then, in .your server-side event-handler code for one of the controls on the page thatcauses a partial-page update, you would (conditionally) call the Update () method of the HB gate panel. For example:
You can cause an UpdatePanel control to be updated by a control elsewhere on the Web page by adding triggers to the Triggers property of the control. A trigger is an association between an event of a control elsewhere on the page and the UpdatePanel control. All controls have default events (for example; the default event of a Button control is Click), so specifying the name of an event is optional. There are two types of triggers that you can add, represented by the following two classes:
- AsyncPostBackTrigger – This class causes the UpdatePanel to update when the specified event of the specified control is triggered.
- PostBackTrigger – This class causes a full-page update to be triggered when the specified event of the specified control is triggered.
You will mostly us AsyncPostBackTrigger, but PostBackTrigger can be useful if you want a control inside an UpdatePanel to trigger a full-page postback.
Both of these trigger classes have two properties: ControlID, which specifies the control that causes the trigger by its identifier, and EventNarne, which specifies the name of the event for the control that is linked to the trigger.
To extend an earlier example, consider the following code:
The new Button control, Button2, is specified as a trigger in the Updatei’anell. When this button is clicked, both UpdatePanell and UpdatePane12 will be updated: UpdatePanell because of the trigger, and UpdatePane12 because it uses the default UpdateMode value of Always.
The UpdateProgress control, as you saw in the earlier example, enables you to display a progress message to the user while a partial-page postback is in operation. You use the ProgressTemplate property to supply an ITemplate for the progress display. You will typically use the
<ProgressTemplate> child element of the control to do this.
You can place multiple UpdateProgress controls on a page by using the AssociatedUpdatePanelID property to associate the control with a specific UpdatePanel. If this is not set (the default), the UpdateProgress template will be displayed for any partial-page postback, regardless of which UpdatePanel causes it.
When a partial-page postback occurs, there is a delay before the UpdateProgress template is displayed. This delay is configurable through the DisplayAfter property, which is an int property that specifies the delay in milliseconds. The default is 500 milliseconds. Finally, you can use the Boolean nynamicLayout property to specify whether space is allocated for the template before it is displayed. For the default value of true for this property, space on the page is dynamically allocated, which may result in other controls being moved out of the way for an inline progress template display. If you set this property to false, space will be allocated for the template before it is displayed, so the layout of other controls on the page will not change. You will set this property according to the effect you want to achieve when displaying progress. For a progress template that is positioned by using absolute coordinates, as in the earlier’ example, you should leave this property set to the default value.
Using Extender Controls
The co1’f ASP.NET AJAX download includes a class called ExtenderControl. The purpose of this control-is to enable you to extend (that is, add functionality to) other ASP.NET server controls. This is
used extensively in the AJAX Control Toolkit to great effect, and you can use the ASP.NET AJAX Server Control Extender project template to create your own extended controls. ExtenderControl controls all work in a similar way – you place them on a page, associate them with target controls, and add further configuration. The extender then emits client-side code to add functionality.
To see.this in action in a simple example, create a new Web site called PCSExtenderDemo in the C: \ ProCSharp\Chapter39 directory, add the AJAX Control Toolkit assembly to the bin directory of the Web Site, and then add the following code to Defaul t. aspx:
You also need to add the following event handler to the code-behind this file:
protected void OnSelect(object sender. EventArgs e)
favoriteColorLabel.Text = «LinkButton)sender) .Text;
favoriteColorLabel.Style[‘color’] = ((LinkButton)sender) .Style[*color*];
In the browser. n0ltvery much is visible at first. and the extender seems to have no effect. This is shown in Figure 39-5.
However, when you hover over the text that reads “green,” a drop-down dynamically appears. U you
click this drop-down, a list appears, as shown in Figure 39-6.
When you click one of the links in the drop-down list, the text changes accordingly (after a partial-page
There are two important points to note about this simple example. First, it was extremely easy to associate the extender with target controls. Second, the drop-down list was styled using custom code – meaning that you can place whatever content you like in the list. This simple extender is a great way to add functionality to your Web applications, and it is very simple to use.