Windows DevCenter    
 Published on Windows DevCenter (
 See this if you're having trouble printing code examples

Drag and Drop Ajax Programming with Atlas

by Jesse Liberty

Just about every book or article I've read about Atlas has given me a headache. They seem to have two messages in common: (1) all my server-side ASP.NET applications are now obsolete, and (2) the only way to fix them is to add really complicated JavaScript. Woe is me.

These books and articles (which shall remain nameless because lawyers are so expensive these days) all seem to imply that to be a real Atlas programmer, I should stop hiding behind black-box controls and understand Ajax and JavaScript and, for good measure, XMLHTTPRequest objects! It's like a nightmare flashback to 1985 when, to be a real C programmer, you really needed to understand Assembler so that when things went wrong, you could drop down into the snap-shot debugger to see what was in the registers. (Haven't done that for a while, and I don't really miss it much.)

No! I won't have it. The move up the ladder of abstraction is a good thing. We were right when we said that by using a higher level of abstraction, we can better focus on the problem domain, leaving the "plumbing" to well-tested controls provided by Microsoft and other vendors. I'll be damned if I want to slip back into writing type-unsafe non-object-oriented JavaScript. Twenty years of progress up in smoke, down the drain, and out the door. Feh. (Feh is Yiddish for Yuck.)

Fortunately, it is a chimera, appearing on the horizon through the fractured lens of an early adopter's telescope. The script-centric approach is an artifact of pre-release technology being explored by those who know the underlying foundation of JavaScript best. When Ajax started to get very hot, the first ones to write about it were, naturally enough, JavaScript aficionados. They were the ones who could create JavaScript client-side code that made an appreciable difference in the user experience.

Atlas expertise has become equated with script expertise; a false identity needs to be exposed and broken as quickly as possible. When Programming ASP.NET,4th Edition is released, we will have a great deal of Atlas, but very little JavaScript. I feel very strongly that application programmers should focus on applications, and controls programmers should focus on building nicely encapsulated controls (no user servable parts, opening black box may void warranty).

This Article Shows No JavaScript

For this article, I am going to start top-down, using Atlas controls and drag-and-drop within Visual Studio 2005, and I am not going to look inside the black box at all if I can help it. (Almost seems impossible, or at least sacrilegious, no? But of course, that is exactly how I would teach normal ASP.NET controls.)

Will I cover everything? Nope. But we'll get a darn good look at how quickly and easily you can improve a working ASP.NET program with tested and working Atlas controls that you can download for free from Microsoft. And my guess is they'll be turning them out almost as fast as you can learn them.

What You Need to Write Atlas Applications

The Microsoft Atlas website provides a very good explanation of what you need to download and how to install the files (as well as how to integrate them into Visual Studio), so I won't waste your time recapitulating the instructions here. Please navigate to the ASP.NET Atlas home page and click on the Download icon to retrieve the JUNE CTP (presumably if there is a later CTP by now, you'll want that, and the example code for this article will work as is or with minor modifications). The June CTP comes in three parts: Documentation, Samples, and Setup. Only the third part is required, but you'll want all three. When you are done, return to the home page and click on the Atlas Control Toolkit; you'll need that later in the article.

The downloads include directions on adding two tabs to your toolbox (Atlas and Atlas Toolkit) and populating them with the controls (a matter of browsing for the appropriate DLLs). It is pretty easy, but if the drag-and-drop approach doesn't work, you can always right-click on the toolbox tab and select "Choose Items," then click Browse, find the Bin directory, and choose the DLL. Doing so will add all the Atlas controls from that dll to the tab, as shown in Figure 1.

Adding Controls
Figure 1. Adding controls from the dll

Starting with a Working Program

In May, I published Building a Web-Based Bug Tracking Application (Part 2). The article and complete source is available on my website (click on Books, then Articles). We'll use that application, which builds Tiny Bug Tracker as a starting point, adding Atlas functionality to improve the existing application, much as you might add Atlas controls to improve any web application you have already written.

