Pima County GIS - Pima County MapGuide MWF Wrapper

Installing the Wrapper

Overview

The Wrapper is installed on a MapGuide site's web server by the site administrator.

Allocate an hour or so to get oriented to the Wrapper, its files, and what you need to do. Wrapper installation and setup takes some learning time, but once installed, you can use the Wrapper as a common base for all your MapGuide maps and API applications. This saves you a great deal of time in the long run.

Installation in brief:

Copy Wrapper files to your webserver.
Get mgaxctrl.cab files for each Viewer version and install them on your server.
Install class files from Autodesk for Java Viewer (mgjava.cab and mgjava.jar)
Adjust mgmapsettings.inc, the Wrapper settings file to configure the Wrapper for your site.
Test to be sure it works...
Customize the title frame and frameset as needed. Do not change the map frame.

End users use the Wrapper as served by the MapGuide site, but they don't install it directly. In fact, other than having a better MapGuide experience, end users don't even know the Wrapper exists.

Basic Installation

Save old settings, if any. If you are updating an existing installation of the Wrapper, save your current mgmapsettings.inc file in another location. You will want its settings for your site to update the new mgmapsettings.inc file.
Copy Wrapper files to web space. After downloading the released Wrapper zip file and unzipping its contents, either copy all unzipped files to one directory in web space or copy JavaScript (.js) files to a JavaScript directory in web space and all other files to another directory of your choice in web space. It's easiest to put everything in one directory. Be sure that the "samplecode" directory was preserved when you unzipped the files as you don't want the samples mixed in with the functional Wrapper code.
You will see the compressed and uncompressed versions of mgmapframe.cfm and a few others. These files have been compressed to reduce download time for end-users. The uncompressed versions have "SOURCE" in the file name, are not the "live" files used by the Wrapper, and are much easier to read.
Get mgaxctrl.cab files for each Viewer version and install them on your server. Consider making a /viewer/ directory with subdirectories for each version to contain the mgaxctrl.cab files specific to the various versions. You can get latest version mgaxctrl.cab file from Autodesk and the older ones from Pima County. See paths where you can get these files in the mgmapsettings.inc file and adjust the paths in mgmapsettings.inc once you have them on your server.
Install class files. Autodesk supplies the mgjava.cab and mgjava.jar class files for the Java Viewer. Be sure to put them in a "classes" directory on your MapGuide server and adjust the Wrapper's settings mgmapclassespath value (in mgmapsettings.inc) to point to that location. You also put MapGuideObserver6J.class and MapGuideObserver6J.java files from Autodesk in the same classes directory if your API needs them. (These observer file names assume you are using the version 6.0 or 6.5 Viewer. You need other versions if you support older Viewers.)
Our site has the HTML/CFM webserver separate from the dedicated MapGuide server. In our case, the Wrapper is on the HTML/CFM webserver and the class files are on the MapGuide server. If you have two servers splitting the function as we do and you put the class files on the HTML/CFM webserver, some or all users will get a "cross domain" error of some kind with the Java Viewer. The solution is to put the class files on the server running the MapGuide Server processes.
Here's what we have in the classes directory on our MapGuide server:
```
  
 Directory of C:\mapguide\wwwroot\classes

04/26/2004  09:36 AM    <DIR>          .
04/26/2004  09:36 AM    <DIR>          ..
01/13/1999  07:12 PM             1,961 CheckInstall.class
10/02/1998  10:17 AM             3,794 MapGuideObserver3.class
10/02/1998  10:17 AM             4,442 MapGuideObserver3.java
09/15/1998  11:23 AM             4,802 MapGuideObserver4.class
06/30/1998  03:03 PM             6,361 MapGuideObserver4.java
11/21/2000  01:36 PM             5,436 MapGuideObserver5.class
11/21/2000  01:36 PM             7,351 MapGuideObserver5.java
11/21/2000  01:36 PM             5,539 MapGuideObserver5J.class
11/21/2000  01:37 PM             6,881 MapGuideObserver5J.java
07/09/2003  11:13 AM             4,754 MapGuideObserver6J.class
07/09/2003  11:11 AM             6,881 MapGuideObserver6J.java
04/07/2004  12:01 AM         1,194,920 mgjava.cab
04/23/2004  09:52 AM         2,299,191 mgjava.jar
              13 File(s)      3,552,400 bytes	  
               2 Dir(s)  17,237,782,528 bytes free 
```
Your classes directory may be much simpler. While we have observer files for many releases, you only need them for the releases you support. Our CheckInstall.class file is old and we probably don't use it anywhere. The mgjava.cab and mgmava.jar files are important to enable the Java Viewer. Be sure you have the right files for the Viewer version you support. Unfortunately, you can't tell the Java Edition Viewer version from the mgjava.cab and mgjava.jar file names.
Adjust mgmapsettings.inc settings. Use a text editor to adjust paths and settings unique to your site in the mgmapsettings.inc file. This is critical. Check and adjust each setting carefully, paying attention to the comments for each setting. Failure to update the settings or errors in settings values may cause problems that are not easy to debug. (Older Wrapper versions have an mgmappimacounty value that should be left set to false in mgmapsettings.inc to disable a small amount of code unique to Pima County in the Wrapper.)

