MapGuide 6.5 Migration-Description of the Web Tier API

From MapGuide Best Practices Wiki

Having the flexibility to choose whether to implement MapGuide with a Microsoft Windows Server or a Red Hat® Linux Server gives organizations the ability to choose the most appropriate operating system and development tools. The Web Tier API is fully consistent across both operating systems.

Contents

APIs for MapGuide


Several API objects are available to developers working with Autodesk MapGuide Enterprise. Autodesk MapGuide Studio has a .NET API that enables the user to build custom applications that use Studio components. If developers want to access any aspect of the feature geometries on the server, there is an FDO API to change, manipulate, re-project, or analyze the features.
The following APIs are available:

Web Tier API
Service Function
Resource Service Enables the manipulation of repositories and resources. Can also be used to manipulate and load data.
Feature Service Provides access to FDO providers.
Mapping Service Provides access to maps and layers within a map.
Drawing Service Allows low-level access to drawing sources. Can manipulate DWF files.
Rendering Service Renders a map into a bitmapped image. This image is typically used for display in the HTML viewer.
Coordinate System Supports coordinate system transformations.
Geometry Manipulates geometric objects.
Site Service Configures users, groups, and user sessions.

   
Because much of Autodesk MapGuide and Autodesk MapGuide Studio is driven by XML, including the resource definitions, settings, and layer display configurations, much of the development must be done in applications that can use the Document Object Model (DOM) for XML and that can instantiate and control the APIs.


The following three web development environments represent the three mapagents that are already developed for Autodesk MapGuide and have development examples included in the product:
• PHP 5
• JAVA (JSP)
• ASP.NET

Developing with PHP 5

PHP is a server-side, web-based scripting language that runs on many platforms, including the following:
• Linux (for example, Red Hat, Fedora™)
• Microsoft Windows
• Unix® (for example, Solaris®)
• Mac OS® X


Since PHP is open source, organizations do not have to purchase it. Since it is constantly being revised and debugged, they can be confident that it is robust. It works on most web servers, including Apache, Microsoft Internet Information Server (IIS), Netscape®, and O’Reilly. The Autodesk MapGuide Enterprise Site Administrator is written in PHP. This administration tool is installed with the Web Extensions.
If you choose to install the PHP mapagent, you can use it to call different aspects of the Autodesk MapGuide Enterprise API using PHP.
Following is an example of accessing a map session from Autodesk MapGuide Enterprise within PHP:

<?php
  include 'AppConstants.php';
  MgInitializeWebTier ($configFilePath); //path to the webconfig.ini file
  $userInfo = new MgUserInformation("Administrator", "admin");
  $site = new MgSite();
  $site->Open($userInfo);
  $HTTP_SESSION_VARS['MgSessionId'] = $site->CreateSession();
  $mapDefinition = "Library://DUBLIN CA/5. MAPS/Dublin Map.MapDefinition";
  $webLayout = "Library://DUBLIN CA/6. WEB LAYOUTS/Dublin Web Layout.WebLayout";
?>
<frameset rows="110,*" frameborder="NO" border="0" framespacing="0">
<frame src="Title.php?AppName=Sample Application" name="TitleFrame" scrolling="NO" noresize>
<frame src="/mapviewerphp/dwfviewer.php?SESSION=<?=$HTTP_SESSION_VARS['MgSessionId'] ?>&WEBLAYOUT=<?= $webLayout ?>"
name="ViewerFrame">
</frameset>

Note: The code example uses the library on the server at Library://DUBLIN CA/6. WEB LAYOUTS/Dublin Web Layout.WebLayout is used. This is the web layout created in Autodesk MapGuide Studio.

Example of Instantiating Map with PHP:

$map = new MgMap();
$map->Open($resourceService, 'Dublin Map');


Since the API for Autodesk MapGuide Enterprise is robust, you can use PHP to upload data or link to FDO, create layers with the new information, and then create a map and add that map to the web layouts. The entire process viewed in Autodesk MapGuide Studio could be automated with the API.

Developing with Java


