= 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.

= What you will need =
 * a commercial service api key
 * A [http://mapguide.osgeo.org/ MapGuide 2.1 Server]
 * [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>
}}}

 * Add a second <Map> tag to your map group after the google <Map>. Take care that it remains within the <!MapGroup> tags.

{{{
    <Map>
         <Type>MapGuide</Type>
         <SingleTile>true</SingleTile>
         <Extension>
              <Options>
                   <isBaseLayer>false</isBaseLayer>
              </Options>
              <ResourceId>Library://Samples/Sheboygan/Maps/Sheboygan-m.MapDefinition</ResourceId>
         </Extension>
    </Map>
}}}

'' Note that the Google layer must be the base layer so any overlays must have the isBaseLayer: false option set. ''

 * 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.

''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.''