JavaScript Editor jscript editor     Web designer 
↑


Main Page

In the default model for ASP.NET Web pages, the user interacts with a page and clicks a button or performs some other action that results in a postback. The page and its controls are re-created, the page code runs on the server, and a new version of the page is rendered to the browser. However, in some situations, it is useful to run server code from the client without performing a postback. If the client script in the page is maintaining some state information (for example, local variable values), posting the page and getting a new copy of it destroys that state. Additionally, page postbacks introduce processing overhead that can decrease performance and force the user to wait for the page to be processed and re-created.

To avoid losing client state and not incur the processing overhead of a server roundtrip, you can code an ASP.NET Web page so that it can perform client callbacks. In a client callback, a client script function sends a request to an ASP.NET Web page. The Web page runs a modified version of its normal life cycle — the page is initiated and its controls and other members are created, and then a specially marked method is invoked. The method performs the processing that you have coded and then returns a value to the browser that can be read by another client script function. Throughout this process, the page is live in the browser.

Several Web server controls use client callbacks. For example, the TreeView control uses client callbacks to implement its populate on demand functionality. For more information see TreeView Web Server Control Overview.

Components of Client Callbacks

Creating an ASP.NET page that implements client callbacks is similar to creating any ASP.NET page, with a few differences. For instance, the page must do the following:

  • Implement the ICallbackEventHandler interface. You can add this interface declaration to any ASP.NET Web page.

  • Include a method that implements the RaiseCallbackEvent interface. This method will be invoked by the callback, and then it returns a string to the clientCallback function.

In addition, the page must contain three client script functions that perform the following actions:

  • One function calls a helper method that performs the actual request to the server. In this function, you can perform custom logic to prepare the event arguments first, and then you can send a string as a parameter to the server-side callback event handler.

  • Another function receives (is called by) the result from the server code that processed the callback event, accepting a string that represents the results. This is called the clientCallBack function.

  • A third function is the helper function that performs the actual request to the server, which is generated automatically by ASP.NET when you generate a reference to this function using the GetCallbackEventReference method in server code.

Both client callbacks and postbacks are requests for the originating page, thus, client callbacks and postbacks are recorded in Web server logs as a page request.

Implementing the Appropriate Interfaces in Server Code

To successfully run server code from the client without performing a postback, you must also implement the appropriate interfaces in server code.

Declaring the EventHandler Interface

You can declare the ICallbackEventHandler interface as part of the class declaration for the page. If you are creating a code-behind page, you can declare the interface by using syntax such as the following.

Visual BasicВ CopyCode imageCopy Code
Partial Class CallBack_DB_aspx
    Implements System.Web.UI.ICallbackEventHandler
C#В CopyCode imageCopy Code
public partial class CallBack_DB_aspx : 
    System.Web.UI.ICallbackEventHandler

If you are working in a single-file page or user control, you can add the declaration by using an @ Implements directive in the page, as in the following code examples.

Visual BasicВ CopyCode imageCopy Code
<%@ Page Language="VB" %>
<%@ Implements Interface="System.Web.UI.ICallbackEventHandler" %>
C#В CopyCode imageCopy Code
<%@ Page Language="C#" %>
<%@ Implements Interface="System.Web.UI.ICallbackEventHandler" %>
NoteNote

The interface name is case-sensitive.

Creating a Server-Code Callback Method

In server code, you must create a method that implements the RaiseCallbackEvent interface. The method takes a single string argument instead of the usual two arguments that are typically used with event handlers. The method also returns a string. A portion of the method might look like the following code example.

Visual BasicВ CopyCode imageCopy Code
Public Function RaiseCallbackEvent(ByVal eventArgument As String) _
    As String Implements _
        System.Web.UI.ICallbackEventHandler.RaiseCallbackEvent
    Return eventArgument & " new value"
End Function
C#В CopyCode imageCopy Code
public String RaiseCallbackEvent(String eventArgument As String)
{
    return eventArgument + " new value";
}

Creating Client Script Functions

You must add client script functions to the page to perform two functions: send the callback to the server page and receive the results. Both client script functions are written in ECMAScript (JavaScript).

Sending the Callback

The function to send the callback is generated in server code. The actual callback is performed by a library function that is available to any page that implements the ICallbackEventHandler interface. You can get a reference to the library function by calling the page's GetCallbackEventReference method. You then build a client function dynamically that includes a call to the return value from one of the GetCallbackEventReference method. You pass to that method a reference to the page (this in C# or Me in Visual Basic), the name of the argument by which you will pass data, the name of the client script function that will receive the callback data, and an argument that passes any context you want.

When you have built the function, you inject it into the page by calling the RegisterClientScriptBlock method.

The following code example shows how to dynamically create a function named CallServer that, in turn, invokes the callback.

Visual BasicВ CopyCode imageCopy Code
Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
    Dim cbReference As String
    cbReference = Page.GetCallbackEventReference(Me, "arg", _
        "ReceiveServerData", "context")
    Dim callbackScript As String = ""
    callbackScript &= "function CallServer(arg, context)" & _
        "{" & cbReference & "; }"
    Page.ClientScript.RegisterClientScriptBlock(Me.GetType(), _
        "CallServer",  callbackScript, True)
End Sub
C#В CopyCode imageCopy Code
void Page_Load(object sender, EventArgs e)
{
    String cbReference = Page.GetCallbackEventReference(this, "arg", 
        "ReceiveServerData", "context");
    String callbackScript = "function CallServer(arg, context) {" +
        cbReference + "; }";
    Page.ClientScript.RegisterClientScriptBlock(this.GetType(), 
        "CallServer",  callbackScript, true);
}

Note that the names of the arguments that are accepted by the function you are generating match the names of the values that you pass to the GetCallbackEventReference method.

Receiving the Callback

You can write the client function that receives callbacks statically in the page. The function must be named to match the name that you pass in the call to the GetCallbackEventReference method. The receiving function accepts two string values: one for the return value and an optional second value for the context value that is passed back from the server.

The function might look like the following code example.

В CopyCode imageCopy Code
<script type="text/javascript">
function ReceiveServerData(rvalue, context)
{
    span1.innerText = "Return value = " + rvalue;
}
</script>

See Also



JavaScript Editor jscript editor     Web designer 
→