disambiguation, virtual earth, and other words to impress your friends

Ah, disambiguation. It's such a great word. I'll use it frequently throughout this posting because it makes me sound smart. I suggest you use it with your friends and co-workers for the same reason.

Disambiguation is the process of narrowing your search criteria in Virtual Earth from something fairly generic or confusing to something exact. For example, if you were to search for McChord, VE wouldn't know for sure if you meant McChord AFB or something else, so VE would need you to clarify before showing you a map.

That's where disambiguation comes into play. Virtual Earth will prompt you with a list of possibilities - forcing you to disambiguate by selecting a specific location.

Disambiguation, disambiguation, disambiguation...

The easiest way to handle disambiguation is to let Virtual Earth handle it for you. The way you do that is to set the ninth argument in the Find method to true. This argument is the useDefaultDisambiguation argument and basically it tells Virtual Earth to prompt the user with a list of possibilities if their criteria isn't specific. The code for this is simple and looks like this:

<script type="text/javascript">
var map = null;
var results = null;

//called from body.onLoad
function GetMap()
{
  map = new VEMap('MapDiv');
  map.LoadMap();
}

function FindLocation()
{
var where = "McChord";
try
{
 map.Find(null,
  where,
  null,
  null,
  0,
  10,
  true,
  true,
  true, //useDefaultDisambiguation
  true,
  ProcessResults);
}
catch(e)
{
 alert(e.message);
}
}

//callback function for map.Find
function ProcessResults()
{
}
</script>

So, in the code block above, the second to last boolean value is the argument called useDefaultDisambiguation. Again, setting this to true uses the default Virtual Earth disambiguation box. The code above should pop a disambiguation box with a list of options.

"But wait," you say in your leather pants and best Zoolander accent. "My users are super smart and sexy. They would be insulted to be questioned by a simple tool such as this computer. Remove that small boxy thing from my sight."

That, my friend, is what we like to call customization. Another big word. That's right. Disambiguation customization. How is my brain so big?

If your users are too smart and sexy for disambiguation, you can set up Virtual Earth to just use the first (what it considers the "best") option from a list of disambiguated locations. In other words, if you typed in McChord, Virtual Earth would guess that you might mean McChord AFB and take you straight there.

Giving you the option to show or hide the disambiguation box allows you to customize the experience to your users. If you have a savvy user base you can probably suppress the dialog box. If you feel that some of your users would be confused or mad if they are brought to the wrong Portland or Bangor, then you will probably want to show them the disambiguation dialog box.

This post is getting long, so I'm going to save custom disambiguation for the next post. Until then, happy coding!

What the Heck is JSON!?!

That was my question when I first came across JSON. What the heck is JSON, and why didn't I know it?

The quick definition is that JSON stands for JavaScript Object Notation. Of course, that doesn't really tell you much. Now you know what JSON stands for, but what does it really mean?

Come on, man, tell us. What does it mean?

The bottom line is that JSON is a lightweight data-interchange format. In English, that means that JSON is an simple and elegant method of moving data from one point to another.

Sound familiar? Are all you XML enthusiasts standing up, pumping your fists and screaming "Mother of God! My power....my power...it's slipping away. What's wrong with this world? Dear God, what's wrong with this world..."?

Well, sit down and take a deep breath. JSON isn't going to replace XML. JSON isn't going to go away, either.

JSON's strength is in it's simplicity. It is essentially either an unordered set of name/value pairs, or it is an ordered collection of values. That's it. Nothing more. The JSON clan claims that this is set in stone. There will never be anything more. No schema. No comments. No headache. Just simple data that you can move from point a to point b.

Ah, simplicity, I love you so....

I hear you. You want me to stop the yapping and show JSON in action. Well, here you go. We're going to use some code from a VE implementation. The code below is a server-side code snippet for getting some search results from MapPoint. This data will be consumed on the client so our job is to convert the data to JSON and send it upstream as a string. Ready? Okay!

/*...remember, this is inside a method on the server...most likely in a web service or a library called by the web service*/
FindResults fss = this.findService.FindAddress(fas);
JavaScriptSerializer s = new JavaScriptSerializer();
string json = s.Serialize(fss);
return json.ToString();

