Click here to Skip to main content
13,895,744 members
Click here to Skip to main content
Add your own
alternative version


252 bookmarked
Posted 15 Sep 2005
Licenced MIT

Magic AJAX: Applying AJAX to your existing Web Pages

, 28 May 2007
Rate this:
Please Sign up or sign in to vote.
How to apply AJAX technologies to your web pages without replacing ASP.NET controls and/or writing JavaScript code.


After all the fuss and the hype about AJAX technologies, now there are plenty of solutions for AJAX that developers can choose from. The drawback is that you have to replace the standard ASP.NET controls that your web pages contain with custom AJAX-enabled controls, and/or write JavaScript code for the client to process the data returned by the server.

What if there was a "magical" panel control that, when you drag-n-drop ordinary, old-fashioned, ASP.NET controls, "magically" transforms them to AJAX-enabled controls? Impossible! Well, this article claims that such a panel can exist (AjaxPanel) and sadly, there's no magic about it; it's all plain C# code.

Update - 12 Nov 2005: The MagicAjax framework is now hosted on SourceForge. Many improvements and features have been added since the initial release, including support for ASP.NET 2.0.


This article assumes that you know what AJAX is. If that's not the case, there are plenty of good articles in CodeProject to get you started. The code behind this article is based on the excellent series AJAX WAS Here by Bill Pierce. Understanding the client JavaScript framework and how it invokes server methods is not required to use the classes in this article, but if you want to see what happens "under the hood", I strongly recommend reading Bill Pierce's articles.

Using the code

I have included a demo project to show you how to convert the existing plain postback controls to AJAX-like ones.


This page tries to be a chat application. I will not get into the details of how it works; it was created just for demonstration purposes. It uses the standard ASP.NET controls, no mystery here. The buttons cause a postback to the server and the page reloads and fills the controls with the new data.


This page uses the same controls but it works quite differently. The controls are refreshed instantly and without any reloading by the browser. That's right, AJAX is here.

Hey, how did you do that

There are four steps required to convert BubisChat.aspx to AjaxBubisChat.aspx (or to apply AJAX to any page using this framework):

  • Make the page inherit from AjaxPage (optional)

    public class AjaxBubisChat : Ajax.AjaxPage

    Inheriting from AjaxPage is not required; it just handles the callback event and provides some useful properties for convenience. To handle the callback event in a page that inherits from AjaxPage, you override the OnCallBack method:

    protected override void OnCallBack(EventArgs e)
        // Refreshes the sessionID in the cache
        txtMsg.Text = chatData.msgText.ToString();
        base.OnCallBack (e);

    If the page doesn't inherit from AjaxPage, it can handle the callback event by implementing the ICallBackEventHandler interface:

    public interface ICallBackEventHandler
        void RaiseCallBackEvent();

    The callback is like a postback but without the reloading of the page by the browser. I'll explain what the callback does a little later. For reasons that will become clear later, the Load event of the page and its controls are not raised during a callback. You must use the callback event instead.

    During a callback, the HttpContext of the page is invalid, so you can't use the Request/Response properties of System.Web.UI.Page, you have to use the CallBackHelper.Request and CallBackHelper.Response properties instead. The AjaxPage provides valid Request/Response properties so that you don't have to replace them in your code for the ones from CallBackHelper.

  • Put inside an AjaxPanel the controls that will get refreshed without a postback

    It can be one AjaxPanel for each TextBox and ListBox, or one AjaxPanel for all of them. The buttons should be inside an AjaxPanel, so that their submit function is replaced automatically for a callback function. In this example, I just put all the controls inside one AjaxPanel for convenience.

  • Configure the web.config file


        <add name="AjaxHttpModule" type="Ajax.AjaxHttpModule, Ajax" />

    at the <system.web> section, and:

    <!-- If CallBackScriptPath is not set in the appSettings, 
                                     "/ajax/script" is used-->
    <add key="CallBackScriptPath" value="/ajax/script" />

    at the <appSettings> section of the web.config file.

    The AjaxHttpModule processes the callback at the AcquireRequestState event of the HttpApplication, after the request has been authenticated. The default script path is valid if you extract the source files to the wwwroot path. If you extract them to another directory, you should change the CallBackScriptPath of the application settings accordingly.

  • Enable the CallBackTimer on the page (optional)

    // For automatic CallBack every 3 seconds.

    This is required so that the chat textbox is automatically refreshed if there are new messages to display. Most pages don't need automatic refresh, so just ignore this if that's the case.

