Friday, July 31, 2009

Atlas Tutorial: Creating an AJAX Scribble application

Please read instructions at the end of article on how to run the application after downloading the source.

Image in Internet Explorer Image in FireFox


ASP.NET Atlas is a rich set of client side and server side libraries to develop AJAX-style applications using ASP.NET. This tutorial (and probably more in this series) attempts to provide a general view of the features available in Atlas. Since, Atlas is a very vast library this very first tutorial concentrates on two most important features of Atlas:

  1. Ability to call server side web services from client side scripts
  2. Ease of developing cross-browser compatible JavaScript code


MFC Scribble application was one of the first application that I used to learn MFC. Therefore, I decided to base this tutorial on Scribble. Scribble application allows users to draw freehand sketches using the mouse. I first saw a similar application on the web, utilizing AJAX technologies, at the JavaScript Draw website. The JavaScript draw website works only on Mozilla Firefox. This article describes how to build a cross-browser version of the application. We will build on the application in each article in this series to demonstrates more features of Atlas.

Installing Atlas

At the time of writing of this article, December CTP of Atlas can be downloaded by clicking this link. If this link does not work you can always go to the Atlas website to get the correct link. The Atlas library is available as a Visual Studio 2005 template (VSI). The download site has instructions on how to install the template.

Creating an Atlas Project

Once the Atlas template is installed you can create a blank Atlas project by clicking selecting the menu option: File -> New -> Web Site. This brings up the New Web Site dialog box as shown.

Visual Studio Project

Under location you can either select File System or HTTP. Selecting HTTP will allow you to create a web site on an IIS server and selecting File System will allow you to create a web site on your local file system (which you can debug and test using the ASP.NET development web server). You can select either option but I have found the application to work better with Internet Explorer on IIS.

Atlas Blank Project

The newly created Atlas web site has the following directory structure.

  • App_Data
    This is an empty directory where you can place data files.
  • Bin
    This is the directory where dll file for the assembly Microsoft.Web.Atlas is placed. This contains the server portion of the Atlas library.
  • ScriptLibrary
    A directory where you can place any JavaScript files for the application.
    • Atlas
      Atlas client Scripts are placed here in two different subdirectories.
      • Debug
        The debug version of Atlas client side JavaScript files are placed in this directory.
      • Release
        The release version of Atlas client side JavaScript files are placed in this directory. The scripts in this directory are more compactly written and have some debug code removed.

Atlas Client Scripts

The December release of Atlas has the following client scripts.

  • Atlas.js
    This is the core Atlas script file consisting of basic utility functions and client side controls and components.
  • AtlasCompat.js
    This file contains the Atlas compatibility layer for supporting Mozilla Firefox and Apple-iMac-Safari web browsers. This script ensures that Atlas code is cross browser compatible.
  • AtlasCompat2.js
    Additional functions to ensure compatibility for the Safari web browser, are included in this file.
  • AtlasRuntime.js
    This is a scaled down version of the core Atlas script file. This script file does not have the client side components and controls. This script file can be used when the aforementioned components or controls are not being used in a web page.
  • AtlasUIDragDrop.js
    This file contains utility functions to provide drag drop functionality in a web page.
  • AtlasUIGlitz.js
    This file contains utility functions to provide animation and other special effects in a web page.
  • AtlasUIMap.js
    This is the script file for Atlas mapping framework that uses Virtual Earth.

Other Files

Atlas adds the following files to the root directory of the web site.

  • Default.aspx and Default.aspx.cs
    This is a web page containing Atlas Script Manager control that is responsible for rendering script blocks referring to the Atlas client side scripts. An client script of type
    test/xml-script block is also added to the page. This script block is used to write scripts using declarative XML syntax.
  • eula.rtf
  • readme.txt
  • Web.Config
    The web.config is essential for running Atlas applications. It contains some configuration settings specific to Atlas and also adds the Atlas HTTP modules and HTTP handlers.

The Scribble Application

The Scribble application allows users to draw freehand sketches by clicking on the left mouse button and moving mouse around. A sketch stroke ends when the user releases the mouse button or moves outside the drawing area. There are ways to draw using JavaScript by utilizing VML, but we are not going to use VML in this sample.

The default web page in Scribble will have an image (a regular HTML image - the IMG tag). The user mouse events over the image are captured using JavaScript event handlers. The JavaScript functions send the series of points in a sketch stroke to a web service. The web service updates and image object saved in a session variable by drawing lines through all the points sent by the client. Finally, the client requests an updated image from the server. The image source is an HTTP handler which streams the image stored in the session variable to the client. Here are the main components of the application.

  • Default.aspx
    The page with the dynamic image and Atlas Script Manager control.
  • ScribbleImage.ashx
    This is an HTTP handler which streams the image object stored in the session variable.
  • ScribbleService.asmx
    This is the web service to which all the sketching requests are sent. The webservice modifies the image.
  • Scribble.js
    The JavaScript code for the application resides in this file to make a clear separation between design and the code.
  • Global.asax
    The Session_Start and the Session_End events are handled in Global.asax. The Session_Start creates the session variable and Session_End disposes the image stored in the session variable.


We begin our coding process from Global.asax.

  1. In the Website menu click on Add New Item or press Ctrl + Shift + A.
  2. In the Add New Item dialog box select Global Application Class and click ok. You will see the Global.asax file created.
  3. We start by importing the System.Drawing namespace. Insert the following line of code just after the first line.