Working with the MapTips control


In this topic


Set title and contents using HTML

The content displayed by a map tip at runtime is defined with the LayerFormat's Title and Contents sections.  In general, the Title defines the text content in the map tip callout and Contents define the text content rendered in the body of the map tip callout.  The diagram below shows the location of the Title and Content sections in a map tip at runtime.  Note that the Title is visible when you hover over a map tip, while the Contents are visible upon click of a map tip.
MapTips Runtime Example
Both the Title and Contents can be defined at design-time via the MapTips property page or smart tags in the design view of a page.   In either case, the Records tab in the Map Tips Expression Editor provides a dialog to use default formatting (fields as argument\value pairs) or custom formatting using a rich text editor or explicitly modification of the HTML content.  The Title and Contents text must contain valid HTML content.   Valid HTML is defined by the browser in which the HTML is rendered and generally includes raw text as well as elements and their events and attributes.   It is important to note that double-quotes are not permitted in the text of the Title or Contents.
For more information about the MapTips control, see MapTips control.
See the following screen shot that shows the MapTips Expression Editor dialog box: 
MapTips Expression Editor  
If creating a custom format, the Records tab in the Map Tips Expression Editor includes a drop-down list of available fields in the layer on which map tips will be constructed.   Select the field value you want to display in the Title or Contents and it will be inserted into the respective section.  The field name bounded by curly brackets is inserted into the design-time content, for example "{CITY_NAME}", and will be replaced with the field value for the map tip at runtime.  

The following example illustrates how to define map tip Title and Contents based on field values and HTML capabilities.  The Title and Contents text is listed on the left while the runtime example of a map tip using this custom format is displayed on the right.  Note that carriage returns in the Map Tips Expression Editor are respected, while white-space is ignored.  Also keep in mind that the properties of the callout containing map tip content cannot be changed by modifying the MapTips control, Title or Contents.  By default the callout window has a light gray background color for the Title, a white background color for the Contents, and a dark gray border.

The Title includes two fields from the map tip layer and defines some style properties of the text in the header, such as font name, size and text color.    

The Contents section contains four items of interest.   

1) An img element that derives its source url from a field in the map tip layer.   In this case, the image is assumed to exist in the root folder for the Web application.  The style attribute defines how the image is presented in the body.

2) A labeled value of the POPULATION field.  This content is double-spaced to the right by including the HTML entity references for two non-breaking spaces " ".  Note that the style properties of the img element in the first item dictate where this item is located.

3) A break that clears all previous alignment settings and starts the next element below the previous element.  

4) Text and a hyperlink that searches www.google.com  for the occurrence of the field values (city name and state abbreviation) defined.  A div element defines a style that disables wrapping due to white space in the text or hyperlink content in the page.

Custom map tips layouts

A MapTip Layout is the portion of a MapTip that contains its title and content. A Layout consists of three components:
  • An HTML template that defines the DOM elements which comprise the structure of the Layout
  • CSS to style the DOM elements of the HTML template. The CSS can be defined inline within the HTML template, in style blocks on the page displaying the MapTips, or in separate stylesheet files.
  • An image that contains the MapTip arrows. This image can also be used as a background for the MapTip.
By defining these components, Web ADF developers can fully customize a MapTip’s Layout. Once the components are defined, they can be easily applied in JavaScript through the Web ADF’s layout property. A Layout can be set for all the MapTips in a web page by calling the global static method ESRI.ADF.UI.defaultMapTipsTemplate.set_layout, or to a specific GraphicFeatureGroup by setting the layout property on that GraphicFeatureGroup’s MapTips control. By specifying a MapTip’s title, content, and Layout, Web ADF developers can completely customize the appearance of their application’s MapTips.

Create an HTML template

