IMF Developer's Guide

Identify Reporting

IMF Developer's Guide » Identify Reporting

This document describes the customization and function of the identify tool that is used for displaying information about features that the user clicks on the map.

The identify tool and the drill-down identify tool are automatically activated for queryable map layers if the tools are added to the toolbar by the site designer. Both tools produce a standard report that displays the attributes of the feature where the user clicks the map with the tool active. In the case of the identify tool, the report shows data from the layer that has the identify icon beside its name in the layers list. The drill-down identify tool displays information about all queryable visible layers with features that are found where the user clicks. To add the tools to your application, include the following in your site configuration file in the tools section.

<TOOL name="Drill Down Identify"
      hint="Identify visible"
      url="$IMF/imfDrillIdentify.jsp"
      shape="point"
      popup="false"
      status="Display information about the features where you click the map."
      graphic="$IMF/tools/drill_1.gif"
      active-graphic="$IMF/tools/drill_2.gif" 
      width="16" height="16" />

<IDENTIFY-TOOL
      name="Identify"
      popup="false"
      hint="Identify"
      status="Display information about the feature that you click on the map."
      graphic="$IMF/tools/identify_1.gif"
      active-graphic="$IMF/tools/identify_2.gif"
      width="16" height="16" />

If the site designer decides that a layer should not be identifiable, or that it should not appear in the drill-down identify report, there are attributes in the <WMS-LAYER> element that can be used to disable identify reporting for a specific layer. Note that a layer isn't queryable at all unless the wms-queryable attribute for a layer is set to "true", so the identify routines for a layer can be disabled that way too.

<WMS-LAYER
  ... 
  wms-queryable="true"
  can-drill-identify="true"
  can-identify="false" />

<WMS-LAYER
  ... 
  wms-queryable="false" />

The layer's configuration can define a custom reporting routine for the identify tool to use for that layer, or a default standard report can be displayed. A custom report is usually a dynamic web document that can be called with parameters to find and display the applicable data. For a custom reporting routine, IMF constructs a URL that contains information from the spatial data record, and calls a remote script that uses CGI, ASP, Cold Fusion, Java, JSP, perl, or Oracle Reports to generate the report. The default reporting routine can also be customized.

There are several types of identify reports.

default
urlAppendFieldValue
urlFieldValues
urlInsertFieldValue
urlMultipleFieldValues

An explanation and configuration guide for each of the report types follows.

identify-type="default"

This is the basic identify routine that lists the field names and values for each feature located where the user clicks the mouse on the map. This is the default identify setting, so it is not necessary to include directives in the configuration file to specify that layers use this type.

If features overlap or more than one feature is within the search tolerance of the position clicked, multiple records will be displayed. The drill-down identify report always uses the default report layout, even if a custom report is used for the identify report.

By default, the report shows all fields with non-null values. The field names are as found in the database, although SDE column names are automatically shortened so as to not display the owner and table name. However, the developer can prevent fields from displaying in the default identify report, and set aliases for the fields so that the names are more meaningful to the user than the field names in the feature table of the layer.

The following is an example of a layer defined with the default identify type and special field settings. In this example, an alias is set for the layer, and some fields have been set to not display in the report. The field named "NAME_TXT" will be shown on the report with a label of "Map Sheet". Note that the fields would display by default, so other fields not listed in the layer definition would appear in the report labeled with their field name.

<WMS-Layer title="1:250,000 NTS Mapsheets" .... >
  <FIELD name="area" visible="false" />
  <FIELD name="perimeter" visible="false" />
  <FIELD name="bc_grid250k_id" visible="false" /> 
  <FIELD name="name_txt" alias="Map Sheet" />
</WMS-LAYER>

Important notes:

When setting the properties of SDE layers, use the full field name including the owner and table name.
When setting field aliases for the default reports, use the alias attribute instead of the identify-alias one. The identify-alias attribute is used by the URL routines to match the parameters when making URL requests.

The default identify and drill-down-identify reports automatically display hyperlinks for fields that contain URLs as values. The text of the hyperlink defaults to "more data", but it can be set to any text within the field element as follows:

<FIELD name="fld_rpt" alias="Field Report"
       hypertext-message="View the field report document" />

If you have field-level metadata, you can define it with the metadata-url attribute of the field element. If metadata is defined for a field, the field name or alias will be a hyperlink to the metadata, which will open in a popup window if the user clicks the hyperlink. Example:

<FIELD name="fld_rpt" metadata-url="http://server/metadata.html" />

The report can also show one or more special identify links made up of field values. The identify links are defined with <IDENTIFY_LINK> elements, which are layer sub-elements.

identify-type="urlMultipleFieldValues"

The urlMultipleFieldValues identify type opens a specified URL that can generate a report using parameters passed from the layer's feature table for the location clicked by the user. If multiple records are found at the point clicked, the URL is called using the values from each record found with the values separated by commas.

