The new AJAX Enabled functionality now built into the Map Suite Web Edition allows you to do many common operations without the overhead of a page post-back. To quickly get you started, we have provided this document which covers the basics. For more advanced interoperation with other controls, it is best to have a good working knowledge of JavaScript and the principles behind AJAX-based technology.

A Word About the Scope of This Document

This document only covers the AJAX integration within the map control itself and does not cover other more general AJAX concepts or other AJAX implementations such as Microsoft's Atlas. Our goal in integrating AJAX with the Web Edition was to provide a standalone API to enable our customers to easily harness the power of AJAX without being dependant on any specific third party framework.

Understanding the Web Edition AJAX Step-By-Step

Step 1: Enabling AJAX

The Map Suite Web Edition now operates in two modes. The first is compatibility mode, which uses post-backs as the method of refreshing the map, and the second is AJAX mode, which uses asynchronous JavaScript to accomplish the same goals without the post-back. By default, the map control will be set to use compatibility mode, so the first thing we need to do if we want AJAX functionality is to turn AJAX mode on. We suggest you do this in the page's form load event.

In the Page_Load event, add:

Step 2: Setting AJAX Map Modes Using JavaScript

The next step is to wire the new JavaScript events to the buttons that will control the various modes of the map, such as track zoom in, track rectangle, etc. In the past we typically used ASP buttons that would post-back, and then on the server side we would change the mode of the map to, for example, "TrackRectangle" or "TrackPoint." With AJAX we do not need to post-back to the server for these operations, so we will now use simpler HTML elements instead of ASP buttons.

We'll use an HTML image element as an example:

As you can see above, this will not cause a post-back, but will put the map in the correct mode. The key item above is the "onclick" event we specified. There are many new functions you can use to set the map into various modes on the client, and a complete list is further below. The "onclick" event can take up to two parameters; the first parameter is the map control ID that specifies which map to change the mode of, especially on a page with multiple map controls. The second parameter is an argument that you can optionally use to pass information back to the server side.

Specifying an argument to pass back to the server side:

In the example above, we are calling the "SetTrackRectangle" mode and specifying this is for searching for pay phones. Using this technique, you can have many different rectangle searches and be able to tell them apart on the server side. After the user draws the track rectangle on the screen, a new event will be called on the server side.

Server side code to process after the user draws the track shape:

Inside this event, you can access the track shape and the optional argument you specified in the JavaScript function.

Predefined functions:

SetTrackZoom(MapControlID)
SetPan(MapControlID)
SetCenter(MapControlID)
SetTrackEllipse(MapControlID, EventArgument)
SetTrackPolygon(MapControlID, EventArgument)
SetTrackRectangle(MapControlID, EventArgument)
SetTrackCircle(MapControlID, EventArgument)
SetTrackLine(MapControlID, EventArgument)
SetTrackPoint(MapControlID, EventArgument)
SetSelectMapShapes(MapControlID, EventArgument)
SetSelectFeatures(MapControlID, EventArgument)
SetSelectFeaturesAndMapShapes(MapControlID, EventArgument)

Step 3: Setting AJAX Custom Events Using JavaScript

In the previous step, we wired up the JavaScript events that took care of changing the map modes. However, there are also functions such as zooming, panning and custom actions which may require the map to refresh without a post-back. We cover those actions by using a JavaScript function called AjaxEvent, which takes an action name and the map control ID.

We'll use an HTML image element as an example:

In the sample above, we call the "AjaxEvent" function, passing in the action (which is "ZoomIn") and the map control ID as seen in the previous sample. The action is text that will be passed to the server side to take action on. Whenever the image is clicked, an event on the server side called AjaxPostback gets raised. Despite the naming, this is not a page post-back and from the user's perspective they will not know we went back to the server.

Server side code to process the user events:

As you can see from the above sample code, all we need to do is call the map operation we need. In the case of a Zoom In button, we simply call Map1.ZoomIn(40). After this event is finished, the server will generate a new map image and that image will automatically get loaded on the client side without a full page post-back.

In some instances it is necessary to force the screen to post-back after a map operation. This is typically when you may have data grids or some non-AJAX enabled controls that need to be refreshed. In this case, you can simply set the force post-back variable to true as in the sample below.

Notice the case with the track rectangle will now force a post-back. This can be used in many cases where you need to update other non-AJAX controls on the page.

Step 4: Passing Arguments Back to the Client from the Server

