ThinkGeo.com    |     Blog    |     Wiki    |     Support

Client API Documentation for Map Suite Web Edition

This topic discusses the client API functions used by JavaScript in Map Suite Web Edition 4.0 and higher. You can use these functions by Map.ClientID. For example, if your map control’s clientID on the web page is “Map1”, use these functions by calling Map1.GetMapParser(); in JavaScript.

This topic discusses the client API functions used by JavaScript in Map Suite Web Edition 3.0 and higher.


Contents:





Overview


Use the following functions by Map.ClientID. For example, if your map control’s clientId on the web page is “Map1”, use these functions by calling “Map1.GetMapParser();” in JavaScript.





GetOpenLayersMap()



Description:

Returns OpenLayers.Map object used by current map control. You can call map’s function directly by using it.



Return type: {OpenLayers.Map}



Sample Code:


var map = Map1.GetOpenLayersMap();



GetExtent()



Description:

Returns an OpenLayers.Bounds object which represents the longitude/latitude bounds of the current viewport. If no baseOverlay is set, returns null.



Return type: {OpenLayers.Bounds}



Sample Code:


var extent = Map1.GetExtent();



ZoomIn()



Description:

Zoom in the map by one zoom level.



Sample Code:


Map1.ZoomIn();


Sample Online:

websamples.thinkgeo.com/Samp…ndOut.aspx





ZoomOut()



Description:

Zoom out the map by one zoom level.



Sample Code:


Map1.ZoomOut();


Sample Online:

websamples.thinkgeo.com/Samp…ndOut.aspx





ZoomToExtent(extent)



Description:

Zoom to the specified extent and re-center.



Parameters:

extent: {OpenLayers.Bounds} A fixed extent to zoom to.



Sample Code:


var extent = new OpenLayers.Bounds(30, -95, 78, -60);
Map1.ZoomToExtent(extent);




GetCenter()



Description:

Get an OpenLayers.LonLat object which represents the longitude/latitude of the center of the current viewPort of the map.



Return type: {OpenLayers.LonLat} current center longitude and latitude.



Sample Code:


var center = Map1.GetCenter();


Sample Online:

websamples.thinkgeo.com/Samp…heMap.aspx





SetCenter(longitude, latitude)



Description:

Allow users to re-center the map to the specified longitude & latitude directly.



Parameters:

longitude: {float}   The x-axis coordinate in map units

latitude: {float}      The y-axis coordinate in map units



Sample Code:


var lonlat = Map1.GetCenter();
var newLongitude = lonlat.lon + 10;
var newLatitude = lonlat.lat + 10;
Map1.SetCenter(newLongitude, newLatitude);


Sample Online:

websamples.thinkgeo.com/Samp…tMenu.aspx





PanByScreenPixel(x, y)



Description:

Pan the map by a value of screen pixels.



Parameters:

x: {Integer}    Screen pixel

y: {Integer}    Screen pixel



Sample Code:


Map1.PanByScreenPixel (100, 100)



PanToWorldCoordinate(longitude, latitude)



Description:

Pans to a new longitude & latitude. If the new longitude & latitude is in the current extent, the map will slide smoothly.



This function is similar to SetCenter(longitude, latitude), but the effect is different. The SetCenter(longitude, latitude) function jumps to the target instantly, while the PanToWorldCoordinate(longitude, latitude) function pans smoothly over to the target if the target is in the current extent.



Parameters:

longitude: {float}   The x-axis coordinate in map units

latitude: {float}      The y-axis coordinate in map units



Sample Code:


var lonlat = Map1.GetCenter();
var newLongitude = lonlat.lon + 10;
var newLatitude = lonlat.lat + 10;
Map1.PanToWorldCoordinate(newLongitude, newLatitude);


Sample Online:

websamples.thinkgeo.com/Samp…heMap.aspx





ZoomToPreviousExtent()



Description:

Restore to previous extent.



Sample Code:


Map1.ZoomToPrevousExtent();


Sample Online:

websamples.thinkgeo.com/Samp…story.aspx





ZoomToNextExtent()



Description:

Restore to the next extent.



Sample Code:


Map1.ZoomToNextExtent();


Sample Online:

websamples.thinkgeo.com/Samp…story.aspx





ToggleExtent()



Description:

Toggle the map between the previous and the next extent.



Sample Code:


Map1.ToggleExtent();


Sample Online:

websamples.thinkgeo.com/Samp…story.aspx





SetDrawMode(drawMode)



Description:

