MGB Map Js Component overview
The MGB Map Js Component enables developers to easily consume the map related operations of the MGB platform from within their web applications. The following operations can be accomplished with the help of the MGB Js Component:
- display MGB profiles on a map.
- provide the means to implement edit/update/delete functionalities for all the MGB POIs (points of interest) displayed on the map
- perform search operations inside the MGB profiles displayed on the map
- display users’ POI bookmarks
- style the way POIs are displayed on the map using CSS
The MGB Js Component will handle behind the scenes many of the complexities related to displaying MGB data on maps, like geo paging (which is loading and displaying POIs only from the current map view, that will allow the map to still work even with very big profiles) and cross domain Ajax.
The MGB Js Component is built to deliver the maximum amount of flexibility and customization. However it is intended to be used only by developers or by anybody with moderate to advanced technical knowledge. If you are not such a person or if you simply want a much easier way to integrate a MGB map on your site, you should check the MGB Embedded Map.
I remember that in the old days, Microsoft Visual C++ 6 used to display tips at startup and one of the most interesting of them was: We use it before you do! Visual C++ was developed using Visual C++. This is also the case with the MGB Js Component. While we are making it available for developers to ease their work of consuming map related MGB functionalities, we are already using the same component internally for many of our existing projects like the GeoMarks Facebook application or the MGB Embedded Map.
External dependencies
The MGB Js Component is only responsible with displaying and handling MGB related data on a map. The map itself is an external dependency. At the moment only Bing Maps are supported as a map provider. The reference to the Bing Maps Js file must be made before the one to the MGB Js Component.
Also, the MGB Js Component is dependent on the jQuery library. In order to avoid conflicts with existent client side code, the MGB Js Component does not automatically load jQuery, instead you would have to do that. This should not be a problem since many current days sites already include jQuery. In the MGB Js Component we do not reference the $ variable, so it is safe to jQuery.noConflict().
We are using only a limited set of jQuery functionalities and you should be safe with any of its latest versions, however we have only tested for versions higher than 1.3.2.
If you need to use the XSLT capabilities of the MGB Js Component you will also need to include the jQuery Transform plugin in your page.
You can download Transform from this address: http://plugins.jquery.com/project/Transform.
If you are not using the XSLT capabilities of the MGB Js Component you do not need to reference the Transform plugin.
For more details on how to set the external dependencies, please check the Samples section.
XSLT support for POI popups
The POI popups are displayed every time a user moves its mouse over a POI on the map. There are two ways of customizing the look and feel of POI popups:
- By using CSS (you can get the default POI popup style at http://mgbmap.mygeobook.com/MapJs/css/default/mgbMap.css). Each page that uses the MGB Js Component must include a POI popup CSS. If the default style suits the needs of the project, then only the default style needs to be included. If the style of the POI popup needs to be customized, there are two possible approaches for that: include the default style and after that override the style elements you want to replace or provide a completely new CSS file.
CSS customization would probably suit most of the customization needs related to style. If needed, also from CSS you can hide different elements of the popup that you do not want to be displayed. XSLT customization is a bit more difficult to implement, but it offers additional flexibility since it also allows to completely change the HTML structure of the POI popup.
As stated in the External dependencies section, you need to reference the jQuery Transform plugin in order to use the XSLT capabilities of the MGB Js Component.
By default, the MGB Js Component, will bring the description of each POI as HTML from the server and render it inside the popup. There are two methods that allow you to override this behavior: setPoiDescriptionXslt and setPoiDescriptionXsltUrl. You can call any of the two methods to set the XSLT document that will be used to format the POI popup, which will now be retrieved from the server as HTML.
A sample of an XSLT transformation that creates a popup identical with the default one can be found here: http://mgbmap.mygeobook.com/MapJs/xslt/default/POI popup description.xslt.
Inside the sample XSLT, please note the XSLT parameters zoomFunc, deleteFunc, detailsFunc, editFunc that are defined at the beginning of the document. You will need to declare these parameters as well at the beginning of your XSLT stylesheets, because their values will be supplied by the MGB Js Component during the transformation. You can get more info about the functionality provided by those parameters, by checking the description of the setPoiDetailsFunc method.
Below is a sample of an XML document that is returned by the server when requesting the details of a POI (this XML will be transformed with the supplied XSLT in order to create the popup HTML):
<SerializablePoiDetails>
<Altitude>0</Altitude>
<AverageRating>
<AverageRating>-1</AverageRating>
<NumberOfRatings>0</NumberOfRatings>
</AverageRating>
<Description>This poi is created just as a sample. This poi is created just as a sample. This poi is created just as a sample. This poi is created just as a sample. This poi is created just as a sample. This poi is created just as a sample. This poi is created just as a sample. This poi is created just as a sample. This poi is created just as a sample.</Description>
<Email>test@test.com</Email>
<FaxNumber>f1234567890</FaxNumber>
<Icon i:nil="true"/>
<Id>922</Id>
<Latitude>45</Latitude>
<Longitude>26</Longitude>
<MailingAddress>bla bla street, no 10</MailingAddress>
<Name>My Sample app test</Name>
<PhoneNumber>1234567890</PhoneNumber>
<PoiImages>
<SerializablePoiImage>
<Description i:nil="true"/>
<ImageLink>http://resources.mygeobook.com/geomark/image/8a230f7ec0e44ff5ab353bd48b4e75d1.jpg</ImageLink>
<ThumbnailLink>http://resources.mygeobook.com/geomark/image/8a230f7ec0e44ff5ab353bd48b4e75d1_thu.jpg</ThumbnailLink>
<Title i:nil="true"/>
</SerializablePoiImage>
<SerializablePoiImage>
<Description i:nil="true"/>
<ImageLink>http://resources.mygeobook.com/geomark/image/71a78fdd12f64acd8fcfb04254761327.jpg</ImageLink>
<ThumbnailLink>http://resources.mygeobook.com/geomark/image/71a78fdd12f64acd8fcfb04254761327_thu.jpg</ThumbnailLink>
<Title i:nil="true"/>
</SerializablePoiImage>
</PoiImages>
<ProfileId>1022</ProfileId>
<Thumbnail>http://resources.mygeobook.com/profile/thumbnail/c12aa9dcb4fe4e6dac8c52fc63525132.jpg</Thumbnail>
<WebSite>Bout.www.google.com</WebSite>
</SerializablePoiDetails>
Samples
Premier League Stadiums
This is a very simple sample that demonstrates how a MGB profile can be displayed on a map. Please check the comments inside the code.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Premier League Stadiums</title>
<!-- default style for the MGB Map elements. override to customize the style -->
<link type="text/css" href="http://mgbmap.mygeobook.com/MapJs/css/default/mgbMap.css" rel="stylesheet"/>
<!-- include the Bing Maps js. This is an external dependency for the MGB Js Component and needs to be loaded before it -->
<script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2"></script>
<!-- include jQuery from the MS CDN. This is an external dependency for the MGB Js Component and needs to be loaded before it -->
<script type="text/javascript" src="http://ajax.microsoft.com/ajax/jquery/jquery-1.4.2.min.js"></script>
<!—include the MGB Js Component -->
<script type="text/javascript" src="http://mgbmap.mygeobook.com/MapJs/MgbMapJsComponent.js"></script>
<script type="text/javascript">
/* the Bing Maps object */
var map = null;
/* will be used to access the MGB Js Component */
var mgbService = null;
jQuery(document).ready(function() {
/* load the bing map */
map = new VEMap('divMap');
map.LoadMap();
/* load the MgbService */
mgbService = new MgbService(map, 'Microsoft');
/* add the "Premier League Stadiums" profile to the map (the profile id is used) */
mgbService.showProfile(1184);
});
</script>
</head>
<body>
<h1>Premier League Stadiums</h1>
<div id='divMap' style="position:relative; width:800px; height:500px;"></div>
</body>
</html>
Reference
MgbService class
The main class of the MGB Js Component providing access to all of the map related MGB functionalities from client side javascript. Check the Samples section for some quick demonstrations on how to use this class.
Constructor
Parameters:
mapObject <object, required> - an instance of a map class. For this version, a instance of a VEMap class (Bing Maps).
mapSupplier <string, required> - a string telling the map supplier for this instance of MgbService. The only value allowed by this version is “Microsoft”.
Methods
showProfile
Show a profile on the map.
Parameters:
profileId <int, required> - the id of the profile to show on the map.
hideProfile
Removes a profile from the map.
Parameters:
profileId <int, required> - the id of the profile to remove form the map.
setMapSessionKey
Attaches a MGB Map Service session key to the current instance allowing it to make calls on behalf of an authenticated user. The MgbService class does not necessarily require this parameter, since it can work in two different modes: public and secure.
In the public mode you can access anything that is public. For example you can display on the map any profile that has been marked as public (“List in GeoMarks directory” from the GeoMarks facebook application) or perform a search inside any such profile.
In secure mode, you can access any public MGB resource, plus any private resource accessible to the user for which the session key has been created.
Check the security/createSessionForMapService method from the MGB Rest Service reference for details on how to obtain a session key for an authenticated user.
Parameters:
sessionKey <string, required> - the MGB Map Service session key associated to the current authenticated user
getMapSessionKey
Gets the MGB Map Service session key assigned to this instance.
setPoiEditFunc
The MGB Js Component handles the displaying of a popup description each time a user moves its mouse cursor over a point of interest on the map. The developer can set a few actions that would be displayed as links at the end of the popup description. The actions are javascript functions that would be called when the link is clicked. Every time such a function is called it would be called with a single parameter representing the id of the point of interest for which the user clicked the link.
Use this method to display an Edit link at the end of the popup description. By default, if this method is never called, the Edit link will not be set.
Parameters:
handler <function, required> - a javascript function that would be called when the user clicks the Edit link at the end of the popup description of a point of interest. The function must receive one parameter representing the point of interest id. If the handler parameter is null, the Edit link will not be displayed.
getPoiEditFunc
Gets the point of interest Edit handler that was set for this class instance.
setPoiDeleteFunc
The MGB Js Component handles the displaying of a popup description each time a user moves its mouse cursor over a point of interest on the map. The developer can set a few actions that would be displayed as links at the end of the popup description. The actions are javascript functions that would be called when the link is clicked. Every time such a function is called it would be called with a single parameter representing the id of the point of interest for which the user clicked the link.
Use this method to display an Delete link at the end of the popup description. By default, if this method is never called, the Delete link will not be set.
Parameters:
handler <function, required> - a javascript function that would be called when the user clicks the Delete link at the end of the popup description of a point of interest. The function must receive one parameter representing the point of interest id. If the handler parameter is null, the Delete link will not be displayed.
getPoiDeleteFunc
Gets the point of interest Delete handler that was set for this class instance.
setPoiDetailsFunc
The MGB Js Component handles the displaying of a popup description each time a user moves its mouse cursor over a point of interest on the map. The developer can set a few actions that would be displayed as links at the end of the popup description. The actions are javascript functions that would be called when the link is clicked. Every time such a function is called it would be called with a single parameter representing the id of the point of interest for which the user clicked the link.
Use this method to display an Details link at the end of the popup description. By default, if this method is never called, the Details link will not be set.
Parameters:
handler <function, required> - a javascript function that would be called when the user clicks the Details link at the end of the popup description of a point of interest. The function must receive one parameter representing the point of interest id. If the handler parameter is null, the Details link will not be displayed.
getPoiDetailsFunc Gets the point of interest Details handler that was set for this class instance.
setPoiRatingsFunc
The MGB Js Component handles the displaying of a popup description each time a user moves its mouse cursor over a point of interest on the map. The developer can set a few actions that would be displayed as links at the end of the popup description. The actions are javascript functions that would be called when the link is clicked. Every time such a function is called it would be called with a single parameter representing the id of the point of interest for which the user clicked the link.
Use this method to display an Ratings link at the end of the popup description. By default, if this method is never called, the Ratings link will not be set.
Parameters:
handler <function, required> - a javascript function that would be called when the user clicks the Ratings link at the end of the popup description of a point of interest. The function must receive one parameter representing the point of interest id. If the handler parameter is null, the Ratings link will not be displayed.
getPoiRatingsFunc
Gets the point of interest Ratings handler that was set for this class instance.
attachEvent
Attaches a handler to an MGB Js Component event. You can check the events section of this class for more details.
Parameters:
eventName <string, required> - the name of the event
handler <function, required> - a handler for the event. Check the documentation for each event to see the parameters that each of them is transmitting to the handler.
detachEvent
Detaches a handler to an MGB Js Component event. You can check the events section of this class for more details.
Parameters:
eventName <string, required> - the name of the event
handler <function, required> - a handler for the event. Check the documentation for each event to see the parameters that each of them is transmitting to the handler.
getProfiles
Gets an array with all the ids of the displayed profiles.
getDisplayedProfilesCount
Gets the count of all the displayed profiles.
refreshCrtArea
Forces a refresh on all the points of interest displayed in the current map view.
setAutoZoomAndCenter
Enables or disables the auto zoom and center functionality. When enabled, after displaying a profile to the map, the map would be automatically zoomed and centered in such a way that all of the profiles points of interest are visible (if the profile has a reasonable small number of points of interest).
Parameters:
Enable <bool, required> - true to enable the auto zoom and center and false to disable it.
getAutoZoomAndCenter
Gets the auto zoom and center setting for this class instance.
setPoiTitlesZoomLevel
Set the zoom level from which titles will be shown under the icons for the displayed points of interest. By default, titles are never displayed.
The zoom values that this method accepts are the ones for underlying map used to display the points of interest. For example, for Bing Maps allowed values are between 1 and 19. Set a zoom value smaller than the minimum allowed value and zoom title will never be displayed.
You will have to take into account that displaying titles might only make sense on high zoom levels, when points of interest are far away one from another. Otherwise the titles might overlap and create a not very nice visual effect.
Parameters:
zoom <int, required> - the zoom value from which to start displaying point of interest titles.
getPoiTitlesZoomLevel
Get the zoom value from which titles are being displayed under the point of interest icons on the map.
centerOnPoi
Centers the map on a given point of interest. On Bing Maps, after the operation, the zoom level will be set to 11.
Parameters:
poiId <int, required> - the id of the point of interest on which to center the map.
zoomToLocation
Centers the map on the given location. On Bing Maps, after the operation, the zoom level will be set to 11.
Parameters:
lat – the latitude of the location on which to center
lon – the longitude of the location on which to center
zoomAndCenterToDefault
Zooms and centers map to a default location in the North of the Atlantic Ocean, so that only blue water is visible on the map. You might use this function if you need to display a neutral zone on the map (no country visible).
invalidatePoiDescription
Information displayed on the popup description of each point of interest are retrieved from the MGB servers using Ajax and then cached, so that if the user goes with mouse curser over the same point of interest no more round trips to the server will be made. If things have changed in a point’s of interest description and you want the popup description to reflect the latest changes, you must destroy the description cache by calling this method.
Parameters:
poiId <int, required> - the id of the point of interest for which to invalidate the description cache.
searchInCurrentProfiles
Performs a full text search (google like) in the in all the points of interest from the currently displayed profiles. After calling this method, the MGB Js Component will enter in search display mode and will only display the points of interest that match the search criteria. Call the clearSearch method in order to exit the search display mode and start displaying all points of interest from profiles again.
Parameters:
searchString <string, required> - the search string that will be used when performing the full text search.
clearSearch
If the MGB Js Component is in search display mode, calling this method brings it back to displaying all points of interest in profiles mode.
showPoiBookmarks
Call this method to hide the currently displayed points of interest from the map and instead display the current’s user bookmarked points of interest. You set a current user by providing its Map Service session key to the setMapSessionKey method.
After calling the showPoiBookmarks method, the MGB Js Component enters in bookmarks display mode. To bring it back to displaying all the points of interest from the current profiles, you must call the hidePoiBookmarks method.
hidePoiBookmarks If the MGB Js Component is in search bookmarks mode, calling this method brings it back to displaying all points of interest in profiles mode.
showProfilesLayers
If the MGB Js Component is in search display mode or in bookmarks display mode, calling this method brings it back to displaying all points of interest in profiles mode.
getPoiDescriptionXsltUrl
Gets the url of the XSLT document that is going to be used in order to generate the POI popup descriptions.
setPoiDescriptionXsltUrl
Sets the url of the XSLT document that is going to be used in order to generate the POI popup description. The url must be in the same domain as the url of the page hosting the MGB Js Component, in order to avoid cross domain AJAX errors (AJAX is used to retrieve the content of the document on the client side).
If the address of the XSLT is not in the same domain the url of the page hosting the MGB Js Component, there are two possible workarounds: create a proxy for the XSLT file on the same domain as the hosting page or use the setPoiDescriptionXslt method, to set the XSLT document as a string.
getPoiDescriptionXslt
Gets a string representing the XSLT document that is going to be used in order to generate the POI popup descriptions.
setPoiDescriptionXslt
Sets the XSLT document that is going to be used in order to generate the POI popup descriptions. The XSLT document is set as a string.
For that you would need to either declare the XSLT document as a Javascript string, or more conveniently to store that document inside a HTML tag (a hidden textarea element for example) and load it in a Javascript variable from there.
Events
There are two methods that can be used in order to consume MgbService events: the attachEvent method to attach a handler to an event and detachEvent to detach a handler from an event. Both methods take the same parameters:
eventName <string, required> - the name of the event
handler <function, required> - a handler for the event. Check the documentation for each event to see the parameters that each of them is transmitting to the handler.
onprofileload
This event is fired when a profile is being loaded.
Parameters:
id – the id of the profile that has been loaded
onprofilehide
This event is fired when a profile is being hidden.
Parameters:
id – the id of the profile that has been hidden
onsearchloaded
This event is fired when the search layer is being loaded.
Parameters:
mgbMapLayerInfo – a instance of the MgbMapLayerInfo class
onbookmarksloaded
This event is fired when the bookmarks layer is being loaded.
Parameters:
mgbMapLayerInfo – a instance of the MgbMapLayerInfo class
onbeforeaddpoi
This event is fired when a POI is added to the map. You can use PoiAddArgs parameter to cancel adding certain POIs.
Parameters:
addPoiArgs – an instance of the AddPoiArgs class
MgbMapLayerInfo
Data class that holds information on an Mgb Layer displayed on a map.
Fields
totalItemsOnMap <int>
The total number of items on a given map. For example, if the map represents a search result, this number would represent the total search matches from the entire map.
totalItemsDisplayed <int>
The total number of items displayed. For each map, MGB will only bring the points in the current map view so chances are that this number is smaller than the totalItemsOnMap field. Furthermore, MGB uses a threshold for the max number of items it would return in one call, this being another factor why this number might be smaller than totalItemsOnMap.
AddPoiArgs
Represents the argument passed to the event handler of an onbeforeaddpoi event.
Fields
poiId <int>
The id of the POI being added.
profileId <int>
The profile to which the added POI belongs.
cancelAdd <bool>
Set to true to cancel the poi adding.