The purpose of the Tiny Bug Tracker is to provide a single programmer (or a very small group of programmers) with a simple web-based application for tracking the progress of bugs reported, worked on, fixed, and closed by various members of the team. You begin by creating users and roles using the Web Site Administrator Tool, as shown in Figure 2.

Figure 2. Adding a user with the WAT (for more on ysabell see Discworld)

Users then sign in to use the application, as shown in Figure 3.

Logging In
Figure 3. Logging In

Users can click on the menu choice to Enter a bug, which brings them to the New Bug form (also used to edit bugs) as shown in Figure 4.

New Bug
Figure 4. Enter a bug

All of these bugs are placed into the TBTData database, with one entry for each bug in the Bugs table, and one entry for each modification of the bug in the BugHistories table, as indicated in Figure 5.

Figure 5. Bug Database

Once you have bugs in your database, you can review them in TBTReview.aspx. Clicking on Details brings up the Details panel for that bug, revealing the fields that do not fit in the grid. Clicking History brings up a grid with each change for the given bug, and you can then reveal the details for that change, as shown in Figure 6.

Figure 6. Review

There are a few problems with this application that Atlas can help us resolve. Each time you move from the details of one bug to the details of the next, the entire page is posted back to the server; there is a delay and hence, there is flicker. Also, as you scroll the review, you may realize you want to enter a new bug, but the menu is up on top, which forces you to scroll back. It would be nice to have the menu available. Finally, if you click Cancel when entering a new bug, it cancels--potentially throwing away a good deal of work accidentally.

Creating the Atlas Version

To make life easier, rather than adding Atlas controls to the existing application, I'm going to build a new Atlas application and then add the pages from the previous application. This ensures that Visual Studio will set up all the references that Atlas requires, and by using the pages from the previous article, I know that the basic application code should work, and I won't have to take time re-examining the underlying functionality. Note that I'm using the June CTP of Atlas; if you are using a different release, your mileage may vary.

What follows will make much more sense if you take a few moments to read through the original article. I'll wait here. Take your time. I'll work on other projects; wake me when you are ready.

First Improvement: Reduce Flicker--Only Update Part of Each Page

One of the biggest problems with the Tiny Bug Tracker application is that each time you ask for details on a different bug, the entire page must be redrawn, causing annoying flicker. (Due to caching, the database is not "hit" each time, but the round trip to the server does cause a noticeable pause).

We can use Atlas to ensure that we update only that part of the page that must be updated. To do so, we'll add four update panels to the TBTReview Page. An Update Panel is an Atlas control specifically designed to be updated independently of anything else on the page. The details of how it works may well be fascinating, but all you really care about is that it works asynchronously; that is, there is no need for a full-page postback. Even better, you can create each update panel by dragging it from the toolbox right onto the page and hey! presto! Visual Studio does the work for you. (You can also create an Update Panel by adding one by hand in source view, or you can create one dynamically in C# at runtime).

Creating the Atlas Application Step-by-Step

You can create your new application by starting with your existing application and adding the Atlas controls, libraries, and references. Really. But as I said above, I'm not going to do that because with beta software, I like to let Visual Studio set everything up just right. So, I'll create a new website called Atlas Bug Tracker by creating a New Web Site and choosing "Atlas Web Site" from the templates, as shown in Figure 7.

Create new web site
Figure 7. Create new Atlas website

The initial site will be built with a few files included by default: a readme.txt, a eula.rtf, a default.aspx, a web.config and, within bin, a copy of Microsoft.Web.Atlas.dll. Delete the readme, the eula, and Default.aspx; you won't be needing them.

Open the WAT, and on the security tab, choose forms-based authentication, and create the user names and roles you had in the previous application (Alex, Dan, Jesse, and Stacey and Developer, Manager, QA, and User).

Copy over the pages TBTMaster.master, TBTReview.aspx, TBTBug.aspx, and TBTWelcome.aspx and their codebehind pages, and add them to the project. Do not copy over the web.config file.

The WAT has modified the web.config file created for you when you chose the Atlas project, so you now have the combined configuration of both: an Atlas project with forms-based security.

You'll want to run the program and make sure everything is right before you begin making changes.