The mapagent installed with the MapGuide Web Server Extensions is a Java Server Page (JSP) called mapagent.jsp. Developed by Sun Microsystems, JSP is a web server scripting agent that communicates requests to the server. JSP is compiled on the server side as a servlet, as opposed to an applet (a java application that runs on the client). JSP can communicate with existing servlets and Java servlets that are on the server. To run JSP pages, you need a web server that is capable of running Java. The most common is the Apache Tomcat Server. Tomcat is another open source application that can be downloaded for free from http://tomcat.apache.org and installed on either Linux or Windows operating system. If you are using Windows or you are running Tomcat in parallel with another web server, you might choose an alternative port when installing it. For example, you may install Autodesk MapGuide Enterprise Web Extensions and use the Java mapagent. It might be found at http://hogwarts:8080/JavaMapAgent/MapAgent.jsp.
Example of Instantiating Map with JSP:

<%@ page import="org.osgeo.mapguide.*" %>
MgMap map = new MgMap();
map.Open(resourceService, "Dublin Map");


All the API calls in Autodesk MapGuide are also available with the Java Web Server Extension.

Developing with ASP .NET

Active Server Pages (ASP) .NET is based on the Microsoft .NET Framework. This programming framework is installed on a Microsoft Windows operating system. Unlike PHP or Java, .NET works only with Microsoft IIS. Using the Microsoft Web Services that .NET provides, you can create many server-side custom applications in a Microsoft environment. ASP.NET can be programmed in many scripting languages:


• C# (C Sharp)
• Visual Basic (VB)
• JScript

ASP.NET developers usually choose between C# and VB.NET. Using development tools such as Microsoft® Visual Studio® .NET, or Microsoft® Visual Basic® .NET, you can easily put together complex applications using the WYSIWYG (what you see is what you get) features of an Integrated Development Environment (IDE).
The MapGuide Web Server Extensions come with an ASP.NET mapagent as well. The sample files that are bundled with the Web Server Extensions are developed in C# .NET, but any of the .NET scripting languages that are compatible with ASP.NET can be used to develop applications.
Example of Instantiating Map with ASP.NET:

<%@ Import Namespace="OSGEO.MapGuide" %>
MgMap map = new MgMap();
map.Open(resourceService, "Dublin Map");
Code Examples


Note: The development guide for Autodesk MapGuide Enterprise is a good resource for code samples. Development methodology is available with the product upon installation.
Many applications require custom interfaces and need to extend capabilities beyond those available in Studio. In Autodesk MapGuide Enterprise these are created in the Web Tier of APIs (ASP.NET, PHP, or JSP). The APIs contain and extend all the functions and methods of the MapGuide API. In fact, most seem instantly familiar. The major differences between using the MapGuide API and the Spatial Application Server API are as follows:


• The Spatial Application Server API is organized into server-side Services (see “Description of Web Tier API,” earlier in this document). Whenever you do anything to your map, you must inform the Spatial Application Server web tier in order to save the state of your application. You can accomplish this by creating a ResourceService object that stores state.
• The Viewer must be informed of changes (because the changes actually take place on the server, not in the client). The most common way to do this is with a DHTML OnLoad() event that refreshes the page (and thus an embedded viewer) when an operation takes place.
• In Autodesk MapGuide, the API references an MWF Object embedded in a browser client. In Spatial Application Server the API references Site resources on a server. Thus the methods to access the API class libraries are very different.


The following examples concentrate on the Site Service and Mapping Service. Within these, examples are given for the following API classes: MgSite, MgSiteConnection, MgWebActions, MgLayer, and MgMap.

Embedding the Viewer into a Web Page

There are several ways to embed the viewer in a web page, but the most common method is to call dwfviewer.aspx, installed in the Web Tier's virtual directory, and pass it the name of a Web Layout. This approach enables users to customize the display and add custom commands. It also supports dynamic interaction by the user through the client. As the user changes the display, the DWF Viewer requests updated metadata from the Spatial Application Server and requests updated graphics to display.
The following code calls two ASP.NET pages: one containing a title graphic, the second a pointer to the Viewer Definition .aspx page. This page is passed a parameter declaring which web layout to reference. For reference, the old way of performing this function is provided as well

 

ASP.NET (Server) 

