IMF Developer's Guide

<tool>

IMF Developer's Guide » Site Configuration » <tool>

The <tool> element defines a tool in the toolbar above the map. A tool sets a mode that causes something to happen when the user clicks on the map, as opposed to a button that causes something to happen immediately when the user clicks the button. Tools, buttons, and spaces are displayed in the order that they appear within the <tools> element.

There are some special tool names that are known to the application, such as "Zoom In", "Identify", etc., with built-in handlers that perform the special action of the tool. IMF makes it easy to define new tools that interact with the map through the use of custom handlers that you develop. Any tool with a name that is not a special predefined tool is automatically a custom tool.

See also: tool examples and tool image gallery.

Frequency	Parent Elements (the <tool> element is valid within):
PO+	<tools>

Frequency	Description (in this context)
PO+	The <tool> element may appear zero or more times within the <tools> element.

Attributes	Description
active-graphic	The URL of the image for the tool when the tool is active. This is used for tools only, not buttons. Required for tools, ignored for buttons and spaces. The URL can contain the special variable $IMF to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $IMF are resolved relative to the location of the XML file. Required.
graphic	The URL of the image for the tool. The URL can contain the special variable $IMF to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $IMF are resolved relative to the location of the XML file. Required.
handler	The URL to a script that will be executed when the map is clicked. Used by custom tools only (tools unknown by name to the framework). The URL can contain the special variable $IMF to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $IMF are resolved relative to the location of the XML file. Required for custom tools only.
height	The height of the tool image, in pixels. Required.
cursor-url	The URL to a cursor file to be used when zooming over the map when the tool is active. The URL can contain the special variable $IMF to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $IMF are resolved relative to the location of the XML file. Optional. The generic cursor defined in the cursor-generic attribute will be shown if this attribute is missing, or if the user's browser does not support real cursors.
cursor-generic	The name of the default CSS2 cursor used when zooming over the map when the tool is active. This cursor will also be used in browsers that don't support real cursors. Valid values are: "auto", "crosshair", "default", "pointer", "move", "e-resize", "ne-resize", "nw-resize", "n-resize", "se-resize", "sw-resize", "s-resize", "w-resize", "text", "wait", "help". Optional, defaults to "crosshair".
help	The URL to a text file (some HTML permitted) that contains help for this tool to be included on the auto-generated help page. The URL can contain the special variable $IMF to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $IMF are resolved relative to the location of the XML file. Optional. Help text is generated from other attributes if this attribute is missing.
hint	The pop-up tip that will appear when the user moves the mouse over the tool. Required.
name	The name of the tool. All tools in a toolset must have a unique name. Required.
options	This value can be used with some internal JavaScript managed tools. Optional.
popup	Used to indicate that a custom tool should open in a popup window. Optional, defaults to "false".
shape	The data collection shape type. Valid values are "point", "box", "line" and "polygon". For custom tools, the handler script will be executed in the dataFrame each time the user clicks the map. Tip: Use $IMF/imfArgs.jsp for the handler script to understand what arguments the handler script is being called with. Optional, default is "point".
show-point	An indicator of whether a small marker is shown on the viewer's map after the tool is used. Useful for point type of tools only. Valid values are "true" and "false". Optional, defaults to "false".
status	The message that will appear in the browser's status area when the user moves the mouse over the tool. Required.
target	The name of the frame that the URL will be executed in. Use "_blank" to execute it in a new browser window. Optional, defaults to "dataFrame".
visible	Used to set the visibility of a tool to invisible for use in designing user interfaces with active tools set from outside the toolbar. Optional, default is "true".
width	The width of the tool image, in pixels. Required.

Examples:

<!-- A built-in IMF tool -->
<tool name="Measure"
      shape="line"
      options="units=feet"
      hint="Measure Distance"
      status="Measures the distance between points where you click."
      help="$IMF/help/measureTool.txt"
      graphic="$IMF/tools/measure_1.gif"
      active-graphic="$IMF/tools/measure_2.gif"
      width="16" height="16"/>

<!-- A custom tool -->
<tool name="Line Markup"
      shape="line"
      handler="$IMF/imfMarkupToolLine.jsp"
      hint="Line Markup"
      status="Adds user-defined lines to the map."
      help="$IMF/help/markupLineTool.txt" 
      graphic="$IMF/tools/markup_line1.gif"
      active-graphic="$IMF/tools/markup_line2.gif"
      width="18" height="18" />