Note: the complete source code is available for download from my website. (Click on Books, and then on Articles), along with a link to my private support forum and other material that may be of interest.

The Script Manager

The key control for Atlas is the ScriptManager. Virtually every Atlas control requires that its page has a ScriptManager whose job is to coordinate all the Atlas controls on that page. Fortunately, this application has a master page, so we can drop our ScriptManager on the master, providing one ScriptManager for every page in the application (One ScriptManager to rule them all, one ScriptManager to find them...*).

The one attribute that we will need to add to the ScriptManager is EnablePartialRendering="True" because it turns on the ability to render part of the page asynchronously without a full-page postback.

You can place the ScriptManager control anywhere in the master page. I've put mine right below the login status control:

       <atlas:ScriptManager ID="ScriptManager1" runat="server" EnablePartialRendering="True" />

Dragging and dropping the control from the toolbox is probably the easiest way to add it to the page, and doing so ensures the control is properly registered on the page. When you do, however, you are likely to see the Destination File Exists dialog box, as shown in Figure 8.

Destination File Exists
Figure 8. Destination File Exists

When the control is added to the page, it brings Microsoft.Web.Atlas.dll with it. There is no reason not to click Yes and refresh the file.

Breaking TBTReview into Sections

With the ScriptManager in place, you are ready to add asynchronous updates for the various grids and DetailsView objects on the TBTReview page. To do so, drag four UpdatePanel objects from the Atlas tab of the Toolbox onto the page. Each UpdatePanel represents a block of UI that can be updated independently. I placed BugReviewGrid and its data source into the first, BugDetailsView and its data source into the second, BugHistoryGrid and its data source into the third, and BugHistoryDetailsView and its data source into the fourth. You can do this with drag-and-drop in Design view, or by moving the HTML in Source view.

For example, in Figure 9, I've dragged UpdatePanel2 onto the form, and I'm dragging BugDetailsView into the Panel.

Dragging into UpdatePanel
Figure 9. Dragging into the Update Panel

When I release the mouse, BugDetailsView and its SqlDataSource will be inside the Update panel, as reflected in the HTML in Source view (severely abridged here):

    <span class="style1"><atlas:UpdatePanel ID="UpdatePanel2" runat="server">
          <asp:DetailsView ...  </asp:DetailsView>
           <asp:SqlDataSource ...>   </asp:SqlDataSource>
      <span class="style1"></ContentTemplate>

The change in performance is instant and remarkable. Suddenly, the page stops flickering. When you move from one bug's details to another, it is smooth, instantaneous, and flicker-free. To make sure the difference is real, remove the attribute EnablePartialRendering="True" from the ScriptManager in the master page and rerun the application. You can't miss it.(Don't forget to put the attribute back!)

Look Ma, No JavaScript

Stop a moment and notice that at no time did you write JavaScript. You didn't touch XMLHttpRequest, and you have no idea how the work is done; it is all every bit as magical as how, for example, the DataGrid control itself works. Here's what I say: that is not only OK, that is jolly good. This ignorance lets you focus on what you're trying to do, and lets Microsoft focus on building the controls. (Hey! Stop whimpering. If you really want to know how it works, I promise, we have lots of books on JavaScript and on Programming Atlas that go into all the gory details. But isn't it nice, just for the moment, to focus on getting the job done?)

But There's More...