To specify DOM elements that make up a MapTips' layout, create an HTML template. The template consists of markup placed in an HTML file that is accessible to the Web application at runtime. Any valid markup can be used in the template. To define the placement of the MapTips' title and content, and the application of other MapTips' properties, the layout supports the use of keywords that are populated at runtime. Place these keywords inside curly brackets preceded by the @ symbol, for example {@title}. The following keywords are supported:
  • title—MapTips' title
  • content—MapTips' attribute display
  • callout_width—MapTips' width specified by the MapTips control’s width property
  • maptip_height—MapTips' maximum height specified by the MapTips control’s maxheight property
  • maptip_titleID—DOM element ID of the element containing the MapTips' title
  • maptip_contentID—DOM element ID of the element containing the MapTips' content
  • maptipID—Asynchronous JavaScript and XML (AJAX) component ID of the MapTips' control
See the following code example that shows a basic template:
[HTML]
<div class="MapTipsStyle" style="width:{@callout_width}; position:relative;">
  <div id="{@maptip_titleID}" class="title">{@title}</div>
  <div id="{@maptip_contentID}" class="content">{@content}</div>
</div>
In the preceding code example, the MapTips' title and content—specified by {@title} and {@content}—are placed in a div tag. The IDs of these div tags are specified with the maptip_titleID and maptip_contentID keywords; therefore, they are assigned appropriate DOM element IDs at runtime. CSS classes (.title and .content) are applied to these div tags by specification of the HTML class attribute.
The title and content div tags are embedded within a single div container. The width of the div container is linked to the width of the MapTips control by using the callout_width keyword. A different CSS class (.MapTipsStyle) is applied to the div container.

Style the HTML template

The preceding code example shows a parent .MapTipsStyle CSS class with child .title and .content classes. These classes can be specified using standard CSS and placed anywhere within the application, if they are available on the Web page containing your custom MapTips. For example, these classes can be specified by placing the following HTML style block in the page's head element. In the code example, the background image (BlueShadow.png) and the Verdana font are applied to the MapTips container, and different font sizes and weights are applied to the MapTips' title and content:
[HTML]
<style type="text/css">
  .MapTipsStyle { background-image:url(Images/BlueShadow.png); 
 font-family:Verdana; }
.MapTipsStyle .title { font-size:10pt; font-weight:bolder; }
.MapTipsStyle .content { font-size:8pt; }
</style>

Include an image for map tips arrows

A custom MapTips' layout must include an image containing arrows that attach to the MapTips' body and point to the feature that the MapTips describe. Since Web ADF MapTips open to the left or right and expand up or down, the MapTips control supports using up to four different arrows—one each for when the MapTips' anchor point is in the upper left, upper right, lower left, and lower right positions. However, specifying four distinct arrows is not required; where appropriate, the same arrow can be used for more than one anchor point.
The following image shows an example of a MapTips template image. Two arrows are embedded on the image; therefore, the same arrow is used for upper and lower left anchor points, and the other arrow is used for upper and lower right anchor points.
The image containing the arrows can also be used as the MapTips background by specifying the image's URL in the CSS for the template. The image shown with rounded corners, color gradient, and shadow effect, was created for this purpose. The image's width and height has been substantially decreased to fit in this topic; an actual template image can be at least as tall and as wide as the tallest and widest MapTips your application displays.

Apply layout programmatically

Once a layout's components have been defined, apply the layout programmatically at runtime with JavaScript. Create a basic JavaScript Object Notation (JSON) object that encapsulates the layout's components. Specify the following properties for the JSON object:
  • templateUrl or template—If the HTML for the template is specified in a separate HTML document, specify the templateUrl property with the URL of that document. If the HTML is specified as a string, specify that string as the value of the template property. For clarity and to minimize errors, specify the template in a separate document using the templateUrl property.
  • arrowUrl—URL to the image that contains the MapTips' arrows.
  • arrowBounds—Array that specifies the location of the arrows within the arrow image, the positioning of the arrow relative to the MapTips' body, and the feature described by the MapTips.