<frameset rows="120, *">
<frame src="Title.aspx?AppName=Sample Application">
<frame src="http://localhost/mapguide/mapviewernet/dwfviewer.aspx?WEBLAYOUT=Library://
<YOUR DIRECTORY>/Layouts/<YOUR LAYOUT>.WebLayout" name="ViewerFrame">
</frameset>

 MapGuide 6.5 (Client) 

<OBJECT ID="map" WIDTH="100%" HEIGHT="100%"
CLASSID="CLSID:62789780-B744-11D0-986B-00609731A21D">
<PARAM NAME="URL" VALUE="http://localhost/example.mwf">
</OBJECT>

 

Creating User and Session Information: The Site Service API

Using the preceding simple code, developers can view the Spatial Application Server Web Layout and interact with the maps through the default tools. However, to interact with the maps through the API you need to set up user information and session variables. Because Spatial Application Server uses a Web Tier API on the server, any application needs to store session data reflecting the state of the application to pass between the server and the viewer. This is done using a Spatial Application Server session and session variables, accessible through the Site Service API
The following lines of code illustrate the establishment of a Server Site and create a Session ID for later reference.

ASP.NET (Server) 

<%@ Page language=”c#” %>
<%@ Import Namespace=”OSGEO.MapGuide” %>
<%
  String mapDefinition=”Library://<Path to your map resource>/<your map>.MapDefinition”;
  String webLayout=” Library://<Path to your Layout resource>/<your Web Layout>.WebLayout”;
  String SessionId=””;
  MgInitializeWebTier(configPath);
  //configPath is the path to the webconfig.ini file
  MgUserInformation userInfo = new MgUserInformation(“UserName”,“Password”);
  MgSite = new MgSite();
  Site.Open(userInfo);
  sessionId = site.CreateSession()
%>

MapGuide 6.5 (Client) No similar methods.


