Visual representation of task results

In this topic

About visualization of task results

In ArcGIS Server 10, task results are represented in two ways: data representation (shown in a result panel) and visual representation (shown on the map as a callout). The following screen shot shows the effect of identifying a result in ArcGIS Server 10:

Terminology

The following four distinct features are defined by the visual representation. The features are defined and configured in the faces-config.xml of the Application Development Framework (ADF) of a Web application.

Callout

The result pane window is referred to as the Callout.

LayerDefinition

LayerDefinition is a Java class used to customize the query result. The LayerDefinition can be used to set field aliases, filter return fields, set symbols, and set other features related to the resulting layer. The calloutTemplate and resultTemplate are also defined here. This class must be defined for the Callout window to display as desired.

calloutTemplate

calloutTemplate is an Extensible Markup Language (XML) template that's used to display results in the Callout. It comprises three nodes at the top level: header, body, and footer. See the following illustration:

resultTemplate

resultTemplate is a well-defined XML template for formatting result attributes.

Supported map services

ArcGIS Local Map Service, ArcGIS Internet Map Service, ArcIMS Local Map Service, and ArcIMS Internet Map Service support callout functions.  Web Map Service (WMS) services do not support callout function since WMS protocol does not return geometry information.

Using the Identify task in a Manager-generated Web application

Callout functions are enabled by default in the Web ADF Web map application. Any query result that originates from a layer with LayerDefintion can have a callout. Results can be populated through the Identify task. The following usage scenario uses a Manager-generated map application.
The following steps show how to create and deploy a Web application using Manager. In this process, the LayerDefinition is automatically configured in faces-config.xml
  1. Click the Identify icon on the toolbar. See the following screen shot:

  2. Click the map to identify the result. The callout window opens as shown in the following screen shot:

  3. Show all the feature classes for this location. See the following screen shot:

  4. Select one feature class (for example, Montana in the States layer) and click the add to results link at the bottom of the callout window to add the results to the result panel. See the following screen shot:

  5. Switch to the Pan tool and click the MapTip graphics to show the callout. See the following screen shot:

Customization categories

This section describes the customization categories that are available.

Renderer

The Renderer category defines how the result (the MapTip feature) graphics should be rendered by default. It holds a symbol that is used during the rendering. You can set the picture marker for the result in a point layer. For line layers, you can set a line color, width, pattern (dashed, dotted, and so on), and transparency. For polygon layers, you can set the same line properties to define the border of the polygon and also set a fill color. Define your own symbol and pass it to the renderer to customize the renderer.

HighlightRenderer

The HighlightRenderer category defines how the result graphics are rendered when they're highlighted. That is, what the result graphics look like when the mouse moves over them.

FieldAlias

The FieldAlias category sets the field alias's name for the feature attributes.

CalloutTemplate

