Dynamic resources

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

Each non-cached (dynamic) map resource on the server may 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 HTTP Handler) used to render map images for non-cached service without iterating through page lifecycle.   See the Map control discussion about Using the MapHandler for more information.

Cached map resources on the server may be represented by an AdfTileHandler or AdfTileDirectAccess instance on the client. Which 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, two to the map cache tile).  Thus utilizing the AdfTileDirectAccess type is preferred for best performance.

Adding a layer (resource) at runtime to the map 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 AdfTileDirectAccess type provides the best option for leveraging pure browser logic when accessing map data, it will be used as an example.   Since AdfTileDirectAccess is designed to access map cache tiles directly, you must provide the appropriate information required to access and navigate the cache. The key to success if making sure you have the correct cache information and the algorithm necessary to determine urls to cache tiles. The following code demonstrates creating a new AdfTileDirectAccess instance and inserting below other layers in a map's layer collection:

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);
}

This code may be called by any event in the browser, such as a click event on a button. The property descriptions for AdfTileDirectAccess are provided in the table below:

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.   Examples include: 'gif','jpg','jpeg','png8','png24','png32'

tileUrlGeneratorFunction
The name of the function which will generate a url for a cache tile using the serverUrl (virtual root directory), level, row, and column. The function must be defined in script before creating the AdfTileDirectAccess instance.

opacity The opacity of the layer ranging from 0 (transparent) to 1 (opaque).  Note that for png32 images, image transparency is used and layer opacity will be ignored.

levels A collection of LevelInfo instannces.   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 which 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 provides an example illustrating the an equation used to determine which map tile to retrieve from an ArcGIS Online or ArcGIS Server service:

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. Examples include: 'gif','jpg','jpeg','png8','png24','png32'
tileUrlGeneratorFunction	The name of the function which will generate a url for a cache tile using the serverUrl (virtual root directory), level, row, and column. The function must be defined in script before creating the AdfTileDirectAccess instance.
opacity	The opacity of the layer ranging from 0 (transparent) to 1 (opaque). Note that for png32 images, image transparency is used and layer opacity will be ignored.
levels	A collection of LevelInfo instannces. 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).

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;
}

Note, these two functions must be located in the page before creating the AdfTileDirectAccess instance that uses them. In addition, this solution assumes the map cache tiles are in JPEG format (.jpg). If the ArcGIS Server cache you wish to access uses a different format, this value will need to change to the appropriate value.

A comprehensive sample of ADF JavaScript techniques and capabilities is available within this help system. See the Common Custom JavaScript sample for instructions and code.