Whew! That JSON sure is hard work! The key is using the JavaScriptSerializer. That bad boy takes my collection of results objects and serializes it into a JSON collection of objects. Bing, bang, boom. Done.

Now let's see how we consume it on the client.

function WebMethodCallback(result, eventArgs)
{
var data;

try
{
data = eval('(' + result + ')');
var numberFound = data.NumberFound;

}
catch(e)
{
//handle this exception
}
}

Again, that's it! We eval the string into an object we called data. From that point forward, data is used just like any other object. Notice on the next line we set an local variable to a property off of the data object. Shazam! JSON in action, baby.

Find a Location with Virtual Earth 6.0

A working map in Virtual Earth 6.0 is great, but what is really handy is having a map load with a specific area. This can be a state, a country, a city, whatever. It can be a location you have set as a default starting point, or a location supplied by a user.

For today, we'll just use a static starting location.

Use the code we created yesterday. We'll just modify it slightly so our map doesn't default to the whole of the United States.

Step 1
First, find the line of Javascript code that looks like this:

map.LoadMap();

We're going to change this line to load a specific point on the map.

Step 2
Next, we're going to create a new Virtual Earth object called the VELatLong object. This is one that you will use a lot in your Virtual Earth development. This object represents a position on the map - a latitude and longitude.

Since we're just creating a static starting location for our map, we're going to hard code our lat/long location. To do so, on the line just before map.LoadMap(), we create a new VELatLong object and pass in the latitude and longitude in the constructor, like this:

var centerPosition = new VELatLong(47.49319671735114,-122.21654891967773);

Step 3
Next, we're going to use this VELatLong object and pass it into our LoadMap method to set our starting location.

map.LoadMap(centerPosition);

Go ahead and compile and browse to your page. You should see the map load with a new location. But there is still a problem. We're too far away to see anything of value.

Step 4
Finally, we're going to set a default zoom level. The zoom levels are integers ranging from 1 to 19, with 19 being fully zoomed in. The default is 4. Let's get up close and personal, and set a zoom level of 13.

map.LoadMap(centerPosition,13);

That should do it. Compile and browse and you should be looking at Renton Airport.

How To Show a Map in Virtual Earth 6.0

Displaying a map using Virtual Earth 6.0 is a snap. In four short steps, you can have a fully functional, dynamic map on your web site!

Step 1.
First, we need to add a link to the Javascript that drives Virtual Earth. VE is a client-side application, which means it needs Javascript to run. If you have Javascript-disabled browsers in your user pool, you'll be out of luck.

Here's the link you'll need for the latest version of Virtual Earth:

<script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6"></script>

Notice the ?v=6 appended to the end of the url. That indicates that you want to use version 6 of Virtual Earth.

You'll need this Javascript referenced and available on each page that you want the mapping functionality.

Step 2.
Next, you'll need to add a div to represent your map, like this:

<div id="myMap" style="z-index:100;position:relative; width:413px; height:327px; top:0px; left:0px; border-style:solid; border-width:1px; border-color:#C2C2C2;"></div>

Be sure this is inside of your form tags. You can style it anyway that you'd like. You can also call it anything that you'd like. I've called mine myMap. We'll use that ID in upcoming Javascript calls.

Step 3.
Next, we need to add a script block with a couple of short functions to initialize and set up the map. I've cryptically called these InitializeMap() and SetupMap(), as follows:

<script language="javascript" type="text/javascript">
//be sure this is outside the function block so you can reference it later.
var map = null;

function InitializeMap()
{
//pass in the ID of your div here
map = new VEMap('myMap');

//we need to give the map time to load before we use it...
setTimeout('SetupMap(); ', 1000);
}

function SetupMap()
{
try
{
map.LoadMap();
}
catch(e)
{
alert(e.message);
}
}
</script>

Step 4.
This is your last step. Here you need to get things kicked off. To do so, add a body.onLoad() method to your body element to fire off the InitializeMap() function, like this:

<body onload="InitializeMap()">

That's it! Compile your application and browse to your page. You should now have a map that allows panning and zooming. We'll discuss other things you can do with this map in later posts.