Testing Your Basic Installation

Test the basic Wrapper installation before customizing the title frame or using the MapGuide API as described below.

Any problems you have are likely to be caused by incorrect mgmapsettings.inc values. It is much easier to fix problems by examining and fixing your settings than it is to zero in on exactly where the code fails.

See Linking to the Wrapper and your MapGuide Map and create a simple Wrapper link to a map. Assuming you have the MapGuide Viewer installed, your new link should simply display the map. If the map fails to load with a known good MWF, try displaying mgmapdetect.cfm over the web. If the mgmapdetect.cfm page fails to display in it's entirety, it's likely that you have an incorrect mgmapjavascriptpath setting.

Do some testing besides just viewing the map such as the following:

Uninstall your Viewer ActiveX control (see uninstall tips) and see that you get the right prompts and installation of the ActiveX control in Internet Explorer when you first access a map through the Wrapper. After uninstalling, use mgmapdetect.cfm to see that the Viewer is really gone. We have mgmapdetect.cfm at a public location on our site and sometimes direct users to that page to get information to help us resolve any issues they may be having. Another thing to try to satisfy yourself that the Wrapper works, is to uninstall and manually install a Viewer older than the current viewer, such as Version 6.0 by running mgcontrol60.exe (possibly released simply as mgcontrol.exe). If you need an old install file, check our FTP server archive. Then surf to a map with the Wrapper and check to see that an upgrade is recommended or required (depending on the Version of your MWF and the corresponding mgrequiredviewer and mgrequiredcodebase settings in your mgmapsettings.inc file).

Assuming your MWF requires the version 6.5 MapGuide Viewer and you have Mac OS X available, test the Java Viewer by using Mac OS X. MWF's made with older MapGuide versions work only on Mac Classic where the Java Viewer more difficult to set up on the Mac due to the need to install Java runtime support. Although Firefox is not supported by Autodesk and the API won't work, you can still use Firefox to test the Java Viewer.

The Wrapper allows you to test the Java Viewer by using Internet Explorer on Windows by adding &use=java to the Wrapper's URL with Internet Explorer. The Wrapper defaults to using the ActiveX control in this case, but for your testing purposes, adding the &use=java parameter to the URL makes Internet Explorer on Windows use the Java Viewer. Read more about Java Viewer Support in the Wrapper.

Customizing your site

Add content to the mgmaptitleframe.cfm title frame for your site, such as a map title and links to help. If you prefer to have a frame to the right of the map, you shouldn't have any problem changing the "title frame" location in mgmap.cfm.
Consider putting the Viewer installation files (.cab and so-on) on your site rather than Autodesk's site, and changing mgmapsettings.inc accordingly. We didn't do this for a long time because we felt it was Autodesk's job to serve their software and not our job. We also wanted to get any "slipstreamed" changes Autodesk made in the same release without telling anyone. However, we learned that the bulk of problems that users were having installing the Viewer were caused by no network access or slow access to Autodesk's site. When we put the MapGuide Viewer installation files on our server, complaints went way down, and users responded that installs were fast. An argument can be made that if the users can get to your site, then they will also be able to get the installation files on your site. That's not necessarily true when the Wrapper is on your site and the MapGuide Viewer installation files are on another site, such as Autodesk's. After putting these files on your server, update their locations in the Wrapper's mgmapsettings.inc file.
Consider trying API customization. See Sample MapGuide API Code for the Wrapper Environment and the supplied samplecode directory of files for examples of using the MapGuide API with the Wrapper. (This assumes you preserved the samplecode directory with "Use Folder Names" or the equivalent when you un-zipped the Wrapper files.)

Checking the user's MapGuide environment with mgmapdetect.cfm

mgmapdetect.cfm is a test or diagnostic that displays the current MapGuide Viewer environment. It uses the "detection" phase of the Wrapper to display the Viewer environment on your machine. You can run mgmapdetect.cfm from our site to see what it does. You can invoke it from your installation to show that all the detection logic is working properly. It is also a very helpful tool for researching and debugging end-user Viewer installation problems. We often have end users surf to our mgmapdetect.cfm page and tell us what it says over the phone or copy the contents to an e-mail to send to us.

Pima County MapGuide MWF Wrapper Main Page