For this type of identify report, the layer configuration file must specify the fields that will be sent, and the URL of the document that will produce the report. An example from a map configuration file will likely describe this most clearly:

<WMS-LAYER
       title="1:50,000 NTS Mapsheets"
       .....
       wms-queryable="true"
       identify-popup="true"
       identify-handler="http://myserver.com/mapreport.asp"
       identify-handler-type="urlMultipleFieldValues"
       identify-handler-key-fields="b50k_tag,b50k_id" />

When an identify is done on this layer, the URL will be called with field=value pairs for each key field specified. This process uses the POST method for transmitting what could be a long list of values without exceeding the maximum URL length. For the above example, the resulting URL call would be something like:

http://myserver.com/mapreport.asp?b50k_tag=92F08,92F09&b50k_id=43,44

Your report program can then produce a report by processing the parameters received.

If you are using an existing reporting URL that expects parameters named differently than the field names in the feature table, you can set an alias for the field name following this example:

<WMS-LAYER
       title="1:50,000 NTS Mapsheets"
       .....
       wms-queryable="true"
       identify-popup="true"
       identify-handler="http://myserver.com/mapreport.asp"
       identify-handler-type="urlMultipleFieldValues"
       identify-handler-key-fields="b50k_tag,b50k_id">
  <FIELD name="b50k_tag" identify-alias="mapno" />
</WMS-LAYER>

This will result in the alias being used when the URL is called, as follows:

http://myserver.com/mapreport.asp?mapno=92F08,92F09&b50k_id=43,44

If a new reporting script is being developed, one that can handle one or more field values is much more flexible than a script that can only accept one. This routine is highly recommended.

identify-type="urlFieldValues"

The urlFieldValues identify type opens a specified URL that can generate a report using parameters passed from the layer's feature table for the location clicked by the user. Note that although many records may have been found at the point clicked, the URL is called using the first record found.

<WMS-LAYER
       title="1:50,000 NTS Mapsheets"
       .....
       wms-queryable="true"
       identify-popup="true"
       identify-handler="http://myserver.com/mapreport.asp"
       identify-handler-type="urlFieldValues"
       identify-handler-key-fields="b50k_tag,b50k_id" />

An example from a layer configuration file will likely describe this most clearly:

When an identify is done on this layer, the URL will be appended with field=value pairs for each key field specified. For the above example, the resulting URL call would be something like:

http://myserver.com/mapreport.asp?b50k_tag=92F08&b50k_id=43

Your report program can then produce a report by processing the parameters received.

If you are using an existing reporting URL that expects parameters named differently than the field names in the feature table, you can set an alias for the field name following this example:

<WMS-LAYER
       title="1:50,000 NTS Mapsheets"
       .....
       wms-queryable="true"
       identify-popup="true"
       identify-handler="http://myserver.com/mapreport.asp"
       identify-handler-type="urlFieldValues"
       identify-handler-key-fields="b50k_tag,b50k_id">
  <FIELD name="b50k_tag" identify-alias="mapno" />
</WMS-LAYER>

This will result in the alias being used when the URL is called, as follows:

http://myserver.com/mapreport.asp?mapno=92F08&b50k_id=43

identify-type="urlAppendFieldValue"

The urlAppendFieldValue identify type opens a specified URL that can generate a report using a value passed from the layer's feature table for the location clicked by the user. Note that although many records may have been found at the point clicked, the URL is called using the first record found.

For this type of identify report, the layer configuration file must specify the field that will be sent, and the URL of the document that will produce the report. An example from a map configuration file will likely describe this most clearly:

<WMS-LAYER
       title="1:50,000 NTS Mapsheets"
       .....
       wms-queryable="true"
       identify-popup="true"
       identify-handler="http://myserver.com/mapreport.asp"
       identify-handler-type="urlAppendFieldValue"
       identify-handler-key-fields="b50k_tag" />

When an identify is done on this layer, the URL will be appended with the value of the field specified. For the above example, the resulting URL call would be something like:

http://myserver.com/mapreport.asp?92F08

Your report program can then produce a report by processing the parameter received.

identify-type="urlInsertFieldValue"

The urlInsertFieldValue identify type opens a specified URL that can generate a report using a value passed from the layer's feature table for the location clicked by the user. Note that although many records may have been found at the point clicked, the URL is called using the first record found.

<WMS-LAYER
       title="1:50,000 NTS Mapsheets"
       .....
       wms-queryable="true"
       identify-popup="true"
       identify-handler="http://myserver.com/mapreport_"
       identify-handler-type="urInsertFieldValue"
       identify-handler-suffix=".asp"
       identify-handler-key-fields="b50k_tag" />

When an identify is done on this layer, the value of the field specified will be inserted between the handler and suffix. For the above example, the resulting URL call would be something like:

http://myserver.com/mapreport_92F08.asp