The CalloutTemplate category sets the content of callout window. You can define any customized content here. ${fieldalias} represents the feature class attribute to insert the result attribute into callout content. For example, to show the city’s population in the callout, put the variable references ${CITY_NAME} and ${POP1999} into the CalloutTemplate (assuming that CITY_NAME is the name attribute and POP1999 is the population attribute).
See the following code example:
<managed-property>
     <property-name>calloutTemplate</property-name>
     <value><![CDATA[<header>Welcome to ${CITY_NAME}</header>
     <body><div style='width:200px;height:100px'>${CITY_NAME} has population ${POP1990</div></body>
     <footer>Demo footer</footer>]]></value>
</managed-property>

ResultTemplate

The ResultTemplate category sets the content of the result in the result window.

MaxRecordCount

The MaxRecordCount category sets the maximum number of returned records.

Customizing the result

There are two ways to customize the result: using Manager or manually. Both of these options interact with LayerDefinition. While using Manager is more convenient, the manual approach provides more flexibility.

Customizing results using Manager

This sections describes how to use Manager to customize your result.
Layer configuration
Layer configuration defines how results returned from the layer are shown and what is represented in the callout. This is the default configuration for all the tasks executed on this layer. Each layer can be configured to have its own symbol mark, highlight color, and width.
Task configuration
Task configuration defines how returned task results are shown and what the callout content is.  Each layer can have one and more tasks. Each task can have its own result configuration. Once you define a task configuration on a layer, the layer configuration is overridden. This gives you more flexibility over the appearance of the results.
For instance, assume you have single point layer called Hospital. You want to put hospitals into two categories. One category is hospitals where visit time is more than 35 minutes; while the other category is hospitals with less than 35 minutes visit time. You need to distinguish them immediately when you look at your map. Hospitals with more than 35 minutes visit time would be shown with a larger symbol, while hospitals with less than 35 minutes visit time would be shown with a smaller symbol.
 
Follow these steps to accommodate this customization:
  1. Define two separate query tasks.
    1. One task defines a query that returns all the results with a visit time of more than 35 minutes.
      1. Chose the larger size symbol for this task.
    2. The other task defines a query that returns all the results with a visit time of less than 35 minutes.
      1. Chose the smaller size symbol for this task.
  2. Execute the two tasks. Graphics are rendered with respect to the custom query tasks you created.
Understanding the callout
This subsection is targeted for programmers, technicians, and those who need more flexibility over visual representation (result graphics and callouts) of the result.

In ArcGIS Server 10, each result can have a callout on the map that shows detailed information. A callout is the collaborative work of the client and server. The client sends out an XMLHttpRequest that requests MapTip information be sent to the server whenever necessary. By default, the cacheFeaturesOnBrowser property of the WebMap instance is enabled for better performance. All results are stored on the client side (browser). The AJAX request for results is only sent when results are added or deleted.
On the server side,  a single GraphicsResource instance holds all the results, while a Phaselistener listens for incoming MapTip requests. After receiving a request, the listener asks for the generation of an XML file containing the result feature classes based on layer information and the results held in GraphicsResource. The server then sends back an AJAX response with MapTip results. When the client receives the response, it parses the information in it, stores the results information, and draws updated results on the map. When you trigger a MapTip event (for example, hovering the mouse over the result area), the client reacts accordingly (that is, updates result graphics or shows the callout) based on the stored result information.
The interaction with the callout is accomplished with JavaScript. The following illustration shows the architecture used in adf.MapTip.js:
 
Classes
The following classes are used when dealing with callouts on the client:
  • adf.MapTip(EsriMapTip)—The core of the MapTip callout. The most important classes it uses are adf.Callout (EsriCallOut), MapTipElement, Feature, and CalloutNode. It manipulates all MapTip behavior, such as showing the callout window or hiding the callout window.
  • adf.Map(EsriMap)—Has an instance of adf.MapTip(EsriMapTip).
  • adf.Callout(EsriCallOut)—Represents the callout window of the MapTip.
  • MapTipElement—Represents a result area on the map.  It is an SVG element in a FireFox or Chrome browser and Chrome, and a VML element in an Internet Explorer browser.
  • Feature—Contains feature information of the result. Its properties are Header, Content, Footer, Geometry, and Symbol. The Header, Content, and Footer information is what is shown in the callout window. The Geometry property describes the result location on the map, while the Symbol property defines symbolic features (for example, line color, opacity, and highlight marker). These properties are retrieved from an AJAX response from the server. To change a property, you have to do it on the server side.
  • CalloutNode—This class, actually a structure, contains MapTip information for current, active results. At any one time, there is only one CalloutNode instance; however, there can be many MapTipElements and Features since each result has a corresponding MapTipElement and Feature. CalloutNode has three attributes: pt (a Point instance representing the anchor point), sourceElement (a MapTipElement instance representing the result area), and feature (a Feature instance representing the result feature).
See the following diagram:
 
Client-side workflow
The following diagram shows the general workflow of a MapTip. Other methods, such as expand(), hide(), and collapse(), are used by the event handler to manipulate the MapTip box.

Customizing results manually

A callout is composed of two parts: a callout box and callout content. A callout box is created using JavaScript on the client side, while callout content is generated by the server and passed to the client side for rendering in the MapTip box.
Changing callout content
Callout content is composed of the following child nodes1:
  • Title
  • Body
  • Footer
To change the callout content, follow these steps:
  1. Create a well formatted XML file (put your customized HTML content in the Body node). See the following code example:
[XML] 
<header>Welcome to ${STATE_NAME}</header>
<body>
  <table style="[object]">
    <tody>
      <tbody>
        <tr>
          <td style="[object]">${STATE_NAME} has an area of ${AREA} square miles</td>
        </tr>
        <tr>
          <td>The population in year 1999 is ${POP1999}.
            <br/>
          </td>
        </tr>
        <tr>
          <td>The following is the state flag
            <img src="http://www.50states.com/flag/image/nunst020.gif"/>
          </td>
        </tr>
      </tbody>
    </tody>
  </table>
</body>
<footer/>
  1. Put the result generated from step 1 into the CDATA section as shown in the following code example:
[XML] 
<![CDATA[<header>Welcome to ${STATE_NAME}</header>
<body>
  <table style="[object]">
    <tr>
      <td style="[object]">${STATE_NAME} has an area of ${AREA} square miles.</td>
    </tr>
    <tr>
      <td>The population in year 1999 is ${POP1999}.
        <br/>
      </td>
    </tr>
    <tr>
      <td>The following is the state flag:
        <br/>
        <img src="http://www.50states.com/flag/image/nunst020.gif"/>
      </td>
    </tr>
  </table>
</body>
<footer/>
]]>
Find your target layer in your Web application faces-config.xml file, and put the text generated from step 2 into the calloutTemplate. The MapTip now has an eagle image in it as shown in the following screen shot:
 

Frequently asked questions

Question: Why is there no callout window when I do an identify task on a map with two or more resources?
Answer: It may be caused by the type of feature class; some feature class take up lots of memory. Increasing the memory of your application server is probably the best solution.
Question: Why isn’t there a callout for my result?
Answer: Make sure you have a layer definition for the layer to which the result belongs. Remember that a WMS service does not have a layer definition.
Question: How can I disable callouts?
Answer: You can disable callouts by configuring your JSF config file (faces-config.xml) as follows: 
  1. Open the file and navigate to mapContext->attributes->map. 
  2. Find the reference to the WebMap bean instance and add the enableInfoWindow property to the bean. 
  3. Set the value to False to disable callouts. 
By default, callouts are enabled.
See the following code example:
[XML] 
<managed-property>
  <property-name>enableInfoWindow</property-name>
  <value>false</value>
</managed-property>





Development licensing Deployment licensing
Server