Set the map mode by the drawMode parameter. The map mode can be set as “Point”, “Line”, “Polygon”, “Rectangle”, “Square”, “Circle”, “Ellipse”, “Normal” and “Modify”. In the “Normal” mode, the map is in its normal state. In the “Modify” mode, the shapes on the map can be edited. In other modes, you can draw the specified shapes on the map.



Parameters:

“DrawMode”: {string} can be specified as “Point”, “Line”, “Polygon”, “Rectangle”, “Square”, “Circle”, “Ellipse”, “Normal”, “Modify”.



Sample Code:


Map1.SetDrawMode(“Normal”);
Map1.SetDrawMode(“Modify”);
Map1.SetDrawMode(“Point”);
Map1.SetDrawMode(“Line”);
Map1.SetDrawMode(“Polygon”);
Map1.SetDrawMode(“Rectangle”);
Map1.SetDrawMode(“Square”);
Map1.SetDrawMode(“Circle”);
Map1.SetDrawMode(“Ellipse”);


Sample Online:

websamples.thinkgeo.com/Samp…hapes.aspx





ClearFeatures()



Description:

Clear all features drawn on the map.



Sample Code:


Map1.ClearFeatures();



CancelLatestFeature()



Description:

Delete the latest drawn feature.



Sample Code:


Map1. CancelLatestFeature();


Sample Online:

websamples.thinkgeo.com/Samp…hapes.aspx





PrintMap()



Description:

Print the current map.



Sample Code:


Map1.PrintMap();



GetCurrentBaseLayer()



Description:

Allow users to get the map’s current base layer.



Return Type: {OpenLayers.Layer}



Sample Code:


Map1.GetCurrentBaseLayer();



SetBaseLayer(layerId)



Description:

Allow users to specify one of the currently-loaded layers as the map’s new base layer.



Parameters:

layerId: {String} An Id of a layer which you added on the map.



Server Code: Focus on the Id parameter in the constructor of the following Overlays.


WmsOverlay wms = new WmsOverlay(“WMS”);
wms.ServerUris.Add(new Uri(“labs.metacarta.com/wms/vmap0”));
wms.Parameters.Add(“layers”, “basic”);
wms.Parameters.Add(“SRS”, “EPSG:900913”);

GoogleOverlay google = new GoogleOverlay(“Google”);
google.GoogleMapType = GoogleMapType.Normal;

YahooOverlay yahoo = new YahooOverlay(“Yahoo”);
yahoo.YahooMapType = YahooMapType.Regular;

VirtualEarthOverlay ve = new VirtualEarthOverlay(“VE”);
ve.VirtualEarthMapType = VirtualEarthMapType.Road;

Map1.CustomOverlays.Add(wms);
Map1.CustomOverlays.Add(google);
Map1.CustomOverlays.Add(yahoo);
Map1.CustomOverlays.Add(ve);



Client Code: Use the following code to set the preset layer as current base layer.


Map1.SetBaseLayer(“WMS”);
Map1.SetBaseLayer(“Google”);
Map1.SetBaseLayer(“Yahoo”);
Map1.SetBaseLayer(“VE”);




SetCurrentBackgroundMapType(backgroundMapType)



Description:

Change current OpenLayers third part layer’s type.

Please reference the Google, Virtual Earth, or Yahoo API you registered on the web page, then find what type of map they support.



For example:

Google supports: G_HYBRID_MAP, G_NORMAL_MAP, G_SATELLITE_MAP, G_PHYSICAL_MAP…

Reference guide to Google’s supported Map Types:

Google Map Attributes



Yahoo supports: YAHOO_MAP_SAT, YAHOO_MAP_REG, YAHOO_MAP_HYB…

Reference guide to Yahoo’s Map Type control:

Using YMapTypeControl to position map types



Virtual Earth supports: VEMapStyle.Road, VEMapStyle.Aerial, VEMapStyle.Hybrid…

Please reference the latest API to get more supported Map Types.



Sample Code:


//If current map layer is Google:
Map1.SetCurrentBackgroundMapType(G_HYBRID_MAP);

//If current map layer is Virtual Earth:
Map1.SetCurrentBackgroundMapType(VEMapStyle.Road);

//If current map layer is Yahoo:
Map1.SetCurrentBackgroundMapType(YAHOO_MAP_SAT);


Sample Online:

websamples.thinkgeo.com/Samp…ooWms.aspx





SetEditSetting(editSettings)



Description:

Set current map edit mode to Reshape|Rotate|Resize|Drag mode.