And believe it or not, that was all! No JavaScript and no replacement of the controls were necessary. You can add new controls to the AjaxPanel either by code or by using the Visual Studio Designer.

So, what does a callback do

The job of the callback is to invoke server-side control events (and a special CallBackTimer event if it is enabled). For more details, I suggest reading Bill Pierce's articles that I have mentioned in the Background section. When the server receives a callback, it returns generic JavaScript code. The client doesn't care what the JavaScript does (populating a ListBox, invoking an alert box, whatever), it just executes them. Thus, contrary to the usual mentality of AJAX applications, it's up to the server to manipulate the page using JavaScript, not the client. That way, instead of trying to embed JavaScript code in the web page and synchronize it with the server code, the focus is shifted on implementing all the functionality of a custom control on the server side without having to separate the code to the JavaScript part, and to the C# (VB.NET, whatever) part.

Now, it is getting more interesting... A page that is AJAX-enabled is stored as a session state variable. When a callback is invoked, the AjaxHttpModule intercepts it, finds the originating page from the session and invokes the appropriate events for the controls of the page without reloading the original page.

Why store the page in the session

  • There is no overhead because of constant reloading of the page and its controls.
  • The illusion of AJAX is that the page behaves like a desktop application. In a desktop application the controls are kept in memory without reloading them every time a button is pressed, and the controls can be added or removed dynamically. Well, by persisting the page in the session we don't have to reload the controls and the controls can be added or removed dynamically; and if you add them to the AjaxPanel they will actually appear on the browser too!

In order for a page to be stored in the session, it must contain at least one AjaxControl control (base class of AjaxPanel). The session key that is used is the URL of the originating page so that different pages can be distinguished from one another.

The callback doesn't have to come from a control contained inside an AjaxPanel, it can be invoked from any control on the page, as long as it is properly configured to call the appropriate callback function, like this:

Button btnSend = new Button();
btnSend.Attributes.Add ("onclick", 
   CallBackHelper.GetCallbackEventReference(btnSend) + 
   " return false;");

The CallBackHelper.GetCallbackEventReference method provides the AJAXCbo.DoPostCallBack call on the client side, and return false; is added so that the OnClick event can override the submit function.

The AjaxPanel, by default, automatically configures all the submit buttons that it contains to call the callback function and replaces the __doPostBack calls of normal postback with a AJAXCbo.DoPostCallBack call. If you want to manually set the OnClick event of your controls, set the SetCallBackForSubmitButtons and SetCallBackForChildPostBack properties of AjaxPanel to false.

The mysterious AjaxPanel

The task of AjaxPanel is to reflect its contents on the browser of the client each time a callback is invoked. To accomplish this, it scans the controls that it contains and produces the appropriate JavaScript code for every control that is added, removed, or altered, ignoring the controls that haven't changed at all. In order to spot changes, it renders each control and checks if the produced HTML is different from the one obtained during the previous callback.

In addition, if the AjaxPanel encounters any RenderedByScriptControl controls (AjaxPanel inherits from this class), it ignores them and lets them take care of their "reflection" to the browser. Thus, if an AjaxPanel (parent) contains another AjaxPanel (child), and a control of the child-AjaxPanel is altered, the parent-AjaxPanel won't send the entire HTML rendering of the child-AjaxPanel, but instead the child-AjaxPanel will send just the HTML of the altered control. That way, the size of the JavaScript code that the client gets as a response of a callback, is greatly reduced.


The known limitations are:

  • You cannot remove an attribute of the AjaxPanel control. The removal will not be reflected on the page. Use:
    ajaxPanel.Attributes["attrib"] = "";


  • The controls contained inside an AjaxPanel doesn't invoke client-side page validation by default. You have to "manually" insert the appropriate JavaScript in the OnClick event of the control.
  • Tested only in Internet Explorer and FireFox. There is no alternative to XmlHttp if it is not available for the browser.
  • Session must be in "InProc" mode. "SQLServer" and "StateServer" modes are not supported.

To sum up

