Introduction
The purpose of this document is to provide a quick startup guide for ASP .Net developers who want to build applications on the MGB platform. It is being said that sometimes an image tells more than a thousand words. Following the same principle, in programming a good sample sometimes tells more than an entire book and that is why I decided to build this tutorial around such an example.
The example project can be downloaded here: MgbSimpleAspDemo .
In order to be able to run the demo you will need an application key and secret which you can obtain via the contact form . The obtained keys will have to be set in web.config file, in the appSettings section.
Additional documentation
This document will only give you a quick startup guide on consuming the MGB platform. It will not cover all the information you need when building a complex production application. For that you will have to check the following documentations:
MGB frequently used terms
The key term for the MGB platform is geomark. Anything that has a representation on map can be a geomark. For example stores, stadiums, restaurants or simply places somebody has visited can be geomarks. A geomark has properties like location, title, description, email, phone number, pictures etc.
Geomarks are grouped in maps. A map is just a collection of geomarks. Any geomark can only exist inside a map, so for example if we are to create geomarks for all the Premier League stadiums we would have to first create a PremierLegue map (you can view an already built map with Premier League stadiums here: http://mgbembeddedmap.mygeobook.com/Map.aspx?profileId=1184).
Maps can be public, meaning that they can be accessed by anybody, or private, which means that they will only be accessed by the people the map creator chooses.
Initially, when we started the work on the MGB platform, we used the PointOfInterest (or POI) for describing geomarks and Profile for describing maps. That is the reason why, in technical documentation and in the API method names you will only see the initial terms.
If you want to get accustomed with the MGB platform from a user’s perspective, a good starting point is our Facebook application: http://apps.facebook.com/geomarksproduction .
The structure of the MGB platform
The MGB platform was built to ease the job of creating and integrating map related data. At its core is the Rest Service which offers the means through which you can access any functionality provided by the platform. As its name already says, the Rest Service is built on a HTTP Rest architecture, with the method name as part as the URL and the parameters set inside the body of a POST message. You will be able to find all the details of the anatomy of a MGB Rest Service method in the “MGB Rest Service Consumer's Guide”.
For the purpose of this document all you need to know about the Rest Service is that it exposes a flat interface with methods like getPoi or updatePoi, it can be consumed from any platform and it provides secure access to the MGB platform.
Another important component in the platform is the MGB Js Component which has been built to ease consuming any map related operations from the client side of web applications.
At the moment, the Js component can only be used together with a map from Bing Maps and it encapsulates operations like displaying points of interest on a map, searching points of interest, getting and displaying their details, managing large amounts of data through pagination and managing cross domain concerns related to calling the MGB Rest Service from the browser side of a web application. You can find a complete set of details on the MGB Js Component in the “MGB Js Component documentation”.
MGB ASP .Net Wrapper
If you explore the MgbSimpleAspDemo sample solution you will see that it contains two projects. The first of them is called MGB_Wrapper_ASP.NET and it is .Net client for the Mgb Rest service.
We are not yet providing any built Rest Service client for any platform, but if you need to create such a client for the .Net platform, the MGB_Wrapper_ASP.NET project should be a good starting point. It already implements many of the service’s methods and provides the basis on which implementing the other should be strait forward.
The main class of the project from a consumer’s point of view is MgbPublicApiManager. Inside it you will find already implemented methods from the MGB Rest Service in the Rest API methods and Resources API methods code regions.
MgbSimpleAspDemo project
The demo project displays the MGB Profile with id 1184 (representing the Premier League stadiums profile) on a map and for each point of interest, when clicking on the details link from the popup description, a modal window is displayed with a more complete set of details. Below is a screenshot from the demo:
I will now analyze all the key aspects from the code and I will start with the Default.aspx page, that is the main page of the application.
Managing all the client side aspects of populating a map with elements from the MGB platform is done by the MGB Js Component.
In order to load that component you will have to reference the location of its javascript file:
<script type="text/javascript" src="http://mgbmap.mygeobook.com/MapJs/MgbMapJsComponent.js" ></script>
The MGB Js Component has a few external references that need to be loaded before it. The first one is the Bing Maps javascript file, which you will have to reference anyway in order to display the map on the page. The second reference is jQuery, which is one of the most popular javascript libraries on the web these days (check the http://jquery.com/ site for more details).
jQuery is free and open source and it is so popular that even Microsoft and google distribute it using their CDNs. In this demo, I am loading jQuery from Microsoft’s CDN:
<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2"></script>
<script type="text/javascript" src="http://ajax.microsoft.com/ajax/jQuery/jquery-1.4.2.min.js"></script>
In the above screenshot, you can see the popup that is displayed when go with the mouse cursor over a point of interest on the map. The popup is entirely customizable using CSS.
There are two different techniques for doing the customization. The fastest and probably the best suited for most needs, is to load the default CSS and after that override only the sections that you want to modify. The second one is more radical and involves creating a new CSS file and replacing the default one with it.
Below are the lines of code that load the default CSS and override some of its properties (in this example we override the property that hides by default the address line from the popup description):
<link type="text/css" href="http://mgbmap.mygeobook.com/MapJs/css/default/mgbMap.css" rel="stylesheet" />
<style type="text/css">
/* MGB style overrides */
#mgbPoiPopupPropertyAddress {
display: block;
}
The default CSS file can be used as a reference of all the CSS customizable classes and ids.
The MGB Js Component is only responsible with bringing the MGB functionality on the map and not with building the map itself. The map needs to be created separately by the developer, which can customize it anyway he wants (the developer is free to choose the map location on the page, its size and style).
The following lines create the Bing on the Default.aspx page:
map = new VEMap('divMap');
map.LoadMap();
The MgbService is the main class from the MGB Js Component. When created, it must receive a reference to the Bing Map object on which it will render the MGB (the ‘Microsoft’ parameter tells that a Bing Map is going to be used, which are the only ones supported at the moment):
mgbService = new MgbService(map, 'Microsoft');
Loading the Premier League stadiums profiles on the map is done with the following line of code:
mgbService.showProfile(profileId);
The MgbService class allows defining a few actions on the point of interest popup and one of them is the details action:
mgbService.setPoiDetailsFunc('on_gmDetails');
By implementing the above action, a Details link will be present on the point of interest popup description. When clicked, the function supplied as parameter is going to be called. The function will receive the id of the point of interest as a single parameter. The on_gmDetails handler function will load the GeoMarkPopupDetails.aspx page using AJAX and display it in a popup over the map.
Until now we have only focused on client side code and the MGB Js Component. In the code behind of the GeoMarkPopupDetails.aspx page we will also get the chance to see some server side code consuming the MGB Rest Service.
From the access point of view there are two kinds of methods in the Rest Service: anonymous methods and methods that require authentication. You can find a list with all the anonymous methods in the Rest service anonymous methods list document.
This demo only calls the anonymous getPoiInfo method. If you need to call methods that require authentication you will need a session for that, which, depending on your application type, can be created with one of the following Rest Service methods: CreateSessionForExternalWebApp or CreateSessionForExternalDistributedApp.
In GeoMarkPopupDetails.aspx.cs you can see how you instantiate the MgbPublicApiManager class using you app key, app secret and Rest Service URL location. After that the call to the getPoiInfo method is strait forward:
PointOfInterest poi = api.GetPoiInfo(poiId);
Please keep in mind that this was just a quick startup guide on the MGB platform. For starting development on production applications based on the MGB platform please also consider all the other documentation described in the Additional Documentation section.