OK, we've accomplished asynchronous updates, and we could stop there and feel pretty good about Atlas, but let's take a peek at control extenders. You get quite a few with the Atlas Toolkit (and more are on the way all the time). One I really like already is the AlwaysVisible extender. This allows you to take any control and say, "I want this to stay visible on my page as the user scrolls through it." Not only is this impressive as all get-out, it is actually quite useful. It gives you the power of frames without any of the hassle (and frames, I'm told by my designer friends, are oh-so-five minutes ago).

Our master page has a few items on it, one of which is a menu that lets the user add new bugs. It would be nice if the user could get to that menu even if s/he has scrolled down on the review page. This turns out to be so easy as to be embarrassing.

Open TBTMaster.master and drag an instance of AlwaysVisibleControlExtender onto the page. Do this in source view. Between the open and close tags, you'll add one element (Intelligence will offer it for you) of type AlwaysVisibleControlProperties. Intelligence will help with the properties, but I'll show them to you here:

VerticalSide ="top"
VerticalOffset = "10"
HorizontalOffset ="10"
HorizontalSide ="right"
ScrollEffectDuration =".1" />

The TargetControlID is the control that you will be making visible--in this case, the menu. The vertical and horizontal sides dictate where you want the menu to appear (see Figure 10). The offset is how far from the top/right you want the menu to appear, and the scroll effect duration is how long a delay you want (in this case, a tenth of a second). I hate to admit it, but that is all you do; Atlas takes care of the rest. As you scroll, the menu follows you, like a loyal puppy.

Always Visible
Figure 10. Always Visible Menu

It is almost magical how the menu chases after you as you scroll down to look at a bug's detail. It is magical how little you have to do, and it is damnable how hard some people make it seem. I love the fact that Microsoft has encapsulated all this into a control that I can just drag onto my form and--poof!--it works. Yes, over time, I'll want to understand (maybe) how they did it, but you know what? I have deadlines, and this is very cool functionality.

Creating a Trap for Cancel

One bit of coding that we all write a dozen (or a thousand) times is a "trap" for a Cancel button. The user clicks Cancel, and we want a popup that asks the user to confirm that s/he intended to cancel out of the work being done. This can be tricky to write in an ASP.NET application, as dialog boxes do require some JavaScript. Once again, however, Atlas not only makes this trivial, it does so in a way that is totally consistent with the rest of Atlas and integrates seamlessly with your existing application.

The TBTBug.aspx file has two controls, btnSave and btnCancel. To add a trap for btnCancel, all you need do is drag a ConfirmExtender into the cell with the two buttons:

<td colspan="2">
   ID="ConfirmButtonExtender1" runat="server">
      <AtlasToolkit:ConfirmButtonProperties ConfirmText="Are you sure you want to discard this?"
       TargetControlID="btnCancel" />
    <asp:Button ID="btnSave" runat="server" Text="Save" BackColor="Lime" Font-Bold="True" OnClick="btnSave_Click" />
    <asp:Button ID="btnCancel" runat="server" Text="Cancel" BackColor="Red" Font-Bold="True" ForeColor="Yellow" OnClick="btnCancel_Click" />

The effect is illustrated in Figure 11.

Cancel Confirmation
Figure 11. Cancel Confirmation

The ConfirmExtender takes one internal attribute of type ConfirmButtonProperties, which itself takes two attributes, one for the text to display in the message box, and the other to identify the button that triggers the confirmation.

For this to work, the control must be registered, but that is done for you when you drag the control onto the form. Sweet. In the version I'm using, the tag is set at CC1, but it's simple to change the tag to something you like; I changed it to AtlasToolkit

<%@ Register Assembly="AtlasControlToolkit" Namespace="AtlasControlToolkit" TagPrefix="AtlasToolkit" %>

so that when I use the control, I can write code like this: <AtlasToolkit:ConfirmButtonProperties, which reminds me of the source of the control. Not necessary, but nice.

There are a lot of useful controls that come with the Toolkit, and I strongly encourage you to take a look at the video tutorials available in the Atlas How Do I series, which will walk you through much of this material and beyond. You may want to subscribe to one or more of the RSS feeds that will keep you up-to-date on what Atlas controls are being released.

Above all, don't let anyone convince you that Atlas is difficult. The whole point is for it to be as easy as ASP.NET, allowing you to keep your focus on building your application, and not on building the plumbing.

Jesse Liberty is a senior program manager for Microsoft Silverlight where he is responsible for the creation of tutorials, videos and other content to facilitate the learning and use of Silverlight. Jesse is well known in the industry in part because of his many bestselling books, including O'Reilly Media's Programming .NET 3.5, Programming C# 3.0, Learning ASP.NET with AJAX and the soon to be published Programming Silverlight.

Return to the Windows DevCenter.

Copyright © 2009 O'Reilly Media, Inc.