Working with layer formats

In this topic

About working with layer formats

The Web Application Developer Framework (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 layer definition properties that can be defined interactively at design time in Visual Studio and ArcGIS Server Manager for map service layers. For more information, see MapResourceManager control and Working with the MapResourceManager control.
With LayerFormats, you can also define custom renderers and layer definition properties of dynamically generated GraphicsLayers, which cannot be done interactively.
 

Retrieving LayerFormats

The Web ADF provides methods to retrieve LayerFormats. While the most appropriate method for your situation depends on factors, such as the variables available in the current scope, the type of object that you want to specify for the LayerFormat (for example, a MapTips control, a feature layer in a map service, and so on), and the status of that object's initialization, and so on. The following discusses the two basic retrieval scenarios:
  • Scenario 1—Modify the appearance of MapTips created by a Web ADF MapTips control. Get the LayerFormat reference as shown in 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);
[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)
  • Scenario 2—Specify the LayerFormat for a layer on the map. If the layer is a feature (that is, map service) layer, this defines the rendering and attribute display of query results derived from that layer (for example, QueryAttributesTask results). In this case, the rendering of the layer is not affected. If the layer is a graphics layer, defining the LayerFormat determines the rendering and attribute display of the layer.

    The difference in how a LayerFormat interacts with feature and graphics layers can be explained by the fact that LayerFormats only affect graphics layers. Considering that, when results contain geometry, they are encapsulated in graphics layers. Therefore, when you specify a LayerFormat for a feature layer, you are specifying a LayerFormat for any results graphics layers derive from that feature layer. In both cases—with graphics layers and feature layers—the specified LayerFormat is applied to a graphics layer. In either case, you can retrieve the LayerFormat. See the following code example:
[C#] 
ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat layerFormat =
    ESRI.ArcGIS.ADF.Web.UI.WebControls.LayerFormat.FromMapResourceManager
    (MapResourceManager1, resourceName, layerID);
[VB.NET] 
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 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 appear when you hover the cursor over them. To specify either of these properties, initialize a Web ADF renderer and assign it to the necessary property.
Currently, simple renderers are only supported.
The following code example 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.NET] 
' 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 an attribute display

With ArcGIS Server, you can show feature attributes via MapTips callouts and TaskResults nodes out-of-the-box. You can customize these default attribute displays extensively at design time through dialog boxes in Visual Studio and ArcGIS Server Manager. However, what if the necessary appearance of MapTips or TaskResult nodes is not known until run time? To handle this situation, the LayerFormat object provides 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 is what you need, but your application requires the display of different fields and aliases in different runtime 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 (the default), the fields and aliases defined by the Fields property determines those displayed.
The following code example shows 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.NET] 
' 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 following illustrations show the effect of executing the preceding code example on a LayerFormat retrieved from the USA_Data service Cities layer. This service was created by publishing the USA_Data .mxd file included with the ArcGIS Server developer kit.
The illustration on the left shows the default MapTips callout on a result created by a QueryAttributesTask and the illustration on the right shows the same result after executing the preceding code example.

Working with title and contents properties

If your application requires complete customization of attribute displays, specify 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 MapTips or TaskResults node and the Contents property defines what is shown when the MapTips or TaskResults node is expanded. When defining these properties, use standard Hypertext Markup Language (HTML) tags to define formatting and field names enclosed in curly brackets to specify where field values are substituted. The following code example shows how this is 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.NET] 
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 following illustrations show how executing the preceding code example on a LayerFormat retrieved from the USA_Data service Cities layer affects the attribute display results created by a QueryAttributesTask. The illustrations on the left show a result's MapTips and TaskResults node before executing the code and 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 in the Title and Contents properties. To do this, place the necessary JavaScript code inside a call to "eval" enclosed in double curly brackets.
See the following illustrations and code example; the code example was used to modify the LayerFormat for the USA_Data service Counties layer:

[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.NET] 
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

When you specify the properties of a LayerFormat, ensure that those properties are applied. See the following code example if you have defined the LayerFormat for a MapTips control:
[C#] 
MapTips1.RefreshMapTips();
Map1.RefreshResource(MapTips1.ResourceName);
[VB.NET] 
MapTips1.RefreshMapTips()
Map1.RefreshResource(MapTips1.ResourceName)
If you have defined the LayerFormat for a graphics layer, use the following code example:
[C#] 
layerFormat.Apply(graphicsLayer);
graphicsLayer.ForceFullClientGraphicsRefresh = true;
Map1.RefreshResource(graphicsResourceName);
[VB.NET] 
layerFormat.Apply(graphicsLayer)
graphicsLayer.ForceFullClientGraphicsRefresh = True
Map1.RefreshResource(graphicsResourceName)
If you have specified the LayerFormat for a feature layer, further code is not necessary. Subsequent results derived from the layer reflects the defined properties.


See Also:

MapResourceManager control
Working with the MapResourceManager control
MapTips control
Working with the MapTips control