MapGuide Viewer API Reference

Form frame method
- Submit
Legend palette methods
Main frame methods
Map frame methods
Property palette method
- SetProperties
Status bar methods
Toolbar methods
- OnCommandExecuted
- OnCmdStateChanged

Form frame method

Submits a POST request to a server.

Parameters:
url - the URL of the server to send the request to. url can be the name of the script, a relative URL, or an absolute URL, depending on where the invoked script is located.

params - an array containing the request's parameters. Specify each parameter as a name-value pair of strings, where each pair occupies two consecutive array elements. If a request has two parameters, for example, params must have four elements: The first element contains the name of the first parameter; the second element contains the value of the first parameter; the third element contains the name of the second parameter; and the fourth element contains the value of the second parameter. If the request has no parameters, use an empty array or null.

target - the case-sensitive name of the request's target frame: "tbFrame" (toolbar), "mapFrame" (map area, including the legend and property palettes), "formFrame" (this form), "scriptFrame" (script frame), "taskBar" (toolbar above the task frame), "taskPaneFrame" (frame containing the task pane), or "sbFrame" (status bar). target also can be the window name of an existing pop-up frame. The usual targets of a form submit are "scriptFrame" and "taskPaneFrame".

Examples:
The following example calls the script BuildReport.php on the server, without parameters, and directs the script's result to the script frame.
formFrame.Submit("BuildReport.php", null, "scriptFrame");

The following example calls the script Surface.php with two arguments and displays the script's result in the task frame.
xmlSel = mapFrame.GetSelectionXML();
params = new Array("UNITS", "SquareFeet", "SEL", xmlSel);
formFrame.Submit("../MiscScripts/Surface.php", params, "taskPaneFrame");

Legend palette methods

GetBaseGroups(onlyVisible): Returns a list of the names of the base groups that meet the specified filtering criteria.
Parameters:
onlyVisible - set to true to return only visible base groups; set to false to ignore base-group visibility.

GetLayer(layerId)

Returns the map layer with the specified object ID, as a Layer object:

Layer {
  legend;     /* Legend text displayed for this layer */
  name;       /* Layer name */
  objectid;   /* Unique layer identifier */
}

Parameters:
layerId - the layer's unique object ID.

GetLayers(onlyVisible, onlySelectable)

Returns a list of the map layers that meet the specified filtering criteria. The list contains Layer objects:

Layer {
  legend;     /* Legend text displayed for this layer */
  name;       /* Layer name */
  objectid;   /* Unique layer identifier */
}

Parameters:
onlyVisible - set to true to return only the layers visible at the current scale; set to false to ignore layer visibility.

onlySelectable - set to true to return only layers that can be selected; set to false to ignore layer selectability.

InternalStateComplete(): Indicates whether the legend palette is fully initialized. Returns true if the legend palette is initialized; false otherwise. Scripts running in other frames must make sure that this method returns true before calling other methods of the legend palette; otherwise the result will be unpredictable. If this method returns false, wait until the viewer can build all the layers before calling it again.

Refresh(): Forces a refresh of the legend palette, requesting complete layer and group information from the server. This method refreshes only the legend palette; to refresh other viewer components, use the map frame Refresh() method.

SetScale(scale): Changes the legend's scale. This command can make layers and groups appear or disappear from the palette's display, depending on how visibility is defined for the new scale.
Parameters:
scale - the new scale, as a floating-point number greater than or equal to one.

Main frame methods

ExecuteCommand(index): Executes a command in the command list that GetCommands() returns.
Parameters:
index - a zero-based index that specifies which command in the list to execute. A floating-point number is truncated to an integer. If index is out of bounds then the call is ignored and no command is executed.

ExecuteMapAction(code)

Executes a map command.

Parameters:
code - the code associated with the command to execute. The following table shows the valid codes.

Code	Action
1	Enter Pan mode
2	Pan up
3	Pan down
4	Pan right
5	Pan left
6	Enter Zoom mode
7	Zoom in
8	Zoom out
9	Zoom to rectangle
10	Zoom to selection
11	Zoom to map extents
12	Go to previous view
13	Go to next view
14	Zoom to initial view
15	Enter selection mode
16	Select radius
17	Select polygon
18	--
19	Clear selection
20	Refresh map
21	Copy map to clipboard
22	About

