This appendix describes the MapViewer JavaScript application programming interface (API) for SVG maps. This API contains predefined functions that can be called from outside the SVG map, typically from the HTML document in which the SVG map is embedded. In addition, you can create JavaScript functions to be called when certain mouse-click actions occur. The predefined and user-defined functions can be used to implement sophisticated client-side interactive features, such as customized navigation.
If you use any of the JavaScript functions described in this appendix, end users must use Microsoft Internet Explorer to view the SVG maps, and Adobe SVG Viewer 3.0 or a later release must be installed on their systems.
This appendix contains the following major sections:
The MapViewer JavaScript functions for controlling navigation include the following:
recenter(x, y) sets the center point of the current SVG map.
The input x and y values specify the coordinates (in pixels) of the new center point, which is the point inside the SVG map to be displayed at the center of the SVG viewer window. The SVG viewer window is the graphical area in the web browser displayed by the SVG viewer. The coordinates of the center point are defined in the SVG map screen coordinate system, which starts from (0, 0) at the upper-left corner of the map and ends at (width, height) at the lower-right corner.
setZoomRatio(zratio) sets the current map display zoom ratio.
This function can be used to zoom in or zoom out in the SVG map. (It does not change the center point of the map.) The original map zoom ratio without any zooming is 1, and higher zoom ratio values show the SVG map zoomed in. The map zoom ratio should be set to those values that fit predefined zoom levels. For example, if the zoomlevels value is 4 and zoomfactor value is 2, map zoom ratios at zoom level 0, 1, 2, and 3 will be 1, 2, 4, and 8, respectively; thus, in this example the zratio parameter value should be 1, 2, 4, or 8. For more information about predefined zoom levels, see the descriptions of the zoomlevels, zoomfactor, and zoomratio attributes in Section 3.2.1.1.
MapViewer provides functions to enable and disable the display of informational tips, the map legend, hidden themes, and the animated loading bar. The display control functions include the following:
switchInfoStatus() enables or disables the display of informational tips. (Each call to the function reverses the previous setting.)
You can control the initial display of informational tips by using the <hidden_info> element in theme styling rule definition (see Section A.7) and the infoon attribute in a map request (see Section 3.2.1.1). The switchInfoStatus() function toggles (reverses) the current setting for the display of informational tips.
switchLegendStatus() enables or disables the display of the map legend. (Each call to the function reverses the previous setting.) The legend is initially hidden when the map is displayed.
showTheme(theme) sets the specified theme to be visible on the map, and hideTheme(theme) sets the specified theme to be invisible on the map.
showLoadingBar() displays the animated loading bar. The animated loading bar provides a visible indication that the loading of a new map is in progress. The bar is removed from the display when the loading is complete.
MapViewer provides several predefined mouse-click event control functions, which are explained in Section B.3.1. You can also create user-defined mouse event control functions, as explained in Section B.3.2.
MapViewer provides functions to enable and disable theme feature, rectangle, and polygon selection in SVG maps. It also provides functions to get information about selections and to toggle the selection status on and off. The functions for customizing mouse-click event control on an SVG map include the following:
enableFeatureSelect() enables theme feature selection, and disableFeatureSelect() disables theme feature selection.
Theme feature selection can be enabled if the selectable_in_svg attribute in the <theme> element is TRUE either in the map request (see Section 3.2.20) or in the base map (see Section A.8) definition. If the theme is selectable and theme feature selection is enabled, each feature of the theme displayed on the SVG map can be selected by clicking on it. If the feature is selected, its color is changed and its ID (rowid by default) is recorded. Clicking on an already selected feature deselects the feature. The list of IDs of all selected features can be obtained by calling the getSelectedIdList() function, described in this section.
When theme feature selection is enabled, polygon selection and rectangle selection are automatically disabled.
enablePolygonSelect() enables polygon selection, and disablePolygonSelect() disables polygon selection.
If polygon selection is enabled, a polygon selection area can be defined by clicking and moving the mouse on the SVG map. Each click creates a shape point for the polygon. The coordinates of the polygon are recorded, and can be obtained by calling the getSelectPolygon() function, described in this section.
When polygon selection is enabled, theme feature selection and rectangle selection are automatically disabled.
enableRectangleSelect() enables rectangle selection, and disableRectangleSelect() disables rectangle selection.
If rectangle selection is enabled, a rectangular selection window can be defined by clicking and dragging the mouse on the SVG map. The coordinates of the rectangle are recorded, and can be obtained by calling the getSelectRectangle() function, described in this section.
When rectangle selection is enabled, theme feature selection and polygon selection are automatically disabled.
getInfo(theme, key) returns the informational note or tip string of the feature identified by theme name and key.
getSelectedIdList(theme) returns an array of all feature IDs that are selected on the SVG map.
getSelectPolygon() returns an array of the coordinates of all shape points of the selection polygon, using the coordinate system associated with the original user data.
getSelectRectangle() returns an array of the coordinates of the upper-left corner and the lower-right corner of the selection rectangle, using the coordinate system associated with the original user data.
selectFeature(theme, key) toggles the selection status of a feature (identified by its key value) in a specified theme.
setSelectPolygon(poly) sets the coordinates of all shape points of the selection polygon, using the coordinate system associated with the original user data. The coordinates are stored in the array poly. Calling this function after enablePolygonSelect() draws a polygon on the SVG map.
setSelectRectangle(rect) sets the coordinates of the upper-left corner and the lower-right corner of the selection rectangle, using the coordinate system associated with the original user data. The coordinates are stored in the array rect. Calling this function after enableRectangleSelect() draws a rectangle on the SVG map.
User-defined JavaScript mouse-event control functions can be combined with predefined JavaScript functions (described in Section B.3.1) to implement further interactive customization. You can create map-level, theme-level, and selection event control functions.
Map-level mouse event control functions can be defined for mouse-click events and mouse-move events.
A mouse-click event function is called whenever a click occurs anywhere in the SVG map, if both theme feature selection and window selection are disabled. The name of the function is defined by the onclick attribute in the map request (see Section 3.2.1.1).
A mouse-move event function is called whenever the mouse moves anywhere in the SVG map. The name of the function is defined by the onmousemove attribute in the map request (see Section 3.2.1.1).
These JavaScript functions must be defined in the web page that has the SVG map embedded. Mouse-click and mouse-move event functions must accept two parameters, x and y, which specify the coordinates inside the SVG viewer window where the mouse click or move occurred. The coordinate is defined in the local SVG viewer window coordinate system, which starts from (0,0) at the upper-left corner and ends at (width, height) at the lower-right corner.
Theme-level mouse event control functions can be defined for mouse-click, mouse-move, mouse-over, and mouse-out events.
A mouse-click event control function is called when theme feature selection is enabled and a feature of the theme is clicked. Each theme in the map can have its own mouse-click event control function. A theme-level mouse-click event control function is specified by the onclick attribute in the <theme> element in the map request or base map definition.
A mouse-move event control function is called whenever the mouse moves inside any feature of the theme. Each theme in the map can have its own mouse-move event control function. A theme-level mouse-move event control function is specified by the onmousemove attribute in the <theme> element in the map request or base map definition.
A mouse-over event control function is called whenever the mouse moves from outside a feature of the theme to inside a feature of the theme. Each theme in the map can have its own mouse-over event control function. A theme-level mouse-over event control function is specified by the onmouseover attribute in the <theme> element in the map request or base map definition.
A mouse-out event control function is called whenever the mouse moves out of a feature of the theme. Each theme in the map can have its own mouse-out event control function. A theme-level mouse-out event control function is specified by the onmouseout attribute in the <theme> element in the map request or base map definition.
These JavaScript functions must be defined in the web page that has the SVG map embedded. They take the following parameters:
Theme name
Key of the feature
X-axis value of the point in the SVG viewer window where the mouse click occurred
Y-axis value of the point in the SVG viewer window where the mouse click occurred
The key of the feature is the value of the key column from the base table, which is specified by the key_column attribute of the <theme> element in the map request or base map definition. ROWID is used as the default key column. For example, if the onclick attribute is set to selectCounty for the COUNTY theme, the following JavaScript function call is executed if the feature with rowid AAAHQDAABAAALk6Abm of the COUNTY theme is clicked on the SVG map at (100,120): selectCounty('COUNTY', 'AAAHQDAABAAALk6Abm', 100, 120).
The x-axis and y-axis values specify the coordinates inside the SVG viewer window where the mouse event occurred. The coordinate is defined in the local SVG viewer window coordinate system, which starts from (0,0) at the upper-left corner and ends at (width, height) at the lower-right corner.
You can define a selection event control function for rectangle selection or polygon selection, or for both.
A rectangle selection event control function is called whenever rectangle selection is enabled and a rectangular selection area has been created by clicking and dragging the mouse (to indicate two diagonally opposite corners) on an SVG map. The function is called immediately after the selection of the rectangle is completed and the mouse key is released. The function name is specified with the onrectselect attribute in the map request (see Section 3.2.1.1).
A polygon selection event control function is called whenever polygon selection is enabled and a polygon-shaped selection area has been created by clicking and dragging the mouse at least four times on an SVG map, with the last click on the same point as the first click to complete the polygon. The function is called immediately after the selection of the polygon is completed. The function name is specified with the onpolyselect attribute in the map request (see Section 3.2.1.1).
MapViewer provides other useful functions for working with SVG maps. These functions include the following:
getUserCoordinate(x,y) converts the screen coordinates into the original map data coordinates. This function returns the converted result in an array. The first element of the array is the converted X coordinate, and the second element of the array is the converted Y coordinate.
getScreenCoordinate(x,y) converts the original map data coordinates into the screen coordinates. This function returns the converted result in an array. The first element of the array is the converted X coordinate, and the second element of the array is the converted Y coordinate.