After performing an action such as zooming in or out, you may want to update an HTML element on the client side – for example, a zoom bar. To do this, we have provided a mechanism for passing a string back from the server side to the client JavaScript side. The new property on the map control is called "AjaxEventArgs" and is accessible from anywhere on the server side. You can pass any text you need back to the client and in complex situations, when you need to pass back multiple items or lists, you can use XML and parse it on the client side.

When the processing returns from the server side to the client side, a user-implemented JavaScript function is called. This is your chance to process the return arguments and update whatever you need to on the client. The important thing to know is that you need to create this function and the Map will call it on the client side.

In the sample above, the server side returned the name of a city and we updated an HTML tag.

Step 5: Review the Sample Applications & Start Coding

As always, we have provided many samples in C# and VB.NET that demonstrate AJAX in actions. I suggest your next step is to review a few of them and single-step through to see the how the events fire. The best way to learn anything is to jump right in, so whether you experiment with one of our samples or start from scratch, use the samples and this document as a guide, share your questions on our discussion forum — and happy coding!

Sample Life Cycle for a Track Shape

• The page is called and the server side renders the map control.
• On the client side, the user performs an action such as clicking a button, which calls the JavaScript function SetTrackPoint(MapControlID, EventArgument) to set the map to the track point mode. Note that when this happens, the map does not go back to the server.
• The user now clicks on the map where they want the track point to be. The map will go back to the server via asynchronous JavaScript and the following server side functions will fire (note that this will not be a full page post-back):
  
  Map1_AjaxFinishedTrackShape
Map1_AjaxPostback
• During server side execution, you can set a return argument using the Map1.AjaxReturnArgs property of the map.
• When the server side code is finished executing, it will return to the client and refresh the map image.
• After refreshing the image, the map will call the user-implemented function CustomCallback where you can update other client side controls.

Sample Life Cycle for a Zoom In Operation

• The page is called and the server side renders the map control.
• On the client side, the user performs an action such as clicking a button, which calls the JavaScript function AjaxEvent('ZoomIn', 'Map1'). This passes in one string to tell the server what operation to perform and another to specify the map control ID. Note that when this happens, the map will go back to the server through asynchronous JavaScript.
• On the server side, the Map1_AjaxPostback event is fired, and inside there you would call the Map1.ZoomIn(30).
• During server side execution, you can set a return argument using the Map1.AjaxReturnArgs property of the map.
• When the server side code is finished executing, it will return to the client and refresh the map image.
• After refreshing the image, the map will call the user-implemented function CustomCallback where you can update other client side controls.

Sample Life Cycle for a Select MapShapes

• The page is called and the server side renders the map control.
• On the client side, the user performs an action such as clicking the map control, which calls the JavaScript function SetSelectMapShapes(MapControlID, EventArgument) to set the map to SelectMapShapes mode. Note that when this happens, the map does not go back to the server.
• The user now clicks on the map shape they want select. The map will go back to the server via asynchronous JavaScript and the following server side functions will fire (note that this will not be a full page post-back):
  
  Map1_AjaxSelectMapShapes
Map1_AjaxPostback
• During server side execution, you can set a return argument using the Map1.AjaxReturnArgs property of the map.
• When the server side code is finished executing, it will return to the client and refresh the map image.
• After refreshing the image, the map will call the user-implemented function CustomCallback where you can update other client side controls.

Sample Life Cycle for a Select Features

• The page is called and the server side renders the map control.
• On the client side, the user performs an action such as clicking the map control, which calls the JavaScript function SetSelectFeatures(MapControlID, EventArgument) to set the map to SelectFeatures mode. Note that when this happens, the map does not go back to the server.
• The user now clicks on the map where they want to get features. The map will go back to the server via asynchronous JavaScript and the following server side functions will fire (note that this will not be a full page post-back):
  
  Map1_AjaxSelectFeatures
Map1_AjaxPostback
• During server side execution, you can set a return argument using the Map1.AjaxReturnArgs property of the map.
• When the server side code is finished executing, it will return to the client and refresh the map image.
• After refreshing the image, the map will call the user-implemented function CustomCallback where you can update other client side controls.

If you have questions about anything covered in this QuickStart Guide, the ThinkGeo Support Team is ready and available to help. If we can be of any assistance, please contact us using the below information:

Free Discussion Forums: ThinkGeo Discussion Forums
Pre-Sales & Customer Support: ThinkGeo Customer Portal
Support Phone: (866) 847-7510
Web Site: http://thinkgeo.com