See the following code example that shows the implementation of the basic JSON object:
[JavaScript]
var layout = {
    'template': null, 'templateUrl': 'Templates/MapTipsStyle1.htm', 'arrowUrl':
        'Images/BlueShadow.png', 'arrowBounds': [
    // startX,startY,width,height,offsetX,offsetY,bufferX,bufferY.
    [954, 921, 16, 16,  - 1,  - 7, 5,  - 7],  // NW—Upper left.
    [939, 921, 16, 16,  - 15,  - 7, 5,  - 7],  // NE—Upper right.
    [954, 921, 16, 16,  - 1,  - 23, 5,  - 7],  // SW—Lower left.
    [939, 921, 16, 16,  - 15,  - 23, 5,  - 7] // SE—Lower right.
    ]
};
In the preceding code example, the template property is null because the HTML template is from another document, as specified by the templateUrl property. The arrowUrl property references the location of the image containing the arrows. The arrowBounds property is an array containing four arrays, each of which specifies the bounds for the arrow at one of the following anchor points. 
  • First array—Specifies the bounds for the upper left (NW, northwest) arrow.
  • Second array—Specifies the upper right (NE, northeast) arrow.
  • Third array—Specifies the lower left (SW, southwest) arrow.
  • Fourth array—Specifies the lower right (SE, southeast) arrow.
Each array of arrow bounds must specify eight members. The following table shows each member in the order of specification:
Member
Description
startX
Distance for the left edge of the arrow from the left edge of the image containing the arrows.
startY
Distance for the top edge arrow from the top edge of the image containing the arrows.
width
Width of the arrow.
height
Height of the arrow.
offsetX
Offset of the arrow from the side of the MapTips.
offsetY
Offset of the arrow from the top or bottom of the MapTips.
bufferX
Horizontal offset of the arrow from the center of the feature.
bufferY
Vertical offset of the arrow from the bottom or top of the feature.
The following illustrations show each array of arrow bounds and specified members:
 
When the JSON layout object is created, it can be applied by passing it to the Web ADF's layout property. To apply the layout to all MapTips on the page, use the layout property on the defaultMapTipsTemplate global static object. See the following code example:
[JavaScript]
ESRI.ADF.UI.defaultMapTipsTemplate.set_layout(layout);
To apply the layout to a specific GraphicFeatureGroup (that is, GraphicsLayer), use the layout property on the GraphicFeatureGroup's MapTips control. See the following code example:
[JavaScript]
var graphicFeatureGroup = $find('graphicFeatureGroupID');
var mapTips = graphicFeatureGroup.get_mapTips();
mapTips.set_layout(layout);
When the JSON layout object is assigned to the layout property, the newly specified MapTips layout is applied in the application.

Change map tips at runtime

Web ADF MapTips are fully configurable at runtime. Properties that can be defined at design time on the MapTips editor can be modified programmatically by setting properties on the Web tier .NET MapTips object.
The Web ADF JavaScript library classes used to render MapTips in the client Web browser can be used to dynamically configure MapTips on the client. While these JavaScript objects provide configuration options that overlap those available through the Web tier MapTips object, they also allow greater control over the MapTips' appearance and behavior.

Change server control properties