I'm not going to get into the details of the inner workings of the classes. I have tried to document every method, so anyone wanting to extend the AJAX controls that are provided, I strongly recommend reading the comments of all the methods and the classes. For the rest who just want to use the framework:

  • The script path of the demo page is valid only if you extract the source files to the wwwroot path. If you extract them to another directory you should change the CallBackScriptPath of the application settings of web.config accordingly.
  • Follow the four steps that I have mentioned in the Using the code section of this article.
  • Read the comments of AjaxPage.cs, CallBackHelper.cs and ICallBackEventHandler.cs.
  • Read the comments of the public properties of AjaxPanel.
  • Read the comments of the AjaxLinkButton control.
  • You can send custom JavaScript to the client by using CallBackHelper.Write.
  • You must use the CallBackHelper.Request and CallBackHelper.Response properties in the code of your page, unless it inherits from AjaxPage. The same applies to your user controls and the AjaxUserControl that are provided.
  • Do not use Panel controls inside an AjaxPanel because even if only one child of the Panel changes, all its children will have to be rendered on the client. Use AjaxPanel controls instead.
  • After the update of 23-9-2005, the framework can handle the Response.Redirect and Server.Transfer methods during a callback. You don't have to change them in your code.
  • Use CallBackHelper.End instead of Response.End during a callback.
  • Always keep in mind that the callback is different from postback, because the page and its controls are persisted in the session, thus the Load event is not raised, and you can add/remove controls from the AjaxPanel dynamically, and the changes will be reflected on the browser. A bit like manipulating the controls of a desktop application.

Points of interest

AjaxPanel handles the "Browser Back Button" problem as well. The "Browser Back Button" problem is that by pressing the Back button, the browser loads the HTML page by its cache, so any AJAX changes made to the page are lost, while the user still expects to see the same page that he was viewing before.

To solve this, I have put in the page a JavaScript function that executes every time the page is loaded and a hidden field that is empty. The function checks this hidden field, and if it's empty, it assumes that the page was loaded by a request to the server (i.e. by the Refresh button) and sets the value of the field. If the function finds that the field is not empty, it assumes that the browser loaded the page by the Back button (the value of the fields are then restored) and invokes a special callback (CallBackStartup) on the server. When the CallBackStartup event is raised, AjaxPanel renders all of its children on the client page, thus restoring the previous page that the user was viewing.


I hope you find this framework useful. I encourage you to experiment with it, and if some fancy, jaws-dropping, eyes-bleeding, amazing control comes out of it, please share it with us.


  • 16-9-2005 - Initial release.
  • 16-9-2005 - Added in the article the browser detection limitation, noted by Cristian O.
  • 18-9-2005
    • Inheriting from AjaxPage is no longer necessary to use the AJAX Framework. Moved its functionality to other classes except the handling of the callback event and the Request/Response properties.
    • Added AjaxUserControl.cs with similar functionality as AjaxPage.
    • Replaced the AjaxHttpHandler with the AjaxHttpModule.
    • Added IPostDataLoadedEventHandler.cs.
    • Added NoVerifyRenderingPage.cs.
    • Added a few helper functions and properties to CallBackHelper.cs.
    • Other minor additions and improvements.
    • Updated the text of the article.
    • Fixed a bug in SetCallBackForChildPostBack of AjaxPanel, noted by Cristian O.
  • 21-9-2005
    • Fixed CallBackObject.js to make checkboxes work properly (noted by collab man).
    • Added the CallBackHelper.Redirect method and included it in the Sum up section of the article (noted by mdissel).
  • 23-9-2005
    • AjaxHttpModule can now handle Response.Redirect and Server.Transfer during a callback. CallBackHelper.Redirect is not required. Updated the article in the Sum up section.
  • 27-9-2005
    • Fixed a bug noted by collab man (controls not getting refreshed when callback is invoked by CheckBox or ListBox).
    • Fixed a bug noted by JunkyMail1 (multi-select ListBox not working properly).
    • Enhancements to CallBackObject.js provided by Cristian O. ("Loading..." indicator, callback timeout, response returned during an error is displayed on page).
  • 30-9-2005
    • AjaxPanel works properly now when its Visible property is changed.
    • Fixed the hidden controls persisting their state bug noted by mdissel.
  • 6-10-2005
    • Fixed the RadioButtonList problem noted by CarinLindberg.
  • 8-10-2005
    • In CallBackObject.js, fixed the post data not getting sent correctly when they contain '+', noted by Ricardo Stuven.
  • 11-10-2005
    • Added the fix for handling CheckBoxList, provided by Ricardo Stuven.
  • 12-11-2005
    • Included in the article the SourceForge and homepage link for MagicAjax.


