Working with 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:
1) An HTML template that defines the DOM elements which comprise the structure
of the Layout
2) 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.
3) 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.
Creating an HTML Template
To specify the DOM elements that make up a MapTip’s Layout, a Web ADF developer
must create an HTML template. This template consists of markup placed in an
HTML file that is accessible to the web application at run time. Any valid
markup can be used in the template. To define the placement of the MapTip’s
title and content, as well as the application of many other MapTips properties,
Layouts support the use of key words that are populated at run time. These key
words must be placed inside curly braces and preceded by the @ symbol (e.g.
{@title}). The following key words are supported:
title - the title of the MapTip
content - the MapTip’s attribute display
callout_width - the width of the MapTip, as specified by the
MapTips control’s width property
maptip_height - the maximum height of the MapTip, as specified
by the MapTips control’s maxheight property
maptip_titleID - the DOM element ID of the element containing
the MapTip’s title
maptip_contentID - the DOM element ID of the element
containing the MapTip’s content
maptipID - the AJAX component ID of the MapTips control
A very simple template is shown below:
[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 this example, the MapTips title and content - specified by {@title} and
{@content} - are each placed in a div. The IDs of these divs are specified with
the key words maptip_titleID and maptip_contentID so that they are assigned
appropriate DOM element IDs at run time. Additionally, CSS classes called
"title" and "content" are applied to these divs by specification of the HTML
class attribute.
The title and content divs are embedded within a single container div. The
width of the container div is linked to the width of the MapTips control
through use of the callout_width key word. A different CSS class - called
"MapTipsStyle" - is applied to the container div.
Styling the HTML Template
The example template above specifies a parent CSS class of "MapTipsStyle", with
child classes called "title" and "content". These classes can be specified
using standard CSS and placed anywhere within the application, provided they
are available on the web page containing your custom MapTips. For instance,
these classes could be specified by placing the following style block in the
page’s head element:
[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>
Here a background image (BlueShadow.png) and the Verdana font are applied to
the MapTips container, and differing font sizes and weights are applied to the
MapTips title and content.
Including an Image for MapTips Arrows
A
custom MapTips Layout must include an image that contains the arrows that will
attach to the MapTip’s body and point to the feature that the MapTip is
describing. 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 MapTip’s 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 may be used for more than one
anchor point.
The image to the right is an example of a MapTip template image. Here, two
arrows are embedded in the image. Thus, the same arrow will be used for upper
and lower left anchor points, and the other arrow will be used for upper and
lower right anchor points. As mentioned previously, the image that contains 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, given its rounded corners, color
gradient, and shadow effect, is designed for this purpose. Note, however, that
the width and height of the image has been substantially decreased so that it
fits in this document; an actual template image should be at least as tall and
as wide as the tallest and widest MapTip your application will display.
Applying a Layout
Once a Layout’s components have been defined, the Layout can be applied
programmatically at run time through JavaScript. First, a simple JSON object
must be created that encapsulates the Layout’s components. This object must
specify the following properties:
1) templateUrl or template - if the HTML for the template is specified in a
separate HTML document, the templateUrl property should be specified with the
URL of that document. If the HTML is specified as a string, that string should
be specified as the value of the template property. For clarity and to minimize
the chance for errors, it is recommended that you specify the template in a
separate document and use the templateUrl property.
2) arrowUrl - the URL to the image that contains the MapTip’s arrows.
3) arrowBounds - an array that specifies the location of the arrows within the
arrow image and the positioning of the arrow relative to the MapTip’s body and
the feature described by the MapTip.
Creation of the simple JSON object can be implemented as follows:
[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
]
};
Here, the template property is null because the HTML template is taken 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 four anchor points. 
The first array specifies the bounds for the upper left (NW) arrow, the second
specifies the upper right (NE) arrow, the third the lower left (SW), and the
fourth the lower right (SE). Each array of arrow bounds must specify eight
members. In order of specification, these are:
1) startX - distance of the left edge of the arrow from the left edge of the
image containing the arrows
2) startY - distance of the top edge arrow from the top edge of the image
containing the arrows
3) width - width of the arrow
4) height - height of the arrow
5) offsetX - offset of the arrow from the side of the MapTip
6) offsetY - offset of the arrow from the top or bottom of the MapTip
7) bufferX - horizontal offset of the arrow from the center of the feature
8) bufferY - vertical offset of the arrow from the bottom or top of the feature
Once the JSON Layout object has been 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 global static defaultMapTipsTemplate
object:
[JavaScript]
ESRI.ADF.UI.defaultMapTipsTemplate.set_layout(layout);
To apply the Layout to a specific GraphicFeatureGroup (i.e. GraphicsLayer), use
the layout property on the GraphicFeatureGroup’s MapTips control:
[JavaScript]
var graphicFeatureGroup = $find(‘graphicFeatureGroupID’);
var mapTips = graphicFeatureGroup.get_mapTips();
mapTips.set_layout(layout);
Once the JSON Layout object is assigned to the layout property, the newly
specified MapTips Layout will be applied in the application.
Changing map tips at runtime
Web ADF MapTips are fully configurable at run time. Properties that
can be defined at design time via the MapTips Editor (above) can be modified
programmatically by setting properties on the web tier .NET MapTips object.
Furthermore, the Web ADF JavaScript Library classes that are used to render the
MapTips in the client browser can be used by developers 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 MapTips appearance and behavior.
Changing server control properties
Through manipulation of the MapTips’ server control properties, Web ADF
developers can dynamically define the appearance of the MapTips’ attribute
display and change the layer for which MapTips are currently shown. Such
modification must be done 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 MapTips appearance is done through the control’s LayerFormat property.
If the MapTips Editor dialog has been used to define a LayerFormat at design
time, then the LayerFormat property will be populated and can be modified
directly. Otherwise, retrieve the LayerFormat and associate it with the MapTips
control as follows:
[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]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, developers can define the MapTips appearance via
properties such as Title, Contents, and Fields. For further information on how
to use LayerFormats programmatically, see Working with
Layer Formats . Note that before retrieving a LayerFormat with the
above code, the MapTips::Layer property must be specified. Changing the MapTips
layer at run time requires specifying the Layer property. This property takes
the format <MapResourceManager ID>::<MapTips Resource
Name>::<MapTips Layer Name>, as shown below:
[C#]
MapTips1.Layer = string.Format("{0}::{1}::{2}", MapResourceManager1.ID,
mapTipsResourceName, mapTipsLayerName);
[VB]MapTips1.Layer = String.Format("{0}::{1}::{2}", MapResourceManager1.ID, _
mapTipsResourceName, mapTipsLayerName)
After modifying MapTips server control properties, the modifications need to be
applied. This is done by calling MapTips::RefreshMapTips followed by
Map::RefreshResource for the map resource used by the MapTips control. The code
for this is as follows:
[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]' 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 browser.
Changing 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,
which, when a GraphicFeature is moused over, retrieves that feature’s
attributes and displays them in a Web ADF Callout object. Each of these classes
can be manipulated at run time to alter various aspects of MapTips appearance
and behavior. For further information, see the discussion on
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. So 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. The following code demonstrates this:
[C#]// Construct JavaScript to retrieve the Web ADF JavaScript objects associated with the
// MapTips control. Note 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]' Construct JavaScript to retrieve the Web ADF JavaScript objects associated with the
' MapTips control. Note 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);
At this point, the JavaScript needs to be sent to the client browser to be
executed. If the above code is executing during application startup, this can
be done using Page::ClientScript::RegisterStartupScript. If the code is
executing during an asynchronous callback or partial postback, the JavaScript
should be encapsulated in a Web ADF CallbackResult using the static method
CallbackResult.CreateJavaScript and added 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 in turn will
synchronize 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 re-drawn. To prevent this, add a handler for
the buddied Map’s ResourceRefreshed event to re-apply the modified client tier
properties. This can be done by adding the following 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]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