Through manipulation of the MapTips' server control properties, you can dynamically define the appearance of the MapTips' attribute display and change the layer for which MapTips are currently shown. Do the modification after the control's Init phase (during or after page load). If the changes are made during an asynchronous callback or partial postback, the callback results of the map associated with the MapTips control must be returned to the client.
Altering a MapTips' appearance is done through the control's LayerFormat property. If the MapTips Editor dialog box is used to define a LayerFormat at design time, the LayerFormat property is populated and can be modified directly. Otherwise, retrieve the LayerFormat and associate it with the MapTips control. See the following code example:
[C#]
ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat layerFormat =
    ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat.FromMapResourceManager
    (MapResourceManager1, MapTips1.ResourceName, MapTips1.LayerID);
MapTips1.LayerFormat = layerFormat;
[VB.NET]
Dim layerFormat As ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat = _
                                                                    ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat.FromMapResourceManager( _
                                                                    MapResourceManager1, MapTips1.ResourceName, MapTips1.LayerID)
MapTips1.LayerFormat = layerFormat
With the LayerFormat, you can define the MapTips' appearance via properties such as title, contents, and fields. For more information on how to use LayerFormats programmatically, see Working with layer formats.
Before retrieving a LayerFormat with the preceding code example, specify the MapTips::Layer property. Changing the MapTips' layer at runtime requires specifying the Layer property. The Layer property's format is <MapResourceManager ID>::<MapTips Resource Name>::<MapTips Layer Name>. See the following code example: 
[C#]
MapTips1.Layer = string.Format("{0}::{1}::{2}", MapResourceManager1.ID,
    mapTipsResourceName, mapTipsLayerName);
[VB.NET]
MapTips1.Layer = String.Format("{0}::{1}::{2}", MapResourceManager1.ID, _
                 mapTipsResourceName, mapTipsLayerName)
After modifying the MapTips' server control properties, apply the modifications by calling MapTips::RefreshMapTips followed by Map::RefreshResource for the map resource used by the MapTips control. See the following code example:
[C#]
// Refresh the MapTips control to commit the changes made to the control's state
MapTips1.RefreshMapTips();
// Refresh the resource on which the MapTips are shown so that the resource picks up
// the changes.
Map1.RefreshResource(MapTips1.ResourceName);
[VB.NET]
' Refresh the MapTips control to commit the changes made to the control's state
MapTips1.RefreshMapTips().
' Refresh the resource on which the MapTips are shown so that the resource picks up
' the changes.
Map1.RefreshResource(MapTips1.ResourceName)
If changes were made during an asynchronous callback or partial postback, the map's callback results must then be returned to the client so the changes are processed by the Web browser.

Change client control properties

The Web ADF relies on several JavaScript library classes to render MapTips in the client browser. GraphicFeatureGroups are used to manage the graphics for which MapTips are displayed. Each graphic is encapsulated in a GraphicFeature object.
Each GraphicFeatureGroup has an associated MapTips JavaScript control that when a GraphicFeature is hovered over with the cursor, retrieves that feature's attributes and displays them in a Web ADF callout object. Each of these classes can be manipulated at runtime to alter various aspects of the MapTips' appearance and behavior. For more information, see Graphics and MapTips.
Manipulating these objects requires getting a reference to them. On the client, the starting point for these object references is the GraphicFeatureGroup on which the MapTips are displayed. A GraphicFeatureGroup provides references to individual GraphicFeatures and the associated MapTips client control. The associated callout can be retrieved from the MapTips client control. In the Web tier, the client-side ASP.NET AJAX component ID of the GraphicFeatureGroup is provided via the MapTips.GraphicsLayerClientID property. Therefore, the GraphicFeatureGroup can be retrieved by passing the content of this Web tier property to the client and inserting it into a call to the ASP.NET AJAX $find function. See the following code example that shows this procedure:
[C#]
// Construct JavaScript to retrieve the Web ADF JavaScript objects associated with the
// MapTips control. This code assumes the graphicFeatureGroup, graphicFeatureArray,
// mapTips, and callout variables have already been declared via client tier JavaScript.
string retrieveMapTipsJavaScript = @"
// Get the GraphicFeatureGroup on which MapTips are displayed. {0} will be replaced 
// below with the GraphicFeatureGroup's ASP.NET AJAX component ID.
graphicFeatureGroup = $find('{0}');
// Get the GraphicFeatures contained in the GraphicFeatureGroup and put them in an 
// array.
for (var i = 0; i < graphicFeatureGroup.getFeatureCount(); i++)
    graphicFeatureArray[i] = graphicFeatureGroup.get(i);
// Get the Web ADF JavaScript MapTips control.
mapTips = graphicFeatureGroup.get_mapTips();
// Get the Web ADF JavaScript callout defining the format of the MapTips.
callout = mapTips.get_callout();
";
// Insert the ASP.NET AJAX component ID of the MapTips' GraphicFeatureGroup.
retrieveMapTipsJavaScript = string.Format(retrieveMapTipsJavaScript,
    MapTips1.GraphicsLayerClientID);
[VB.NET]
' Construct JavaScript to retrieve the Web ADF JavaScript objects associated with the
' MapTips control.  This code assumes the graphicFeatureGroup, graphicFeatureArray,
' mapTips, and callout variables have already been declared via client tier JavaScript.
Dim retrieveMapTipsJavaScript As String = _
                                          "// Get the GraphicFeatureGroup on which MapTips are displayed. {0} " + vbNewLine + _
                                          "// will be replaced below with the GraphicFeatureGroup's ASP.NET " + vbNewLine + _
                                          "// AJAX component ID. " + vbNewLine + _
                                          "graphicFeatureGroup = $find('{0}'); " + vbNewLine + _
                                          "// Get the GraphicFeatures contained in the GraphicFeatureGroup and" + vbNewLine + _
                                          "// put them in an array" + vbNewLine + _
                                          "for (var i = 0; i < graphicFeatureGroup.getFeatureCount(); i++)" + vbNewLine + _
                                          " graphicFeatureArray[i] = graphicFeatureGroup.get(i); " + vbNewLine + _
                                          "// Get the Web ADF JavaScript MapTips control" + vbNewLine + _
                                          "mapTips = graphicFeatureGroup.get_mapTips();" + vbNewLine + _
                                          "// Get the Web ADF JavaScript Callout defining the MapTips format" + vbNewLine + _
                                          "callout = mapTips.get_callout();"
' Insert the ASP.NET AJAX component ID of the MapTips' GraphicFeatureGroup.
retrieveMapTipsJavaScript = String.Format(retrieveMapTipsJavaScript, _
                            MapTips1.GraphicsLayerClientID);
Send the JavaScript code to the client browser to be executed. If the preceding code example executes during application startup, this can be done using Page.ClientScript.RegisterStartupScript. If the code executes during an asynchronous callback or partial postback, encapsulate the JavaScript in a Web ADF CallbackResult using the static method, CallbackResult.CreateJavaScript, and add to the callback results collection of the control that initiated the asynchronous request.
When the extent of a Map control buddied to a MapTips control is changed, the MapTips control regenerates the GraphicsLayer on which the MapTips are shown to ensure that it only includes features in the new extent. This requires refreshing the map resource containing the GraphicsLayer, which synchronizes MapTips client tier properties with those stored in the Web tier. The result is that MapTips properties defined on the client can be overwritten when the MapTips GraphicsLayer is redrawn. To prevent this, add a handler for the buddied Map’s ResourceRefreshed event to re-apply the modified client tier properties. Do this by adding the following code example to the .aspx page's code-behind:
[C#]
protected void Page_Load(object sender, EventArgs e)
{
    // Add a handler to the map's ResourceRefreshed event.
    Map1.ResourceRefreshed += new MapResourceRefreshedEventHandler
        (Map1_ResourceRefreshed);
}

void Map1_ResourceRefreshed(object sender, ResourceRefreshedEventArgs args)
{
    // Check whether the resource being refreshed includes the MapTips GraphicsLayer.
    if (args.MapResource.Name == "ESRI ADF Layer Map Tips")
    {
        // Construct JavaScript to re-initialize client-side MapTips properties.
        string reApplyMapTipsPropsJavaScript = "<initialization JavaScript>";
        // Encapsulate the JavaScript in a CallbackResult.
        CallbackResult reApplyMapTipsPropsCallbackResult =
            CallbackResult.CreateJavaScript(reApplyMapTipsPropsJavaScript);
        // Add the CallbackResult to the map's collection so it will be processed on 
        // the client.
        Map1.CallbackResults.Add(reApplyMapTipsPropsCallbackResult);
    }
}
[VB.NET]
Protected Sub Map1_ResourceRefreshed(ByVal sender As Object, _
                                     ByVal args As ResourceRefreshedEventArgs) Handles Map1.ResourceRefreshed
' Check whether the resource being refreshed includes the MapTips GraphicsLayer.
If args.MapResource.Name = "ESRI ADF Layer Map Tips" Then
    ' Construct JavaScript to re-initialize client-side MapTips properties.
    String reApplyMapTipsPropsJavaScript = "<initialization JavaScript>"
    ' Encapsulate the JavaScript in a CallbackResult.
    CallbackResult reApplyMapTipsPropsCallbackResult = _
                                                       CallbackResult.CreateJavaScript(reApplyMapTipsPropsJavaScript)
    ' Add the CallbackResult to the map's collection so it will be processed on
    ' the client.
    Map1.CallbackResults.Add(reApplyMapTipsPropsCallbackResult)
End If
End Sub


See Also:

MapTips control
Working with layer formats
Graphics and MapTips