See Also: OnCommandExecuted

FormatMessage(fmt, params)

Formats a message, performing simple string substitution. Returns the formatted message.

Parameters:
fmt - a format string, containing substitution tags of the form {0}, {1}, {2}, etc.

params - an array of values to be substituted into the format.

Example:
FormatMessage("This is the format string, with values {0} and {1}.", new Array("first", "second"));

returns

"This is the format string, with values first and second."

ForwardMouseDown(doc, evt)

Notifies all other frames that a mouse-down event has occurred. This notification allows a frame with an open context menu to close that menu when another part of the viewer is clicked. A script that runs in the task pane must call this method when it receives mouse-down events. You don't have to write special code to handle the viewer's default context menu but if you have provided a custom context menu then you must write your own menu-closing code.

Parameters:
doc - a reference to the document where the click occurred.

evt - the event.

Example:
In the following example, the script attached to the document receiving the mouse-down event calls ForwardMouseDown() before processing the event, causing the main frame to call OnForwardMouseDown() in every frame where this method is present, giving each frame the opportunity to close an open context menu.

function OnMouseDown(evt) {
    parent.ForwardMouseDown(this.document, evt);
    //further processing of the event here...
}

GetCommands(): Returns a list of the commands defined for the current web layout. The list contains BasicCommand-derived objects (a search command is a SearchCommand object, for example). Don't modify the list items. Use ExecuteCommand() to execute a command in the list.

GetContextMenuItems(): Returns a list of the items in the context menu. These items are as they are defined in the web layout, whether or not the context menu is visible when this method is called. The list contains CommandItem or FlyoutItem objects. Don't modify the list items.

GetFormFrame(): Retrieves a reference to the hidden form frame, which you can use to make POST requests to a server-side script. Use the returned reference with Submit().

GetMapFrame(): Retrieves a reference to the map frame that holds the currently displayed map (DWF or HTML format). Use the returned reference with the Main frame methods.

GetScriptFrame(): Retrieves a reference to the hidden script frame, which executes client-side scripts. Every frame contains an HTML page that can contain JavaScript code that's executed when the page is loaded. The GetScriptFrame() method returns a reference to the script frame, which you can use to execute a client action after a server-side script runs.
Example:
GetScriptFrame().location.href = "MyScript.php"

GetTaskFrame(): Retrieves a reference to the task pane, which can display the result of a server-side script.
Example:
GetTaskFrame().location.href = "MyScript.php"

GetTaskListItems(): Returns a list of the items in the task list. These items are as they are defined in the web layout, whether or not the task list is visible when this method is called. The list contains CommandItem objects. Don't modify the list items.

GettingStartedURL(): Returns the URL of the page displayed in the task pane. If no home task is defined, returns the URL of the default Getting Started page.

GetToolbarItems(): Returns a list of the items in the toolbar. The list contains CommandItem or FlyoutItem objects. Don't modify the list items.

GotoHomePage(): Displays the home page in the task pane. If the user hasn't set a home page then the web layout's default home page is displayed. If the task pane is hidden, nothing happens.

Refresh(): Refreshes the current map. This method refreshes the viewer's map, legend, and property components; to refresh only the legend, use the legend palette Refresh() method.

SetSelectionXML(xmlSet)

Selects map features by using an XML description of those features. Calls the SetSelectionXML() method of the map frame.

Parameters:
xmlSet - a well-formed XML description of the features to select. This XML text must validate against the feature-set schema FeatureSet-1.0.0.xsd, which comes with the MapGuide distribution.

See Also: GetSelectionXML() SetSelectionXML()

SetStatusMsg(msg): Displays the specified text in the browser's status bar. The text remains in the status bar until it's overwritten by the browser or an application.
Parameters:
msg - the string to display. Use an empty string or null to clear the status bar.

ZoomToView(x, y, scale, refresh)

Centers the map at the specified point and zooms to a specified scale. Calls the ZoomToView() method of the map frame.

Parameters:
x - the x coordinate of the new center point, expressed in map units.

y - the y coordinate of the new center point, expressed in map units.

scale - the new scale of the map, as a floating-point number greater than or equal to one.

refresh - Determines whether the entire map is refreshed when it is recentered or zoomed. Set refresh to true to refresh; false otherwise. This setting applies only to DWF images; HTML images always refresh automatically.