Working with Web-tier graphics on the client

In this topic

About working with Web-tier graphics
Cross-tier graphics equivalencies
Enable client-side functionality for a GraphicsLayer
Retrieve a GraphicsLayer's corresponding GraphicFeatureGroup
Manipulate callouts on the Web-tier
Push Web-tier property changes to the client

About working with Web-tier graphics

While the Web Application Developer Framework (ADF) includes a rich set of custom graphic functionality for developers to leverage on the Web-tier, the Web ADF JavaScript library provides client-side graphic objects for accessing functionality that can only be made available on the client-tier. For more information, see Working with graphics and Graphics and MapTips.

Sometimes, the functionality offered by the Web ADF on the Web-tier or client-tier meets an application's requirements. When this is the case, isolate graphic manipulation logic to one tier to avoid unnecessary convoluted program flow.

In some situations, it might be necessary or advantageous to interact with the same set of graphics on the Web- and client-tiers. For example, consider a case where a tool needs to issue a query against a map service and display the features satisfying the query on the map. Furthermore, when the cursor hovers over one of these features, the feature's attributes must be shown in a tabular display located elsewhere on the page.

With the Web ADF, executing a query and converting the results to graphics can be easily done using Web-tier objects. Implementing functionality that executes when the cursor hovers over a graphic, requires interacting with graphics on the client-tier. The best solution requires creating graphics on the Web-tier and manipulating those graphics on the client-tier. This topic explains the key concepts a Web ADF developer needs to understand when implementing functionality to handle these situations.

Cross-tier graphics equivalencies

While the Web ADF graphics related objects available on the Web- and client-tiers do not implement all the same capabilities, they do contain many equivalent properties, methods, and events. For managing sets of graphics, the Web-tier ElementGraphicsLayer and FeatureGraphicsLayer classes correspond to the GraphicFeatureGroup object on the client-tier.

For individual graphics, the .NET DataRow and Web ADF GraphicElement Web-tier classes correspond to the GraphicFeature object client tier.

The following table shows the equivalencies between the members of these objects:

Tier	Client	Web
Object	GraphicFeatureGroup	FeatureGraphicsLayer	ElementGraphicsLayer
Member	get(Integer)	Rows.Item(Integer)
	add(GraphicFeature)	Add(Geometry)	Add(GraphicElement)
	ID: String	TableName: String
	getFeatureCount()	Rows.Count: Integer
	visible(): Boolean	Visible: Boolean
	clear()	Clear()
	symbol: Symbol	Renderer: IRenderer	N/A
	selectedSymbol: Symbol	SelectedRenderer:IRenderer	N/A
	highlightSymbol: Symbol	HighlightRenderer: IRenderer	N/A
	elementAdded	TableNewRow
	elementChanged	RowChanged
	elementRemoved	RowDeleted

Object	GraphicFeature	DataRow	GraphicElement
Member	attributes(String)	Item(String)	N/A
	geometry: Geometry	GraphicsLayer.GeometryFromRow()	Geometry: Geometry
	isSelected: Boolean	Item(GraphicsLayer.IsSelectedColumn)
	symbol: Symbol	N/A	Symbol: Symbol
	selectedSymbol: Symbol	N/A	SelectedSymbol: Symbol
	highlightSymbol: Symbol	N/A	HighlightSymbol: Symbol

Enable client-side functionality for a GraphicsLayer

When a GraphicsLayer (element or feature) is instantiated and added to a graphics map resource on the Web-tier, equivalent client-tier graphic objects are not created by default. Instead, when the GraphicsLayer is rendered, the Web ADF creates an image of the layer's contents on the Web-tier, then blends this image with those of other layers on the map. When this is the case, client-side graphics functionality is not available for the layer.

To enable client-tier interaction, the GraphicsLayer class includes a RenderOnClient property, which is set to false by default. When this property is set to true, the Web ADF automatically creates a client-tier GraphicFeatureGroup and GraphicFeatures that mimic the properties of the Web-tier GraphicsLayer and its underlying DataTable. The Web ADF then leaves rendering the graphics to these client-side objects, which in turn, creates a Document Object Model (DOM) element to render each GraphicFeature.

Retrieve a GraphicsLayer's corresponding GraphicFeatureGroup

As previously mentioned, a GraphicFeatureGroup is the client-tier equivalent of a Web-tier GraphicsLayer. Therefore, to manipulate a GraphicsLayer's client-side representation, get a reference to the corresponding GraphicFeatureGroup. When the Web ADF creates a GraphicFeatureGroup for a GraphicsLayer, it uses the Asynchronous JavaScript and XML (AJAX) $create function (the group is registered as an AJAX component).

Registered AJAX components can be retrieved by passing the ID of the component to the AJAX $find function. To get the GraphicFeatureGroup's component ID, use the Web ADF Map control's GetGraphicsLayerClientID method.

