= Using MapGuide Overlays with Commercial Map Service Layers =
Commercial tiled map layers can be used as base layers within MapGuide flexible layouts, provided you make some modifications to your application and map projection. Please note that the commercial mapping API providers referenced in this document have terms and conditions attached to the use of their services. Please review those terms before proceeding, especially if your intended application will not be both publicly accessible and free.

= What you will need =
 * a commercial service api key
 * A [http://mapguide.osgeo.org/ MapGuide Open Source 2.1] or !AutoDesk MapGuide Enterprise 2010 Server.
 * Fusion [http://svn.osgeo.org/fusion/trunk/ svn checkout] in place of the bundled fusion installation.
 * [http://trac.osgeo.org/mapguide/wiki/maestro MapGuide Maestro] or familiarity with !MapGuide's !MapAgent utility.
 * [https://mapguide.osgeo.org/download/releases/2.0.x-samples Sheboygan Sample data set]

optional:
 * [http://usa.autodesk.com/adsk/servlet/item?siteID=123112&id=12299450 AutoDesk MapGuide Studio]

 = Getting Started =

You will need to get a free key from a commercial mapping api provider. For Google maps, you can obtain one here:

http://code.google.com/apis/maps/signup.html

After submitting the request, you should get a sample script tag like this:
{{{
<script src="http://maps.google.com/maps?file=api&amp;v=2&amp;sensor=false&amp;key=<your key here>" type="text/javascript"></script>

}}}

Note that the sensor argument has been set to false.

Microsoft's Virtual Earth service can be used by including this script tag:
{{{
<script src='http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.1'></script>

}}}

Finally, Yahoo's service requires you to obtain a key from:

http://developer.yahoo.com/maps

You should get a script tag that looks like
{{{
<script src="http://api.maps.yahoo.com/ajaxymap?v=3.0&appid=<your key here>"></script>

}}}

If you haven't already done so, use the !MapGuide [http://localhost:8008/mapguide/mapadmin/login.php MapAdmin] page to load the Sheboygan sample data which will be used as an example overlay.

= Step 1: Modify the application html =

You can add a commercial base layer to any fusion application, but as an example we will modify the sample template that comes with MapGuide Open Source.

You can find the template's index.html file in
{{{
<MapGuide Install Directory>/WebServerExtensions/www/fusion/templates/mapguide/standard/ 

}}}

 * Use a text editor to open the file and insert the script tag from the previous step right before the fusion tag:
{{{
<script type="text/javascript" src="../../../lib/fusion.js"></script>

}}}

= Step 2: Update the projection information in the !MapDefinition =

Since the Google, Microsoft and Yahoo mapping systems all use the same modified Mercator projection, any overlaid !MapGuide data needs to be transformed into that coordinate system. !MapGuide can reproject vector data on the fly, meaning the original sample set can be used provided that we modify the !MapDefinition to use the Mercator output projection.

 * Using !MapGuide Maestro, connect to the !MapGuide server and make a duplicate of the /Samples/Sheboygan/Maps/Sheboygan  !MapDefinition resource using the Edit menu copy and paste commands. Rename the copy to Sheboygan-m.
 * Double click on the new file to open it and then click on the button next to 'Coordinate System' to bring up the Select Coordinate System dialog. Click the 'Type WKT code' radio button and then paste in the following definition:
{{{
PROJCS["Popular Visualisation CRS / Mercator",GEOGCS["Popular Visualisation CRS",DATUM["Popular_Visualisation_Datum",SPHEROID["Popular Visualisation Sphere",6378137,0,AUTHORITY["EPSG","7059"]],TOWGS84[0,0,0,0,0,0,0],AUTHORITY["EPSG","6055"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4055"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Mercator_1SP"],PARAMETER["central_meridian",0],PARAMETER["scale_factor",1],PARAMETER["false_easting",0],PARAMETER["false_northing",0],AUTHORITY["EPSG","3785"],AXIS["X",EAST],AXIS["Y",NORTH]]

}}}

 * Close the dialog box and then modify the Initial Map View coordinates so they make sense in the new projection:

{{{
Lower left X: -9774168, Y: 5415995

Upper right X: -9754637, Y: 5434757

}}}
If you need to determine coordinates for your own data sets, you can convert them online using [http://proj4js.org Proj4js]. Pick the 'GOOGLE' CRS from the 'dest' list, enter your coordinates and click transform.

You can use !AutoDesk !MapGuide Studio for the above steps by duplicating the !MapDefinition as above but picking 'Save as XML' from the file menu instead. The saved file can be edited in a text editor but you will then need to use the [http://localhost:8008/mapguide/mapagent/ MapAgent] interface to perform a !SetResource operation with the modified xml file. Studio does not have the correct projection built in and there is no way to add it to the !MapDefinition from application's user interface. !MapAgent can also be used to issue a !GetResource request to retrieve the initial xml file.

= Step 3: Add a Google layer to the !ApplicationDefinition =

 * In the same folder as the index.html file, locate the !ApplicationDefinition.xml file and open it in your text editor. You may want to make a backup copy of the file with a different name. In the original file, replace the !MapSet tag contents with the following block:
{{{
<MapGroup id="googleBase">
    <Map>
         <Type>Google</Type>
         <Extension>
              <ResourceId>google</ResourceId>
         </Extension>
    </Map>
</MapGroup>

}}}

 * If you don't like the default Google map type, you can add an <Options> tag to the Google layer to change it:

{{{
G_NORMAL_MAP (default) : street map
G_PHYSICAL_MAP : terrain map
G_HYBRID_MAP : combined satellite and streets
G_SATELLITE_MAP : satellite map

}}}


i.e.
{{{
    <Map>
         <Type>Google</Type>
         <Extension>
              <ResourceId>google</ResourceId>
              <Options>
                   <type>G_PHYSICAL_MAP</type>
              </Options>
         </Extension>
    </Map>

}}}

 * You can use the same approach with Virtual Earth (be careful - these are case sensitive):

{{{
Road (default) : street map
Shaded : terrain map
Hybrid : combined satellite and streets
Aerial : satellite map

}}}

 * Or Yahoo Maps:

{{{
YAHOO_MAP_REG (default) : street map
YAHOO_MAP_SAT : satellite map
YAHOO_MAP_HYB : combined satellite and streets

}}}

 * Add a second <Map> tag to your map group after the google <Map>. Take care that it remains within the <!MapGroup> tags. The useOverlay tag makes the layer's background transparent so the base layer can be seen.
{{{
    <Map>
         <Type>MapGuide</Type>
         <SingleTile>true</SingleTile>
         <Extension>
              <Options>
                   <isBaseLayer>false</isBaseLayer>
                   <useOverlay>true</useOverlay>
              </Options>
              <ResourceId>Library://Samples/Sheboygan/Maps/Sheboygan-m.MapDefinition</ResourceId>
         </Extension>
    </Map>

}}}

'' Note that the commercial layer must be the base layer so any overlays must have the isBaseLayer: false option set. You can also
pass other [http://openlayers.org/ OpenLayers] layer options in the Options tag. For example, <opacity>0.8</opacity> creates a semi-transparent appearance.''

 * Load the template in a browser: http://localhost:8008/mapguide/fusion/templates/mapguide/standard/

To use the Microsoft Virtual Earth or Yahoo mapping services as base maps, remove the google <Map> block from your !ApplicationDefinition and replace it with

{{{
      <Map xsi:type="WMSLayerType">
        <Type>VirtualEarth</Type>
        <Extension>
          <ResourceId>ve</ResourceId>
        </Extension>
      </Map>

}}}

for Virtual Earth or

{{{
      <Map xsi:type="WMSLayerType">
        <Type>Yahoo</Type>
        <Extension>
          <ResourceId>yahoo</ResourceId>
        </Extension>
      </Map>

}}}
for Yahoo.

 * By default, the map will load with global extent (showing the entire world) because the commercial layer is the base layer. To specify a desired initial view, add an additional xml block to the [wiki:ApplicationDefinition/MapSet/MapGroup MapGroup] alongside the individual Map tags:

{{{
      <InitialView>
          <MinX>-9774168</MinX>
          <MinY>5415995</MinY>
          <MaxX>-9754637</MaxX>
          <MaxY>5434757</MaxY>
      </InitialView>

}}}
 
''Support for these layer types is a new addition to Fusion 2.0 so you may encounter compatibility issues. Please help the project by reporting them to the fusion-dev mailing list or filing a bug in the fusion trac instance.''