Working with layer formats

The Web ADF LayerFormat class provides a common endpoint to programmatically define the rendering and attribute display of MapTips, TaskResults, and GraphicsLayers. Through a LayerFormat, you have run time access to all the layer definition properties that can be defined interactively at design time in Visual Studio (see the MapResourceManager control) and ArcGIS Server Manager for map service layers.  And with LayerFormats, you can also define custom renderers and layer definition properties of dynamically generated GraphicsLayers, which cannot be done interactively.

Retrieving a LayerFormat

The Web ADF provides a variety of methods for retrieving LayerFormats. While the most appropriate method for your situation will depend on factors such as the variables available in the current scope, the type of object for which you wish to specify the LayerFormat (e.g. a MapTips Control, a feature layer in a map service, etc.), and the status of that object's initialization, there are two basic retrieval scenarios. These are explained below.

• Scenario 1:  You want to modify the appearance of MapTips that have been created by a Web ADF MapTips Control. In this case, you can get the LayerFormat reference as follows:
  
  [C#]

  ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat layerFormat =
    ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat.FromMapResourceManager(
    MapResourceManager1, MapTips1.ResourceName, MapTips1.LayerID);
  

  
  [VB]

  Dim layerFormat As ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat = _
    ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat.FromMapResourceManager( _
    MapResourceManager1, MapTips1.ResourceName, MapTips1.LayerID)
  

• Scenario 2: You want to specify the LayerFormat of a layer in the map. If the layer is a feature (i.e. map service) layer, this will define the rendering and attribute display of query results that are derived from that layer (e.g. QueryAttributesTask results). Note that, in this case, the rendering of the layer itself is not affected . On the other hand, if the layer is a graphics layer, then defining the LayerFormat will determine the rendering and attribute display of the layer. The difference in how a LayerFormat interacts with feature and graphics layers can explained by the fact that LayerFormats really only affect graphics layers. Consider that, when results contain geometry, they are encapsulated in graphics layers. So when you specify a LayerFormat for a feature layer, you are really specifying a LayerFormat for any results graphics layers derived from that feature layer. In both cases— with graphics layers and feature layers—the LayerFormat you specify is ultimately applied to a graphics layer. In either case, you can retrieve the LayerFormat as follows:
  
  [C#]

  ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat layerFormat =
    ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat.FromMapResourceManager(
    MapResourceManager1, resourceName, layerID);
  

  
  [VB]

  Dim layerFormat As ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat = _
    ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat.FromMapResourceManager( _
    MapResourceManager1, resourceName, layerID)
  

Specifying Renderers

The LayerFormat object provides two properties—Renderer and HighlightRenderer – that allow you to easily define the symbology for MapTips, TaskResults, and GraphicsLayers. The Renderer property defines the default appearance of the graphics associated with the LayerFormat, while HighlightRenderer specifies how these graphics will appear when the mouse cursor passes over them. To specify either of these properties, simply initialize a Web ADF Renderer and assign it to the desired property. Note that only simple renderers are currently supported. The code below shows how to specify a purple triangle as the LayerFormat's default symbology:


[C#]

// Initialize a Web ADF SimpleMarkerSymbol
ESRI.ArcGIS.ADF.Web.Display.Symbol.SimpleMarkerSymbol adfSimpleMarkerSymbol =
  new ESRI.ArcGIS.ADF.Web.Display.Symbol.SimpleMarkerSymbol();
adfSimpleMarkerSymbol.Color = System.Drawing.Color.Purple;
adfSimpleMarkerSymbol.Type = ESRI.ArcGIS.ADF.Web.Display.Symbol.MarkerSymbolType.Triangle;
adfSimpleMarkerSymbol.Width = 20;

// Initialize a Web ADF Renderer with the symbol
ESRI.ArcGIS.ADF.Web.Display.Renderer.SimpleRenderer adfSimpleRenderer =
  new ESRI.ArcGIS.ADF.Web.Display.Renderer.SimpleRenderer(adfSimpleMarkerSymbol);

// Use the renderer to specify the LayerFormat's default symbology
layerFormat.Renderer = adfSimpleRenderer;

[VB]

' Initialize a Web ADF SimpleMarkerSymbol
Dim adfSimpleMarkerSymbol As _
  ESRI.ArcGIS.ADF.Web.Display.Symbol.SimpleMarkerSymbol = _
  New ESRI.ArcGIS.ADF.Web.Display.Symbol.SimpleMarkerSymbol()
adfSimpleMarkerSymbol.Color = System.Drawing.Color.Purple
adfSimpleMarkerSymbol.Type = _
  ESRI.ArcGIS.ADF.Web.Display.Symbol.MarkerSymbolType.Triangle
adfSimpleMarkerSymbol.Width = 20

' Initialize a Web ADF Renderer with the symbol
Dim adfSimpleRenderer As _
  ESRI.ArcGIS.ADF.Web.Display.Renderer.SimpleRenderer = _
  New ESRI.ArcGIS.ADF.Web.Display.Renderer.SimpleRenderer( _
  adfSimpleMarkerSymbol)

' Use the renderer to specify the LayerFormat's default symbology
layerFormat.Renderer = adfSimpleRenderer

Customizing Attribute Display

With ArcGIS Server, you can display feature attributes via MapTips callouts and TaskResults nodes out-of-the-box. You can customize these default attribute displays extensively at design time through simple dialogs in Visual Studio and ArcGIS Server Manager. But what if the desired appearance of MapTips or TaskResult nodes won't be known until run time?  To handle such situations, the LayerFormat object provides developers programmatic server-side access to the format and contents of ArcGIS Server attribute displays.

Working with the Fields Property

If the default format of attribute displays suits your purpose, but your application requires the display of different fields and aliases in different run-time contexts, then you can meet your requirements by manipulating the FieldInfoCollection object referenced by the LayerFormat's Fields property. When the LayerFormat's UseDefaultTitleAndContents property is set to true (which it is by default), the fields and aliases defined by the Fields property determines those displayed. The code below illustrates using this property to set field visibilities and aliases.

[C#]

// Hide every field except for AREANAME, and
// give the AREANAME field an alias of "Name"
for (int i = 0; i < layerFormat.Fields.Count; i++)
{
  if (layerFormat.Fields[i].Name != "AREANAME")
    layerFormat.Fields[i].Visible = false;
  else
    layerFormat.Fields[i].Alias = "Name";
}

[VB]

' Hide every field except for AREANAME, and
' give the AREANAME field an alias of "Name"
For i As Integer = 0 To layerFormat.Fields.Count - 1
  If layerFormat.Fields(i).Name <> "AREANAME" Then
    layerFormat.Fields(i).Visible = False
  Else
    layerFormat.Fields(i).Alias = "Name"
  End If
Next

The figures below show the effect of executing this code on a LayerFormat retrieved from the Cities layer of the USA_Data service. This service was created by publishing the USA_Data mxd included with the ArcGIS Server DeveloperKit. The figure on the left shows the default MapTip callout on a result created by a QueryAttributesTask, while the figure on the right shows the same result after executing the code above.


 


Working with the Title and Contents Properties

If your application requires complete customization of attributes displays, you can do this by specifying the LayerFormat's Title and Contents properties. When the LayerFormat's UseDefaultTitleAndContents property is set to false, these properties completely define the format and contents of attribute displays. The Title property determines the title of a MapTip or TaskResults node, while the Contents property defines what is shown when the MapTip or TaskResults node is expanded. When defining these properties, use standard HTML markup to define formatting and field names enclosed in curly braces to specify where field values should be substituted. The code below illustrates how this can be done.

[C#]

layerFormat.Title = "<font style= 'color:red;font-weight:bold;'>{AREANAME}</font>";
layerFormat.Contents = "<a href='http://www.google.com/search?q={AREANAME}'>" +
  "{AREANAME}</a>, {ST}  is home to<i>{POP2000}</i> people";
layerFormat.UseDefaultTitleAndContents = false;

[VB]

layerFormat.Title = "<font style= 'color:red;font-weight:bold;'>{AREANAME}</font>"
layerFormat.Contents = "<a href='http://www.google.com/search?q={AREANAME}'>" + _
  "{AREANAME}</a>, {ST} is home to <i>{POP2000}</i> people"
layerFormat.UseDefaultTitleAndContents = False

The figures below illustrate how executing this code on a LayerFormat retrieved from the Cities layer of the USA_Data service affects the attribute display of results created by a QueryAttributesTask. The figures on the left show a result's MapTip and TaskResults node before executing the code, while the figures on the right show the same result after execution.




If your situation requires that some content of the attribute display be calculated dynamically, the Web ADF allows you to embed JavaScript directly in the Title and Contents properties. To do this, simply place the necessary JavaScript code inside a call to eval enclosed in double curly braces. See the code and figures below for an example. The example code was used to modify the LayerFormat of the Counties layer of the USA_Data service.

[C#]

layerFormat.Title = "<font style= 'color:green;font-weight:bold;'>{NAME}</font>";
layerFormat.Contents = "{NAME} County has a population per square mile of " +
  "{{eval(Math.round({POP2000}/{AREA}))}}";
layerFormat.UseDefaultTitleAndContents = false;

[VB]

layerFormat.Title = "<font style= 'color:green;font-weight:bold;'>{NAME}</font>"
layerFormat.Contents = "{NAME} County has a population per square mile of " + _
  "{{eval(Math.round({POP2000}/{AREA}))}}"
layerFormat.UseDefaultTitleAndContents = False

 

Applying Changes to LayerFormats

Once you've specified the properties of a LayerFormat, it's important to ensure those properties are applied. If you've defined the LayerFormat of a MapTips Control, this can be done with the code shown in the following snippet:

[C#]

MapTips1.RefreshMapTips();
Map1.RefreshResource(MapTips1.ResourceName);

[VB]

MapTips1.RefreshMapTips()
Map1.RefreshResource(MapTips1.ResourceName)

If you've defined the LayerFormat for a graphics layer, then use the following code:

[C#]

layerFormat.Apply(graphicsLayer);
graphicsLayer.ForceFullClientGraphicsRefresh = true;
Map1.RefreshResource(graphicsResourceName);

[VB]

layerFormat.Apply(graphicsLayer)
graphicsLayer.ForceFullClientGraphicsRefresh = True
Map1.RefreshResource(graphicsResourceName)

If you've specified the LayerFormat for a feature layer, no further code need be written. Subsequent results derived from the layer will reflect the properties defined.