14.3. The UpdatePanel Control

The UpdatePanel control, in conjunction with the ScriptManager, defines areas within the web page to be partially updated without refreshing the entire page. These areas can be updated independently of one another and are usually triggered to update the content contained in them. An UpdatePanel can be added to the page declaratively with tags or programmatically.

14.3.1. Adding the UpdatePanel to the Page

Adding an UpdatePanel is a simple process. The first step is to add a ScriptManager control to the page.

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

The next step is to decide how the UpdatePanel behaves. The UpdatePanel class inherits the System.Web.UI.Control class, so all the attributes exposed by the parent are exposed by the child class. The most important attributes, however, are specific to the UpdatePanel class. They are:

  • ChildrenAsTriggers: A Boolean value that indicates whether or not the UpdatePanel should be updated when immediate child controls cause a postback. A postback is the process of sending and receiving data from the server. The default value for this attribute is true. Note that children of a nested UpdatePanel do not cause an update of the parent UpdatePanel.

  • RenderMode: Indicates how the panel is rendered. If set to "Block" (the default), the ASP.NET engine renders the UpdatePanel as a <div/> element. If "Inline", the panel is rendered as a <span/> element.

  • UpdateMode: Determines how the panel's contents are updated. If set to "Always", the default value, the panel updates with every postback that originates from the page, including asynchronous postbacks (updates from other panels). The second value, "Conditional", updates the panels when the following conditions are met:

    • The Update() method of the UpdatePanel instance is explicitly called.

    • The postback is caused by a control that is defined as a trigger (more on triggers later). The triggering control can be either inside or outside the UpdatePanel control.

    • The ChildrenAsTriggers attribute is set to true, and a child control causes a postback.

Keeping these conditions in mind, an UpdatePanel that continually updates itself is added to the page like this:

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

<asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">

    <%-- More Code Here --%>

</asp:UpdatePanel>

14.3.2. Adding Content to the UpdatePanel

The whole purpose of an UpdatePanel is to update content, and the content of an UpdatePanel control is housed inside a <ContentTemplate/> element. The ContentTemplate is actually a property of the UpdatePanel class, but the element allows you to add content to the panel declaratively.

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

<asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
        <%-- More Code Here --%>
    </ContentTemplate>

    <%-- More Code Here --%>
</asp:UpdatePanel>

The content contained within <ContentTemplate/> can be a mix of HTML and ASP.NET controls. The following code adds a TextBox server control to the <ContentTemplate/>:

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

<asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
        <asp:TextBox ID="TextBox1" Text="0" runat="server" />
    </ContentTemplate>

    <%-- More Code Here --%>
</asp:UpdatePanel>

The TextBox control, like that of the client library, is for text input from the user. This particular code places a normal text box into the page and initializes its text as the number zero (0).

14.3.3. Triggering an Update

The UpdatePanel has been added to the page and has content ready to update. However, there's nothing (yet) to cause the TextBox to be updated with new data. Since the UpdatePanel in this example is set for Conditional UpdateMode, the update must be triggered according to the criteria listed in the previous section.

Probably the most common way to trigger an update is to assign triggers. Triggers are events from other controls that cause an UpdatePanel to refresh, and they can be added declaratively to the UpdatePanel control with the <Triggers/> element.

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

<asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
        <asp:TextBox ID="TextBox1" Text="0" runat="server" />
    </ContentTemplate>
    <Triggers>
        <%-- More Code Here --%>
    </Triggers>
</asp:UpdatePanel>

<asp:Button ID="Button1" Text="Add More" runat="server" />

Triggers are bound to other ASP.NET controls, which can be either inside or outside of the UpdatePanel. This code declares a Button control, which will be bound to a trigger. But first, there are two types of triggers that can be used.

  • The first, PostBackTrigger, causes a normal postback (the whole page is refreshed). This trigger type can be useful when performing functions like uploading a file, because files cannot be uploaded asynchronously. The PostBackTrigger element allows for only one attribute: ControlID, which corresponds to another control's ID property.

  • The second trigger type, AsyncPostBackTrigger, causes an asynchronous postback. The element that declares this trigger has two possible attributes: ControlID and EventName. The ControlID attribute is the same as it is with PostBackTrigger. The new attribute, EventName, is optional, but it can be set to a specific event of the bound control to trigger the update (otherwise, any event will trigger the update). For example, if EventName is set to "Click", the UpdatePanel will be updated only when the trigger control is clicked.

Of these two trigger types, only one fits the goals of this example: the AsyncPostBackTrigger. The following code binds the Button1 control to a trigger:

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

<asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
        <asp:TextBox ID="TextBox1" Text="0" runat="server" />
    </ContentTemplate>
    <Triggers>
        <asp:AsyncPostBackTrigger ControlID="Button1" EventName="Click" />

</Triggers>
</asp:UpdatePanel>

<asp:Button ID="Button1" Text="Add More" runat="server" />

This new code binds the Button control to the trigger, and it triggers an update only when the Button is clicked. In its current state, however, nothing will happen, because the Click event is not handled.

Don't confuse the Click event of a Button control with the click event in the browser's DOM. The former is a server event that executes server-side code, whereas the latter executes code within the browser. They both serve a similar purpose, but one does not call the other.

14.3.4. Finishing Up

The meat of the application is complete; however, nothing happens when the Button control is clicked. The purpose of this application is to take whatever number is in the TextBox control and increment it when the Button is clicked. This is a simple algorithm to code in C#:

protected void Button1_Click(object sender, EventArgs e)
{
    long oldNumber = System.Convert.ToInt64(TextBox1.Text);
    long newNumber = ++oldNumber;
    TextBox1.Text = newNumber.ToString();
}

protected void ScriptManager1_AsyncPostBackError(object sender,
                                                AsyncPostBackErrorEventArgs e)
{
    ScriptManager1.AsyncPostBackErrorMessage = e.Exception.Message;
}

The first function handles the Button's Click event. When executed, this method retrieves the string value from the TextBox control and converts it to a long integer. The next line increments the value contained in oldNumber and assigns it to the newNumber variable. The final line converts the number to a string and sets the TextBox so that it contains that new value.

If a non-number is entered into the TextBox, the application throws a FormatException error. When this happens, the ScriptManager's AsyncPostBackError event fires. The second function in this code handles this event, and it sets the ScriptManager object's AsyncPostBackErrorMessage property to the exception's message. This information is then sent back to the client, which displays the message in an alert box. Figure 14-3 shows what happens when Ajax is typed into the text box instead of a numeric value.

Figure 14.3. Figure 14-3

The last step in this process is to assign the function to handle the two events:

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

<asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional" runat="server">
    <ContentTemplate>
        <asp:TextBox ID="TextBox1" Text="0" runat="server" />
    </ContentTemplate>
    <Triggers>
        <asp:AsyncPostBackTrigger ControlID="Button1" EventName="Click" />
    </Triggers>
</asp:UpdatePanel>

<asp:Button ID="Button1" Text="Add More" OnClick="Button1_Click" runat="server" />

This new code adds the OnClick event handler to the Button control declaration. Now when the user clicks the button, it will trigger the UpdatePanel to asynchronously update itself. To prove it works, add a JavaScript onload event handler to alert you when the page refreshes.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset