IMF Developer's Guide

Help System

IMF Developer's Guide » Help System

You can define a url containing a help document for a toolset. As of IMF v4.0.6, there is a script that can be called to show a auto-generated help document for the tabs, buttons and tools that are currently being displayed in the IMF application.

First, let's review how you specify a help document that describes the tools on your web site. It is simple. You just specify the document to use in the <tools> element like one the following examples:

<!-- Help document on some other server -->
<tools toolset="default" active="Zoom In" help="http://myserver.com/myhelp.html">

<!-- Help document in the same directory as the site configuration XML -->
<tools toolset="default" active="Zoom In" help="myhelp.html">

<!-- Auto-generated IMF help script -->
<tools toolset="default" active="Zoom In" help="$FRAMEWORK/imfHelp.jsp">

An IMF site can have multiple tool sets, and there is an IMF script that can be called from a button or tab to figure out and open the help document that is applicable to the toolset currently being displayed. The script is called imfContextHelp.jsp, and is used as follows:

<!-- Call help from a tab -->
<tab name="Help"
     url="$FRAMEWORK/imfContextHelp.jsp"
     target="dataFrame"
     hint="Show Help Page"
     status="Display the help page for this site."
     graphic="$FRAMEWORK/tabs/green_help.gif"
     width="43" height="22"/>

<!-- Call help from a button -->
<button name="Help"
        url="$FRAMEWORK/imfContextHelp.jsp"
        target="dataFrame"
        hint="Show Help Page"
        status="Display the help page for this site."
        graphic="$FRAMEWORK/tools/helpcontents.gif"
        width="16" height="16"/>

So, now you know how to specify different help documents for different toolsets, and how to set up a tool or button to open the help. The rest of this page discusses how you can use the default help document (imfHelp.jsp) for all toolsets in the <tools> element and have detailed context sensitive help generated automatically.

To use the automatic help, specify the imfHelp.jsp script for every toolset:

<tools toolset="default" active="Zoom In" help="$FRAMEWORK/imfHelp.jsp">

The imfHelp.jsp will automatically generate a document containing the graphic of each tab, button, and tool contained in the current toolset shown in the web site, garnering the help text as follows:

If the button, tab or tool contains a help attribute that points to a valid URL containing help text, the text will be inserted into the document under the control.
Otherwise, if the control has a status attribute, the text defined to be shown in the status bar will be shown in the help document under the control's image.
Otherwise, if the control has a hint attribute, the text defined to be shown in the as the hint will be shown in the help document under the control's image.

So, help will always be available for all of your controls as long as it has a hint or a status attribute. If a more detailed description is desired, simply create a text file containing the help that you wish to display for a control and reference it using a help attribute in the control. Note that the text file can contain simple HTML such as bulleted lists, font colors, bold and italic text, but be aware that it is included within another HTML document and should not contain tables or be an HTML document of its own. The help attribute can point at a URL on another server or in the IMF installation or in the same directory as the site configuration XML file using the standard methods for defining URL Paths in XML Configuration Files.

The following text files are available to use with your controls:

$FRAMEWORK/help/clearButton.txt
$FRAMEWORK/help/drillIdentifyTool.txt
$FRAMEWORK/help/emailButton.txt
$FRAMEWORK/help/extractGmlButton.txt
$FRAMEWORK/help/findLocationTab.txt
$FRAMEWORK/help/fullExtentButton.txt
$FRAMEWORK/help/identifyTool.txt
$FRAMEWORK/help/indexMapButton.txt
$FRAMEWORK/help/layersTab.txt
$FRAMEWORK/help/legendTab.txt
$FRAMEWORK/help/markupEraseTool.txt
$FRAMEWORK/help/markupGridButton.txt
$FRAMEWORK/help/markupLabelTool.txt
$FRAMEWORK/help/markupLineTool.txt
$FRAMEWORK/help/markupPointTool.txt
$FRAMEWORK/help/markupPolygonTool.txt
$FRAMEWORK/help/markupRectangleTool.txt
$FRAMEWORK/help/markupTextTool.txt
$FRAMEWORK/help/measureAreaTool.txt
$FRAMEWORK/help/measureTool.txt
$FRAMEWORK/help/panTool.txt
$FRAMEWORK/help/printMapButton.txt
$FRAMEWORK/help/refreshMapTab.txt
$FRAMEWORK/help/selectTool.txt
$FRAMEWORK/help/themesTab.txt
$FRAMEWORK/help/zoomInTool.txt
$FRAMEWORK/help/zoomOutTool.txt
$FRAMEWORK/help/zoomPreviousButton.txt

If you are using older site configuration files with tabs, buttons or tools without help attributes, you should modify them to ensure that your users get detailed help for your site's controls. For example, change:

<tool name="Drill Down Identify"
      type="tool"
      hint="Identify visible"
      status="Show information about features where you click the map."
      graphic="$FRAMEWORK/tools/drill_1.gif"
      active-graphic="$FRAMEWORK/tools/drill_2.gif"
      width="16" height="16" />

... to:

<tool name="Drill Down Identify"
      hint="Identify visible"
      status="Show information about features where you click the map."
      help="$FRAMEWORK/help/drillIdentifyTool.txt"
      graphic="$FRAMEWORK/tools/drill_1.gif"
      active-graphic="$FRAMEWORK/tools/drill_2.gif"
      width="16" height="16" />

... otherwise your help document will display only "Show information about features where you click the map." under the drill down identify tool.

For controls that you add yourself, simply create a text file containing the help in the same directory as the site configuration XML, and reference it something like:

<button name="My Button"
  url="doSomething.html"
  target="dataFrame"
  help="MyButtonHelp.txt"
  hint="My Button"
  status="Information about my button."
  graphic="myButton.gif"
  width="16"
  height="16"/>