Some explanation is required here:
• The symbols <% .. %> denote the start and end of blocks of code.
• The first two lines of the code establish the language to be used (in this case, C#) and the libraries of classes to be accessed using the Import method. In this case all the API libraries and associated classes and methods are imported into the application (Library ‘Mg’).
• Next, you create three variables to hold information about the location of the Map and Web Layout resources to be used as well as a Site identification variable.
• Next you initialize the Web Tier.
• Then, you establish the user and create and open a Site using the given user credentials.
• Finally, you create a unique session identifier for the user. The server can now keep track of the session using this variable.
The code to open a viewer and Web Layout earlier stated that although you can interact with the map using the default tools, you could not interact with it through the API. Now, using the Site and session information established here, you can include the viewer in any application simply by adding the session ID variable: 

<frame src="http://localhost/mapguide/mapviewernet/ajaxiewer.aspx?SESSION=<%= SessionId %>&WEBLAYOUT=<%= webLayout %>”
Accessing Map Information Using the MgMap Library of Classes

The following example shows how to access the Autodesk MapGuide Enterprise web tier API to access a map and obtain simple information about the map, getting and displaying the name of the map and its extents. The code assumes that the Session ID variable is passed to the script from the calling function or script.

ASP.NET (Server) 

<%@ Page language=”c#” %>
<%@ Import Namespace=”OSGEO.MapGuide” %>
<%
  String MgSessionId = Request.QueryString[“SESSION”];
  MapGuideApi.MgInitializeWebTier(configPath)
  //configPath is the path to the webconfig.ini file
  MgUserInformation userInfo = new awUserInformation(MgSessionId);
  MgSiteConnection siteConnection = new MgSiteConnection();
  siteConnection.open(userInfo);
  MgResourceService resourceService = siteConnection.CreateService(MgServiceType.ResourceService);
  MgMap map = new MgMap();
  map.Open(resourceService, “<Map Name>”);
  MgEnvelope envelope = map.GetMapExtent();
  Double lowerX = envelope.GetLowerLeftCoordinates().GetX();
  Double lowerY = envelope.GetLowerLeftCoordinates().GetY();
  String mapName = map.GetName();
%>


MapGuide 6.5 (Client) 

<SCRIPT LANGUAGE=”JAVASCRIPT”>
function getMap()
{
  if (navigator.appName == "Netscape")
   return parent.mapframe.document.map;
  else
   return parent.mapframe.map;
}
function getCoordinates(){
  var map = getMap();
  var ext = map.getMapExtent(false,true);
  var lowerX = ext.getMinX();
  var lowerY = ext.getMinY();
  var mapName = map.getName();
}
</SCRIPT>
Enumerating, Refreshing, and Changing the Visibility of Layers

 

To get all the layer names in the map, access the MgLayerCollection class and then the MgLayer class for each layer.
ASP.NET (Server) 

<%
MgLayerCollection LayerCol = map.GetLayers();
MgLayer layer = null;
String layername = “”;
for (int i = 0; i < LayerCol.GetCount(); i++)
{
layer = LayerCol.GetItem(i);
layername = layer.GetName();
}
%>


MapGuide 6.5 (Client) 

<SCRIPT LANGUAGE=”JAVASCRIPT”>
function getMap()
{
    if (navigator.appName == "Netscape")
       return parent.mapframe.document.map;
    else
      return parent.mapframe.map;
}
function getLayerNames(){
 var map = getMap();
 var layers = map.getMapLayersEx(); 
 for (var i = 0; i < layers.size(); i++) 
  {
      var layer = layers.item(i); 
      var layername = layer.getName() ;
  }
}
</SCRIPT>

Continuing the example, you can now toggle the visibility of a layer on or off.
ASP.NET (Server) 

<%
   MgLayerCollection LayerCol = map.GetLayers();
   MgLayer layer = LayerCol.GetItem(“Layer Name”);
    if (layer.IsVisible()){
       layer.SetVisible(false);
   }
   else{
      layer.SetVisible(true);
   }
%>

 

MapGuide 6.5 (Client) 

<SCRIPT LANGUAGE=”JAVASCRIPT”>
function getMap()
{
   if (navigator.appName == "Netscape")
      return parent.mapframe.document.map;
   else
     return parent.mapframe.map;
}
function layerToggle(name)
{
   var map = getMap();
   var layer = map.getMapLayer(name);
   layer.setVisibility(!layer.getVisibility()); 
   map.refresh();
} 
</SCRIPT>
Digitizing

Autodesk MapGuide Enterprise viewers have wrapper APIs available for user interaction with the application. Digitizing and redlining are functions that typically involve user input and can make use of the APIs provided for this purpose.
The Autodesk MapGuide Enterprise Viewer API has several functions for digitizing user input. In this example, if the user clicks the button to digitize a point 

<input type="button" value=" Point " onclick="DigitizePoint();">

  the script calls the JavaScript function: 

function DigitizePoint() {
    parent.parent.mapFrame.DigitizePoint(OnPointDigitized);
}

which in turn calls the DigitzePoint() method of the Viewer API in the map frame. It also passes the name of a callback function, OnPointDigitized, which is defined in the current script. DigizitzePoint() calls this function after it has digitized the point and passes it the digitized coordinates of the point. You can use this callback function to process the digitized coordinates as you wish. In this example, the script simply displays them in the task pane.  

function OnPointDigitized(point) {
   ShowResults("X: " + point.X + ", Y: " + point.Y);
}

MapGuide Enteprise Viewer API (Client) 

<Script Language=”Javascript”>
function digitizeMyLine(myLineDigitizeHandler)
{
   parent.MapFrame.digitizeLineString();
}
Function myLineDigitizeHandler(oLinestring)
{
   // LineString Object
   Var sPoints;
   for (i=0;i<oLineString.count();i++)
  {
      //generate point list string
      sPoints = oLineString.point(i).X + “,” + oLineString.point(i).Y + “,”;
  }
  //submit points to server side script to generate redline layer and feature source 
  var params = new Array(“points”,sPoints);
  parent.FormFrame.submit(“../CreateRedline.aspx”, params, “FormFrame”);
}
</Script>

MapGuide 6.5 (Client) 

<SCRIPT LANGUAGE=”JAVASCRIPT”>
function digitizeMyLine()
{
 getMap().digitizePolyline();
}
</SCRIPT> 
<SCRIPT LANGUAGE=”VBSCRIPT”>
Sub onDigitizePolyline(map, oPoints)
  //create Redline Layer on client Map
End sub
</SCRIPT

Back to Migrating from MapGuide 6.5

Retrieved from "http://sandbox.mapguide.com/index.php/MapGuide_6.5_Migration-Description_of_the_Web_Tier_API"