Parameters:

editSettings: {string} Can be specified as: EditSettings.Reshape, EditSettings.Resize, EditSettings.Rotate, EditSettings.Drag




Sample Code (using only one setting):


Map1.SetEditSetting(EditSettings.Reshape);
Map1.SetEditSetting(EditSettings.Resize);
Map1.SetEditSetting(EditSettings.Rotate);
Map1.SetEditSetting(EditSettings.Drag);


Sample Code (using multiple settings):


Map1.SetEditSetting(EditSettings.Reshape|EditSettings.Resize|EditSettings.Rotate|EditSettings.Drag);



OnMapCreating()



Description:

Call before the map is initialized.



Sample Code:


<script type=“text/JavaScript”>
var OnMapCreating = function(map){
// JavaScript code
}
</script>




OnMapCreated()



Description:

Call after the map is created.



Sample Code:


<script type=“text/JavaScript”>
var OnMapCreated = function(map){
// JavaScript code
}
</script>




How To Use OpenLayers’ API



  1. OpenLayers class document online: dev.openlayers.org/releases/…rs-js.html

  2. How to use it in Map Suite Web Edition:

    In Web Edition, all of OpenLayers’ objects are added to the Map object. Thus, we can use OpenLayers’ class via Map.



    Example: Add a new WmsLayer on the map using JavaScript:


var OnMapCreated = function(map){
var wmsLayer = new OpenLayers.Layer.WMS( “OpenLayers WMS”, “labs.metacarta.com/wms/vmap0”, {layers: ‘basic’});
map.addLayer(wmsLayer);
}


about the SetDrawMode(drawMode) which seems awesome 
 I am wondering 
 after a post , how do I get the data drawn?

Hi, Itay 
  
 If you just want to get the features you have drawn on the client side, I suggest you refer to the "DrawEditShapes" sample in our installed samples which you could find its source code at "Samples\MapShapes\DrawEditShapes.aspx". Once you click the submit button and post the page and you could get the data in the Map1.EditOverlay.Features. 
  
 If you still need other requirements please feel free to let me know. 
  
 Thanks, 
  
 Khalil

Is it possible for me to add more lines of codes to those javascript? 
 For example ZoomIn() 
 I can use the OnExtentChanged event to get content. But it will refresh the page and takes time. We try to use page method (ajax) to achieve this goal. Is this possible? 
  
 Thanks, 
  
 Wilson Jiang

 


Hi Wilson,
Yes, you guys can extend the these functions. Here as following is a demo:
 
<script language="javascript" type="text/javascript">
    ThinkGeo.prototype.yourFunction = function () {
        alert("add custom logic here");
    }
</script>
 
Please make sure adding these functions at the end of the “Body” tag.
Regarding OnExtentChanged event, I don’t think you need to implement it by yourself, you can find the corresponding client event from map’s property “OnClientExtentChanged”. Here is the sample:
 
Map1. OnClientExtentChanged = “clientFunction”;
 
Thanks,
Johnny

How can you use “Map1.ZoomToPrevousExtent();”. Normally you can access Map1 from server side code. In javascript we normally use the following code to get client ID and map. 
 var mapClientID = ‘<%= this.Map1.ClientID %>’; 
  var map = document.getElementById(mapClientID); 
  
 My code in asp is  
 <ThinkGeo:Map ID=“MapSAM” runat=“server” Height=“900” Width=“1200px”/> 
 <asp:Button ID=“Sub” runat=“server” OnClientClick=“MapSAM.ZoomToPrevousExtent();return false;” Text=“Restore to Previous Content” />

 I got “MapSAM undefined” error. I tried to use mapClientID.ZoomToPrevousExtent() or map.ZoomToPrevousExtent(). Neither works. Probably I did not understand the Overview section above. Thanks. Wilson

Wilson,




The code for “ZoomToPreviouseExtent” is ok. Also you can get the source code of ZoomToPrevioursExtent function in “func_GeoResource.axd”by debugging the application.  In that function, we search for the “NavigationHistory” control via mapParser to zoom to previous extent. Can you try the installation sample “NavigateTheMap/NavigationHistory.aspx” to check if there is any difference from yours?




I think there is no problem to get the map clientId, but the code “var map= document.getElementById(mapClientId)” just can get the DIV object which is used to host the map instead of the map object. To get the real map object, please use the code “var map = Map1.GetOpenLayersMap();” instead.


Thanks,

Johnny

 



