Introduction to Anthem.NET

Introduction

AJAX is something lots of ASP.NET developers are interested in, but there are a number of AJAX libraries and solutions out there - so which one do you go for?

When looking myself, the criteria I used were:

support ASP.NET 2.0 as that's what I'm using,
soak as seamlessly as possible with VS2005, ideally without having to hand-code client-side JavaScript, and
support ASP.NET functionality as closely as possible.

Having looked at the various AJAX libraries out there (including Atlas), I noticed that the ASP.NET forums were using a library I hadn't seen before (and it's not Atlas!). Web searches led me to Jason Diamond's MyAjax.net which has recently been redesigned and launched on SourceForge.Net as Anthem.NET, so it's now an official OpenSource project. There are also some discussion forums.

Note: It was pointed out in the comments that I had not addressed the issue of cross-browser compatibility, which is obviously quite important! I'm glad to report that Anthem.NET works on IE, FireFox, and Safari (reportedly much better than Atlas, as I write). The developer has even put work into making sure it runs under Mono as well.

Just Another AJAX Library?

So, is Anthem just another AJAX library? No, and I'd even venture [tin helmet on] it's the best one I've seen for ASP.NET. Anthem is so easy to use, it's almost a crime. It ticked all my criteria (it supports both .NET 1.1 and .NET 2.0), and has a number of built-in AJAX-enabled controls. It supports viewstate, so you can get control states and page info back in callbacks. It works seamlessly with web usercontrols, and master pages; and having used it on a live application, I can say it's reasonably stable. Best of all, you won't need to write any JavaScript (or XMLscript).

Getting Athem.Net

First, you need to download Anthem.NET 1.0, which you will find from the links on the main page here. Unfortunately, the DLL is not precompiled in the snapshots, so you will need to extract the projects and compile them to get the DLL.

There are two versions of Anthem, one each for VS2003, and one for VS2005. You'll also find that the Anthem snapshot has a demonstration website included in the file, that demos the various controls and how to use them.

Using Anthem in VS2005

Assuming you've done this and have created the DLL, all you need to do to install Anthem.NET in a web application is add the DLL as a reference to your web application. You can then make the Anthem controls available by creating a new tab in the Toolbox, and use the right-click menu "Choose Items" - click Browse and locate the Anthem DLL.

All the Anthem controls are essentially subclassed ASP.NET controls, so you can use them on a web page just as you would a normal ASP control. In general, if you don't need AJAX functionality, it's better to use the normal ASP.NET controls, as these won't have the HTML overhead.

A Simple First Test

In our first demo page, we are going to use Default.aspx which should have been created for you when you created the website. Let's say, we want to have a "login" button on this page, but we don't want to redirect to another page which shows the login control, we want to unhide a login control so that the response is faster. If we use a traditional ASP.NET postback, the whole page has to be reloaded to make this visible.

To do this with Anthem, we need two Anthem controls: a LinkButton and a Panel. Drag these from your *Anthem* toolbox. Set the 'Text' property of LinkButton1 to "Login". Now, drag an ASP.NET login control from the ASP.NET 'Login' tab, and place it inside Panel1. Using an Anthem Panel control is the simplest way of providing AJAX updates to non-Anthem controls, if needed. Set Panel1's property Visible to false, so that it isn't visible by default.

Page

Now the magic! Double-click the LinkButton on the designer. You should now be in the code editor, with a template LinkButton1_Click function. This is not a postback but a callback function.

Anthem will:

create the necessary JavaScript on the client,
bind it to the control's OnClick event,
receive the XMLhttprequest on the server, and
call the LinkButton1_Click in your server-side code.

Not only this but you have full viewstate, page and control states loaded. Indeed, you can treat Anthem callbacks exactly like a postback, with only one exception: the only client controls updated are those you specify. To do this, you have to set the Anthem controls' UpdateAfterCallBack property to 'true'. If the control contains other non-Anthem controls (as our Panel1 does), then this will be updated. You can also pre-specify a control as UpdateAfterCallback=true in the designer, if you always want it to update.

Back to our demo - we add the following code to make the Panel1 visible and also update this back in the callback result:

    protected void LinkButton1_Click(object sender, EventArgs e)
    {
        // toggle Panel1 visibility
        this.Panel1.Visible = ! this.Panel1.Visible;
        // tell Anthem to update this control
        this.Panel1.UpdateAfterCallBack = true;
    }

Now, try running this. The page comes up with just the login link. Click the login link, and the callback is sent to the server, which makes Panel1 visible, and returns the updated Panel1 control. Presto, the login control appears without a postback. Look ma, no JavaScript!

To show we have control states passed back, let's try another test. Back in the designer, drag a normal ASP.NET TextBox control onto the web page (below the Panel1 is fine). We will copy the value of this control into the UserName field of the login control when we make it visible, so amend the LinkButton code as follows:

    protected void LinkButton1_Click(object sender, EventArgs e)
    {
        // set username from textbox
        this.Login1.UserName = this.TextBox1.Text;
        // toggle Panel1 visibility
        this.Panel1.Visible = ! this.Panel1.Visible;
        // tell Anthem to update this control
        this.Panel1.UpdateAfterCallBack = true;
    }

When you run the code this time, enter some text in the textbox before you click Login. Note, this is passed back in the viewstate, and is available to our callback code.

Another refinement: what if we have a slow connection? the user might click Login to get the page, but a second or two's delay might make them think nothing has happened (especially if the server is loaded). They might click it again, and cause the login control to flick on/off. It's similar to the Order Submit problem where you only want the user to click the Submit button once. Anthem controls like LinkButton and Button have two useful properties: TextDuringCallBack and EnabledDuringCallBack. If we set EnabledDuringCallback to false, the button is disabled during the callback processing time. To give the user some feedback, you can also set TextDuringCallBack=Wait so they know something's happening. If you run this on a local IIS, it's so quick you won't see it, so let's add a delay so it's easier to see:

    protected void LinkButton1_Click(object sender, EventArgs e)
    {
        // simulate network delay with 2 sec delay
        System.Threading.Thread.Sleep(2000);
        // set username from textbox
        this.Login1.UserName = this.TextBox1.Text;
        // toggle Panel1 visibility
        this.Panel1.Visible = ! this.Panel1.Visible;
        // tell Anthem to update this control
        this.Panel1.UpdateAfterCallBack = true;
    }

Conclusion

I hope this article has whetted your appetite. Anthem.NET is the library that Microsoft should have written, and having looked at Atlas, I found it too complex. It's such an easy way to add AJAX functionality to an ASP.NET website that I'm sure you'll find it as useful as I am already doing!