MapGuide Viewer API

The MapGuide Viewer API is a set of JavaScript functions used to interact with the Viewer. Many of the Viewer frames contain embedded JavaScript functions that can be called from other locations. For full details about the available functions, refer to the online MapGuide Viewer API Reference.

To execute any of the Viewer API functions, call them from JavaScript embedded in a page. There are three common techniques for this:

- Define an Invoke Script command in the web layout. Use this technique when you want to call the Viewer API directly from the tool bar, task list, or context menu.
- Load a page into the hidden script frame and execute the script when the page loads. Use this technique when you want the Viewer to change as a result of an action in the MapGuide page, without reloading the page.
- Execute the JavaScript call from a page loaded in the task pane frame. The JavaScript can execute when the page first loads or as a result of user interaction.

It is important to know the relationships between the frames. JavaScript executes in the context of a single frame, but it can call functions from other frames by locating them in the frame hierarchy. The following frames are children of the main Viewer frame:

- tbFrame
- mapFrame
- formFrame
- scriptFrame
- taskFrame

The taskPaneFrame is a child of the taskFrame.

Custom JavaScript code can execute in the context of the main frame, the script frame, or the task pane frame.

JavaScript defined as an Invoke Script command executes in the context of the main frame. To execute functions in one of the other frames, identify the function with the frame name and function name. For example, the following calls the ZoomToView() function of the mapFrame from the main frame:

    mapFrame.ZoomToView(xLoc, yLoc, newScale, true);

JavaScript loaded into the scriptFrame must go up 1 level in the hierarchy using parent. For example:

    parent.mapFrame.ZoomToView(xLoc, yLoc, newScale, true);

JavaScript loaded into the taskPaneFrame must go up 2 levels in the hierarchy using parent.parent. For example:

    parent.parent.mapFrame.ZoomToView(xLoc, yLoc, newScale, true);

Many Viewer API calls will generate requests to the site server, either to refresh data in the Viewer or to notify the site server of a change in Viewer state. These requests are generated automatically.

#### Topics in this section

- Calling the Viewer API with an Invoke Script Command
- Calling the Viewer API from the Script Frame
- Calling the Viewer API from the Task Pane
- Extending Map Initialization Functionality
- The Hello Viewer Sample