The following code example shows these steps. The code example assumes it is executing during a callback or partial postback after which the Map's callback results are processed on the client.

[C#]


        // Get the component ID of the GraphicFeatureGroup corresponding to graphicsLayer by
// passing graphicsLayer to Map control's GetGraphicsLayerClientID method.
string graphicFeatureGroupID = Map1.GetGraphicsLayerClientID(graphicsLayer);
// Construct a JavaScript statement to retrieve the GraphicFeatureGroup having the ID.
string jsGetGraphicFeatureGroup = string.Format(
    "var graphicFeatureGroup = $find('{0}')", graphicFeatureGroupID);
// Instantiate a callback result that executes the JavaScript.
ESRI.ArcGIS.ADF.Web.UI.WebControls.CallbackResult
    getGraphicFeatureGroupCallbackResult =
    ESRI.ArcGIS.ADF.Web.UI.WebControls.CallbackResult.CreateJavaScript
    (jsGetGraphicFeatureGroup);
// Add the callback result to the Map's collection.
Map1.CallbackResults.Add(getGraphicFeatureGroupCallbackResult);

[VB.NET]


        ' Get the component ID of the GraphicFeatureGroup corresponding to graphicsLayer by
' passing graphicsLayer to the Map control's GetGraphicsLayerClientID method.
Dim graphicFeatureGroupID As String = Map1.GetGraphicsLayerClientID(graphicsLayer)
' Construct a JavaScript statement to retrieve the GraphicFeatureGroup having the ID.
Dim jsGetGraphicFeatureGroup As String = _
                                         String.Format("var graphicFeatureGroup = $find('{0}')", graphicFeatureGroupID)
' Instantiate a callback result that executes the JavaScript.
Dim getGraphicFeatureGroupCallbackResult As _
    ESRI.ArcGIS.ADF.Web.UI.WebControls.CallbackResult = _
    ESRI.ArcGIS.ADF.Web.UI.WebControls.CallbackResult.CreateJavaScript( _
    jsGetGraphicFeatureGroup)
' Add the callback result to the Map's collection.
Map1.CallbackResults.Add(getGraphicFeatureGroupCallbackResult)

When you have a client-tier reference to GraphicFeatureGroup, you can use all the functionality provided by the Web ADF JavaScript library to manipulate it and its contents. However, the GraphicFeatureGroup is synchronized with the Web-tier DataTable underlying the corresponding GraphicsLayer, when the map resource containing the layer is refreshed on the Web-tier (that is, by calling Map.RefreshResource).

This means that the properties stored in this table—geometries, attributes, and whether graphics are selected—overwrite their client-side equivalents when the resource is refreshed. Therefore, avoid client-side manipulation of members that have equivalents on the corresponding Web-tier DataTable (for example, geometry). Otherwise, properties of graphics established on the client-tier can be lost unexpectedly.

Manipulate callouts on the Web-tier

One of the most common uses of client-tier graphics functionality is to display a callout containing attribute related information when the cursor hovers over a feature. When a GraphicsLayer is created on the Web-tier and RenderOnClient is set to true, callouts containing member graphics' attribute information show by default when the cursor is hovered over a member graphic. The Web ADF MapTips, QueryAttributesTask, and SearchAttributesTask controls leverage this functionality to display graphics with callouts.

The contents of these callouts can be modified by using the ApplyTitleTemplate and ApplyContentsTemplate methods of the GraphicsLayer class. The parameter passed to ApplyTitleTemplate determines the callout's initial display, while the parameter passed to ApplyContentsTemplate determines what shows when the callout is clicked. The parameters to these methods are strings containing the Hypertext Markup Language (HTML) elements and fields to render. For more information on how to use template strings, see Working with layer formats.

Some situations can require that client tier graphic functionality is available without callouts. For example, the attributes of graphics when hovered over are shown in a table elsewhere on the page; therefore, you do not want those attributes to also show in a callout. To address this situation, the GraphicsLayer object has an EnableCallout property. To disable callouts for a GraphicsLayer that has RenderOnClient set to true, set EnableCallout to false.

Push Web-tier property changes to the client

As previously mentioned, the graphics properties stored on a Web-tier DataTable are automatically pushed to the corresponding client-tier GraphicFeatureGroup when the map resource containing the graphics refreshes. For properties that are not stored in the underlying DataTable, such as MapTips templates and symbology, passing Web-tier modifications to the client requires setting the GraphicsLayer.ForceFullClientGraphicsRefresh property to true before refreshing the resource.

Setting this property to true and refreshing the resource, overwrites all the properties of the corresponding client-tier GraphicFeatureGroup with their Web-tier equivalents. As a result, to modify properties that are not captured in the GraphicsLayer's underlying DataTable, isolate these modifications to the client- or Web-tier.

Implementing an application that modifies these properties on the client-tier (in some situations) and on the Web-tier (in other situations) unnecessarily convolutes the application's architecture causing graphic properties to unexpectedly be overwritten.