Dynamic resources

In this topic

About dynamic resources

The Web Application Developer Framework (ADF) JavaScript library contains components that provide limited, yet effective, access to layers within a map on the client. The Map control maintains a collection of layers that represent map resources present on the map. In most cases, each layer on the client represents a map resource on the server (Web tier). Properties in the layer collection, and individual layers, provide access to extent, spatial reference, opacity, and visibility. Public events enable you to determine when a layer is added, removed, or changed.
The following simple object model diagram (OMD) illustrates the relationships among the Map component, its LayerCollection, and the different types of layers available on the client:

AdfMapHandler

Each non-cached (dynamic) map resource on the server can be represented by an AdfMapHandler instance on the client. The AdfMapHandler type is unique in that it stores a reference to the ADF MapHandler (an ASP.NET Hypertext Transfer Protocol [HTTP] Handler) used to render map images for non-cached service without iterating through the page life cycle. For more information about the ADF MapHandler, see Map control.

AdfTileHandler and AdfTileDirectAccess

Cached map resources on the server can be represented by an AdfTileHandler or AdfTileDirectAccess instance on the client. The type is determined by access to the map cache from the client. If a public virtual directory is available and provides access to map cache tiles, AdfTileDirectAccess is used. If a public virtual cache directory is not available to the client, the Web ADF TileHandler (an ASP.NET HTTP Handler) is used via an AdfTileHandler instance. In general, accessing map cache tiles using a public virtual directory is preferred since only one Web request per tile is required (as opposed to two for AdfTileHandler—one to the handler and two to the map cache tile). The AdfTileDirectAccess type is preferred for best performance.
Adding a layer (resource) to the map at run time using only the architecture provided by the ADF JavaScript library is possible. The layer (or resource) is created, added, and maintained solely on the client in browser memory (no complimentary Web-tier map resource is maintained). Since the AdfTileDirectAccess type provides the best option for leveraging pure browser logic when accessing map data, it is used in this example.
Since AdfTileDirectAccess accesses map cache tiles directly, you must provide the appropriate information to access and navigate the cache. The key to success is ensuring you have the correct cache information and the algorithm necessary to determine the uniform resource locators (URLs) to cache tiles.
The following code example shows how to create an AdfTileDirectAccess instance and insert it below other layers in a map's layer collection. This code can be called by any event in the browser, such as a click event on a button.
[HTML] 
function addAGSOnlineLayerToMap()
{ 
 var map = $find(mapID);
 var layercollection = map.get_layers();
 layercollection.insert($create(ESRI.ADF.Layers.AdfTileDirectAccess,{
  "id":"Map1_Shaded Relief",
  "serverUrl":"http://services.arcgisonline.com/cache_wc/ESRI_ShadedRelief_World_2D/Layers/_alllayers",
  "extent":new ESRI.ADF.Geometries.Envelope(-180,-90,180,90),
  "tileOrigin":new ESRI.ADF.Geometries.Point(-180,90),
  "imageFormat":"jpg",
  "tileUrlGeneratorFunction":arcgisVirtualDirectoryTileUrlGenerator_jpg,
  "opacity":1,
  "levels":
  [new ESRI.ADF.Layers.LevelInfo(512,512,4,8,0.087890625,0.087890625,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,8,16,0.0439453125,0.0439453125,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,16,32,0.02197265625,0.02197265625,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,32,64,0.010986328125,0.010986328125,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,64,128,0.0054931640625,0.0054931640625,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,128,256,0.00274658203125,0.00274658203125,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,256,512,0.001373291015625,0.001373291015625,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,512,1024,0.0006866455078125,0.0006866455078125,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,1025,2049,0.000343322753906249,0.000343322753906249,0,0),
  new ESRI.ADF.Layers.LevelInfo(512,512,2048,4096,0.000171661376953125,0.000171661376953125,0,0)],
  "visible":true}),0);
}
The following table shows the property descriptions for AdfTileDirectAccess:
AdfTileDirectAccess property
Description
id
Unique ID of the layer.
serverUrl
The root URL of the Web server on which the map cache tiles reside.
extent
The full extent of the cache in map units.
tileOrigin
The coordinate marking the upper left corner of the cache.
imageFormat
The image format of the cache tiles, which includes .gif, .jpg, .jpeg, .png8, .png24, and .png32.
tileUrlGeneratorFunction
The name of the function that generates a URL for a cache tile using the serverUrl (virtual root directory), level, row, and column. The function must be defined in the script before creating the AdfTileDirectAccess instance.
opacity
The opacity of the layer ranging from 0 (transparent) to 1 (opaque). For .png32 images, image transparency is used and layer opacity is ignored.
levels
A collection of LevelInfo instances. Each LevelInfo represents a scale (level of detail) at which cache tiles are available.
visible
Determines if the layer is visible (true) or not (false).
Constructing the tileUrlGeneratorFunction involves creating an equation that uses the level, row, and column to retrieve a cache tile. The level, row, column, and serverUrl are provided to the function when the layer is rendered (such as when it is added to a map's layer collection), when the map extent changes, or when a map is refreshed. The following code example shows the equation that is used to determine which map tile to retrieve from an ArcGIS Online or ArcGIS Server service:
[HTML] 
function pad(toPad, padding, totalLength, padLeft){
    if (toPad.length < totalLength){
        if (padLeft) toPad = padding + toPad;
        else toPad = toPad + padding;
    }
    if (toPad.length >= totalLength) 
        return toPad;
    return pad(toPad, padding, totalLength, padLeft);
}
function arcgisVirtualDirectoryTileUrlGenerator_jpg(level, column, row, vdir){
    var sLevel = 'L' + pad(level.toString(), '0', 2, true);
    var sRow = 'R' + pad(row.toString(16), '0', 8, true);
    var sColumn = 'C' + pad(column.toString(16), '0', 8, true) + '.jpg';
    return vdir + '/' + sLevel + '/' + sRow + '/' + sColumn;
}
These functions must be located on the page before creating the AdfTileDirectAccess instance that uses them. In addition, in this example, the map cache tiles are in a .jpg file format. If the ArcGIS for Server cache you are accessing uses a different format, change this to the appropriate value.
A comprehensive sample of ADF JavaScript techniques and capabilities is available in this Help system. For instructions and code, see the Common Custom JavaScript sample.


See Also:

Graphics and MapTips
Mapping
Web ADF JavaScript library