Click here to Skip to main content
15,847,583 members
Articles / Web Development / HTML

Magic AJAX: Applying AJAX to your existing Web Pages

Rate me:
Please Sign up or sign in to vote.
4.82/5 (72 votes)
28 May 2007MIT12 min read 959K   2.6K   251   283
How to apply AJAX technologies to your web pages without replacing ASP.NET controls and/or writing JavaScript code.

Image 1


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

Written By
Web Developer
Greece Greece
This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.

Comments and Discussions

GeneralIs Magic Ajax dead Pin
Hardy Wang2-Feb-09 4:26
Hardy Wang2-Feb-09 4:26 
GeneralRe: Is Magic Ajax dead Pin
BrianByExperience16-Jun-22 6:34
BrianByExperience16-Jun-22 6:34 
GeneralUnable To Use magicajax Pin
manojbhoyar11-Sep-08 21:22
manojbhoyar11-Sep-08 21:22 
Generalwoooh... Pin
hotvikky14-Apr-08 22:36
hotvikky14-Apr-08 22:36 
QuestionProblem on MagicAjax.dll Pin
leon9167-Mar-08 20:25
leon9167-Mar-08 20:25 
GeneralClient event upon completion Pin
Dewey13-Jul-07 16:34
Dewey13-Jul-07 16:34 
QuestionProblem on deployment on hosted server Pin
harsh067@gmail.com21-Jun-07 6:24
harsh067@gmail.com21-Jun-07 6:24 
GeneralThank you Pin
merlin98128-May-07 8:08
professionalmerlin98128-May-07 8:08 
Generalajax enabled web application Pin
veerbala4-Apr-07 20:19
veerbala4-Apr-07 20:19 
GeneralProblem with Reset onMagic Ajax Callbacks Pin
.NET Follower20-Dec-06 19:28
.NET Follower20-Dec-06 19:28 
Generalconfusing problem with Magic Ajax Pin
minckle4-Dec-06 5:13
minckle4-Dec-06 5:13 
GeneralRe: confusing problem with Magic Ajax Pin
Yogesh Jamkhindikar13-Dec-06 0:55
Yogesh Jamkhindikar13-Dec-06 0:55 
GeneralPage.RegisterStartupScript or Page.RegisterClientScriptBlock does not work with MagicAJAX and ASP.Net 1.1 Pin
Sucharit Sengupta16-Nov-06 23:49
Sucharit Sengupta16-Nov-06 23:49 
QuestionProblem using majic ajax on 1.1 Pin
Saud AKhter3-Nov-06 2:31
Saud AKhter3-Nov-06 2:31 
QuestionDatalist & DropDownList problem... Pin
Rothariger28-Sep-06 5:46
Rothariger28-Sep-06 5:46 
QuestionThe usage of session and viewstate is unavaible?? Pin
steven_wong28-Aug-06 23:38
steven_wong28-Aug-06 23:38 
QuestionI need help in MagicAjax 0.3 [modified] Pin
coolshad10-Aug-06 1:04
coolshad10-Aug-06 1:04 
QuestionHow to manage the Menu Control in ASP.NET 2.0 Pin
Rhlye26-Jul-06 7:22
Rhlye26-Jul-06 7:22 
AnswerRe: How to manage the Menu Control in ASP.NET 2.0 Pin
lawsop24-Jan-07 6:59
lawsop24-Jan-07 6:59 
Questionthank u ..some queries? Pin
coolshad31-May-06 11:52
coolshad31-May-06 11:52 
QuestionWhat about server side function ? Pin
w3Nima11-May-06 2:00
w3Nima11-May-06 2:00 
QuestionMagic ajax is better or outpost? Pin
somaieh1-May-06 5:24
somaieh1-May-06 5:24 
GeneralThankyou Pin
eepeesn20-Apr-06 6:03
eepeesn20-Apr-06 6:03 
QuestionDoes Magic Ajax work with libraries like RICO and Prototype? Pin
sadlermd27-Mar-06 17:17
sadlermd27-Mar-06 17:17 
GeneralChat Application. Pin
RK KL25-Mar-06 7:10
RK KL25-Mar-06 7:10 

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.