Pima County Geographic Information Systems logo

Pima County GIS - Pima County MapGuide MWF Wrapper

Migrating Existing API Applications to Use the Wrapper

The Wrapper is easier to integrate on a new MapGuide site, especially if you have API applications. Retrofitting an existing site is more difficult, especially if the site uses the MapGuide API.

While the Wrapper code is general purpose, it requires that the map object be in its own dedicated frame. API functions can be added to any existing map easily with very little code, as all the Wrapper code is common to all API applications.

The Wrapper allows all your maps to be encapsulated by the same web page code with URL parameters that specify a path to desired MWF and API code. This allows you to code just the API code fragment to do what we want, and not copy and rework an entire map page just to run a little API code in JavaScript. See the mgmap.cfm code file header for Wrapper mgmap.cfm parameters that specify the location of your API code.

Realize that the "guts" of the Wrapper is the mgmapframe.cfm module which displays the map frame. The page you invoke for the Wrapper, mgmap.cfm, is just the frame definition that includes the map frame. Developers with other frames to integrate (such as to control the MapGuide API) would typically use their own top level frameset page in place of mgmap.cfm, using the map frame as defined in mgmap.cfm and whatever title or other frames as dictated by the application. For an API application, use the scriptpath and/or jspath parameters and optionally the vbspath parameter to mgmapframe.cfm to point to the application's API code in separate modules. No changes are required to mgmapframe.cfm. If your map uses frames now, you might be able to slip mgmapframe.cfm in where your current map frame is.

Existing API applications will take some thinking and rework to drop into the Wrapper environment. On the other hand, new API applications are greatly simplified using the Wrapper. We feel the Wrapper supports the API well, but you need to pick out the API portions of your existing pages to use with the Wrapper. The Wrapper also makes the assumption that there is no API user interface code (user forms, controls and so on) in the map frame itself -- and we have yet to see a case where this is necessary. Typically, HTML forms and controls used with the API go into the mgmaptitleframe.cfm file or other fame defined by you in a copy of mgmap.cfm.

While it takes a little head scratching to learn how to integrate API code with the Wrapper, in the end it's astonishingly simple. (Each time we add API code to a map, we copy a couple of small files from another map's API code to get started so even we don't have to figure it out again. Some of these file are in the samplecode directory release with the Wrapper. ) The nice thing is that API code can be added to any map without writing anything more than the API code you want to do your specific function. Your API code files can be very small and to the point.


Back button Pima County MapGuide MWF Wrapper Main Page