Hi Thinkgeo, 
  
 Is there any addition to above API since 3.0? We are now into 4.5… 
  
  
 Regards, 
 Anil

 


Hi Anil,
There is nothing change for Client API from 3.0 to 4.5
PS:  Mapsuite WebEdition relys on OpenLayers, so you can use all APIs which provide by OpenLayers, and then we have updated Openlayers since we updated WebEdition to 4.5, that means there are some addition OpenLayers APIs you can use. The detail please refers to:
openlayers.org/
Thanks,
James

Hi,


I just tried to use Map1.GetCurrentExtent() Both were wrong. The correct function was getExtent(), which I found in the OpenLayers docs.



var tgMap = null;
var OnMapCreated = function(map) {
tgMap = map;
tgMap.events.register('moveend', null, mapMoved);
tgMap.events.register('zoomend', null, mapMoved);
}
function mapMoved() {
if (!tgMap) return;
var xt = tgMap.getExtent();
}

Perhaps the docs here needs updating ? Or be removed ?


Using Web Edition 5.5.111.0

 



Hello Lars I, 
  
 Thank you reporting this, we will update this docs. 
  
 We appreciate your help. 
  
 Regards, 
  
 Gary

Hi, 
  
 I’ve begun using the Ajax Controls Toolkit for my projects, as its mix of client-side and server-side implementation is almost perfect for me. 
  
 However, using ACT presents problems with the client-side implementation of Map Suite. There’s no “Map1” variable anymore for client-side operations. 
  
 ACT changes the controls names, which seem to affect your client-side code. If I put the map control into a TabPanel “tpMap” in a TabContainer “tcMain”, the client-side variable is suddenly named “tcMain_tpMap_Map1” instead. 
  
 I did try to utilize the “map” returned by OnMapCreated() (as seen in the example above), but that seems to be a pure OpenLayers map object, not your extended implementation, and so it lacks a method or two. 
  
 Is this a bug or is it wad ? 
  


 


Hi Lars I.,
Sorry for delay and any inconvenience this may cause.
The “Map1” here is the ClientID of the map, it’s wrapped as an instance of utility for operating the pure OpenLayers map object, maybe we should get a better name to avoid the confusion between utility name and the name of the pure map object. Technically, we should use ClientID instead of the Id of the map control, because maybe we add several map controls into a complicated WebControl, such as TabControl, with same id. In other words, on client side, the clientId of map represents the utility object, which is understand as “Map1” by us before.
The “OnMapCreated” and “OnMapCreating” means the pure OpenLayers map creating event, so that’s why you get like that.
Thanks.
Johnny 

 How do I refresh client map if client sends a message to server and changes extent on server side? Do I need to send extent back to client and use ZoomToExtent(extent)?



Hi Hotter, 
  
 After the extent changed on server side, you don’t need to do anything on client side and the map would be refresh automatically. Because the server side is responsible for saving the map status and the client side would recreate the map according to the response from the server. 
  
 Regards, 
 Edgar

 Well I cant make that happen. Maybe you could point where is the problem? My sample:



ChangeExtent_javascript.zip (143 KB)

Hotter, 



I found you were using the Ajax call at client which means the map would not refresh after a post back. So you are right, you need to refresh the map by using “ZoomToExtent(extent)” in the call back. 



And you sample code should be modified two places to do that. 

Server side method “RaiseCallbackEvent”: 

returnString = string.Format("{0},{1},{2},{3}", left, bottom, right, top); // not Map1.CurrentExtent.ToString(); 



Because the openlayers bounds string should look like “left, bottom, right, top” , but our RectangleShape string look like “left, top , right, bottom”. More details about openlayers bounds please see here



Client side method “receiveServerData”: 

function receiveServerData(param){ 

document.getElementById("Label1").innerHTML = param; 

var extent = OpenLayers.Bounds.fromString(param); 

Map1.ZoomToExtent(extent); 





Besides, you also can consider to finish partial refreshing with the help of UpdatePanel  like our sample does. In this way, you just change the extent at server side and our map will refresh automatically, so the above works can be skipped. 



Thanks, 

Edgar



 How do I get those "left, bottom, right, top" from RectangleShape?


I think I found it (rectangleShape.LowerLeftPoint.X, rectangleShape.LowerLeftPoint.Y, rectangleShape.UpperRightPoint.X, rectangleShape.UpperRightPoint.Y)



Yes you are right, if you have any other questions please let us know. 
  
 Regards, 
 Edgar

Can this possibly be updated ? or is there a link to this clientside function documentation somewhere ?