This article, along with any associated source code and files, is licensed under The MIT License


About the Author

Argiris Kirtzidis
Web Developer
Greece Greece
No Biography provided

You may also be interested in...


Comments and Discussions

GeneralLet me understand it... Pin
asp20 coder6-Oct-05 18:22
sussasp20 coder6-Oct-05 18:22 
GeneralRe: Let me understand it... Pin
mbaskey7-Oct-05 0:00
membermbaskey7-Oct-05 0:00 
GeneralRe: Let me understand it... Pin
asp20 coder7-Oct-05 2:38
sussasp20 coder7-Oct-05 2:38 
GeneralRe: Let me understand it... Pin
Argiris Kirtzidis7-Oct-05 2:51
memberArgiris Kirtzidis7-Oct-05 2:51 
GeneralRe: Let me understand it... Pin
asp20 coder7-Oct-05 3:52
sussasp20 coder7-Oct-05 3:52 
GeneralRe: Let me understand it... Pin
Argiris Kirtzidis7-Oct-05 8:12
memberArgiris Kirtzidis7-Oct-05 8:12 
GeneralCall a javascript function from C# Pin
turnsharp6-Oct-05 13:09
groupturnsharp6-Oct-05 13:09 
GeneralRe: Call a javascript function from C# Pin
Cristian Odea6-Oct-05 23:00
memberCristian Odea6-Oct-05 23:00 
GeneralRe: Call a javascript function from C# Pin
turnsharp7-Oct-05 7:29
groupturnsharp7-Oct-05 7:29 
GeneralHandle more events Pin
Martinac6-Oct-05 11:55
memberMartinac6-Oct-05 11:55 
GeneralRe: Handle more events Pin
Argiris Kirtzidis7-Oct-05 2:53
memberArgiris Kirtzidis7-Oct-05 2:53 
GeneralRe: Handle more events Pin
Martinac7-Oct-05 4:38
memberMartinac7-Oct-05 4:38 
GeneralRe: Handle more events Pin
Argiris Kirtzidis7-Oct-05 8:17
memberArgiris Kirtzidis7-Oct-05 8:17 
GeneralNot working on framework 2.0 Pin
Member 21815595-Oct-05 7:07
memberMember 21815595-Oct-05 7:07 
QuestionRadio Button List problem Pin
CarinLindberg5-Oct-05 1:04
memberCarinLindberg5-Oct-05 1:04 
AnswerRe: Radio Button List problem Pin
Argiris Kirtzidis5-Oct-05 2:27
memberArgiris Kirtzidis5-Oct-05 2:27 
GeneralRe: Radio Button List problem Pin
CarinLindberg5-Oct-05 23:38
memberCarinLindberg5-Oct-05 23:38 
GeneralRe: Radio Button List problem Pin
CarinLindberg5-Oct-05 23:49
memberCarinLindberg5-Oct-05 23:49 
GeneralRe: Radio Button List problem Pin
Argiris Kirtzidis6-Oct-05 4:59
memberArgiris Kirtzidis6-Oct-05 4:59 
GeneralRe: Radio Button List problem Pin
CarinLindberg6-Oct-05 5:40
memberCarinLindberg6-Oct-05 5:40 
GeneralAjax panel is not functioning properly in findcontrol method Pin
sd_sathish4-Oct-05 23:49
membersd_sathish4-Oct-05 23:49 
GeneralRe: Ajax panel is not functioning properly in findcontrol method Pin
Argiris Kirtzidis5-Oct-05 2:29
memberArgiris Kirtzidis5-Oct-05 2:29 
GeneralRe: Ajax panel is not functioning properly in findcontrol method Pin
sd_sathish6-Oct-05 2:53
membersd_sathish6-Oct-05 2:53 
GeneralRe: Ajax panel is not functioning properly in findcontrol method Pin
Argiris Kirtzidis6-Oct-05 5:57
memberArgiris Kirtzidis6-Oct-05 5:57 
GeneralRe: Ajax panel is not functioning properly in findcontrol method Pin
sd_sathish10-Oct-05 2:18
membersd_sathish10-Oct-05 2:18 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web05 | 2.8.190306.1 | Last Updated 28 May 2007
Article Copyright 2005 by Argiris Kirtzidis
Everything else Copyright © CodeProject, 1999-2019
Layout: fixed | fluid