Class adf.Map

Extends adf.Control.

Defined in: Map.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	adf.Map(id, containerNode, formId, width, height) The central class that renders map and other graphic elements, a simple ADF application could consist of one 'adf.Map' instance Create a new map instance inside of the given HTML container.

Field Summary
Field Attributes	Field Name and Description
	animateGridElements Turns on slide animation for elements that are positioned using map.placeElement() with map coordinates
	animateTransistions Show transition animation effects for pan and zoom operations.
	cacheClientFeatures Turns on client-side caching of web result features.
	callOut adf.Callout instance placed at a certain position of map.
	enableMapTips Turns the MapTips feature on and off
	extent Holds the current visible extent in map coordinates
	formId The id of the form this map control is bound to
	graphics The default adf.graphics.Element displayed over the map.
	graphicsId The id of `this.graphics` HTML element.
	graphicsZIndex The CSS z-index value for `this.graphics`.
	height The height of the map
	imageGrid An HTML DIV element which contains viewport's content[map images and graphic elements].
	isFuseGraphics When set to true, the web graphics content is fused with a dynamic map source
	level The current zoom level which maps to a particular map scale.
	mapTip 'adf.MapTip' instance used by map
	numLevels Represents the number of levels of detail in a cached map service
	panningMode This parameter enables the different panning Modes for Navigator and Keyboard, These are the 3 supported modes 0: effective in this mode, All cached services pan continuously and dyanmic services pan traditionally 1: continuous 2: traditional
	scale The current scale of map.
	scaleBar 'adf.ScaleBar' instance used by map
	showCoordinateTracker Turns on the CoordinateDisplayTracker element (default position is at the bottom right of the map display)
	showNavigator Turns on the default adf.MapNavigator.
	showZoomSlider Turns on the default adf.MapSlider.
	slideAnimDuration The number of milliseconds for slide animation to last when using adf.Map#offsetView
	webGraphics The image element containing the server-side web graphics
	webGraphicsId The id of the `this.webGraphics`
	webGraphicsZIndex The CSS z-index value for `this.webGraphics`
	width The width of the map
	zoomBeyondCache If set to true, allows the user to zoom outside of cached levels when combining cached and dynamic services

Fields borrowed from class adf.Control:: bounds, divId, divObject, id, type, updateListenerNames, updateListeners

Method Summary
Method Attributes	Method Name and Description
	activateCurrentToolItem() activates the current adf.MapToolItem
	addMapSource(name, mapSource, updateWebGraphics) Adds a new map source to this map
	addScaleBar(url, position, width, height, screenDistance, mapDistance, units, type) Adds an adf.ScaleBar to the maps display.
	centerAt(x, y, activeToolId) This asynchronous call re-centers the map control on the server at the x and y coordinates.
	changeLevel(newLevel) Asynchronous operation to change the zoom factor.
	clearCurrentToolItem() Deactivates the current tool, then sets the current tool to null
	clearImages() Clears all map images from the DOM
	createCurrentToolItem(id, elementId, clientAction, showLoading, clientPostBack, lineColor, lineWidth, defaultStyleClass, hoverStyleClass, selectedStyleClass, disabledStyleClass) Establishes a new current tool and sets the tool to be active
	createToolItem(id, elementId, showLoading, clientPostBack, lineColor, lineWidth, defaultStyleClass, hoverStyleClass, selectedStyleClass, disabledStyleClass, toolCollection, toolCollection) Establishes a new map tool for this map
	deactivateCurrentToolItem() deactivates the current adf.MapToolItem
	drawGraphic(args) This method draws client graphics on adf.Map#graphics based on the provided map coordinates.
	hideLoading() Hides the map's progress indicator
	init(container) Initializes map with the given HTML container.
	offsetView(x, y, dontCenterAt, dontDragImages, dontCleanUpTiles, dontUpdateTiles) Moves the the map in pixels by x and y values.
	onRefresh() Event occurs when this map has been refreshed on the client and all display contents have been reset.
	panTo(mapPoint) Pans the map so that the given mapPoint is at the center of the map.
	placeElement(args) Places an element within the map.
	reactivateCurrentToolItem(forceActivate) reactivates the current adf.MapToolItem
	removeAllMapSources() Removes all map sources from this map
	removeElement(node) Removes the specified node reference from the DOM if it is found to be a descendant of the maps containing node, otherwise ignored.
	removeMapSource(name, updateWebGraphics) Removes the map source keyed by the provide map source name.
	resize(width, height) This asynchronous call will resize the map control on the server.
	setCurrentToolItem(toolItem, toolBarId) Activates the specified toolItem so that it's action gains control over the user input.
	setDoubleClickCenterZoom(iseffect) sets the double click center effect
	showLoading() Shows the map's loadng through a progress bar widget.
	toMapPoint(point) Converts an adf.Point which contains screen coordinates to the maps coordinate system.
	toScreenPoint(point) Converts an adf.Point with map coordinates to to an adf.Point with screen coordinates The screen coordinate system uses x, y coordinate system for graphic operation whose origin {X: 0, Y: 0} is the upper left corner of map's viewport.
	updateAsync(xml, eventSources) Updates the client-side map control with the server-side xml response after the server control has been modified.
	updateWebGraphics() Sends an AJAX request to retreive the server-side web graphics image output

Methods borrowed from class adf.Control:: addUpdateListener, removeUpdateListener
Methods borrowed from class adf.PageElement:: hide, show

Event Summary
Event Attributes	Event Name and Description
	onCenterAtComplete() Event occurs after the map has re-centered on the server
	onExtentChange(newExtent, previousExtent) Event occurs after this.extent has been updated
	onPanEnd() Event occurs after a pan operation has finished.
	onPanStart() Event occurs just as a pan has been initiated by user interaction, should always be followed by an adf.Map#onPanEnd event.
	onResize() Event occurs when the height and/or width of the map have changed
	onWebResultsChange() Event occurs when the contents of the WebResults object on the server has been changed.
	onZoom(delta) Event occurs when map's scale has changed

Class Detail

adf.Map(id, containerNode, formId, width, height)

The central class that renders map and other graphic elements, a simple ADF application could consist of one 'adf.Map' instance Create a new map instance inside of the given HTML container.

Parameters:
{String} id: The id of the map
{Element} containerNode: The HTML container in which the map resides. It can be set to 'null' if user wants to set map's properties and initialize the map later
{String} formId: The ID of the form that map resides in. The map has to be inside the HTML form
{Integer} width: Optional, the width of the map. If no width is given, map takes the container's width. If map does not has container, the default width is 400px
{Integer} height: Optional, the height of the map. If no height is given, map takes the container's height. If map does not has container, the default height is 400px

Field Detail

{Boolean} animateGridElements

Turns on slide animation for elements that are positioned using map.placeElement() with map coordinates

animateTransistions

Show transition animation effects for pan and zoom operations.

Default Value:: true

{Boolean} cacheClientFeatures

Turns on client-side caching of web result features. Minimizes the number of requests sent to the server.

Default Value:: true

{adf.Callout} callOut

adf.Callout instance placed at a certain position of map. It is often used to show a map tip feature's content.

{Boolean} enableMapTips

Turns the MapTips feature on and off

Default Value:: true

{adf.Extent} extent

Holds the current visible extent in map coordinates

formId

The id of the form this map control is bound to

{adf.graphics.Element} graphics

The default adf.graphics.Element displayed over the map.

Default Value:: null

{String} graphicsId

The id of this.graphics HTML element.

{Number} graphicsZIndex

The CSS z-index value for this.graphics.

Default Value:: 20

{Number} height

The height of the map

Default Value:: 400

{Element} imageGrid

An HTML DIV element which contains viewport's content[map images and graphic elements]. It has the same width and height as viewport. When map initializes or refreshes, it overlaps with viewport completely. Viewport content's width and height might be larger than viewport's if multiple map images coexist inside of imageGrid. By resetting origin of imageGrid, any portion of the viewport content can be surveyed even if the content covers larger area than viewport. imageGrid would have an offset from viewport if continous pan happens or 'map.panTo(mapPoint)' is invocated.

{Boolean} isFuseGraphics

When set to true, the web graphics content is fused with a dynamic map source

Default Value:: false

{Number} level

The current zoom level which maps to a particular map scale. For a dynamic map, level is always 0 This property is updated when adf.Map#changeLevel or adf.Map#updateAsync are called

Default Value:: 0

{adf.MapTip} mapTip

'adf.MapTip' instance used by map

{Number} numLevels

Represents the number of levels of detail in a cached map service

Default Value:: 0

panningMode

This parameter enables the different panning Modes for Navigator and Keyboard, These are the 3 supported modes 0: effective in this mode, All cached services pan continuously and dyanmic services pan traditionally 1: continuous 2: traditional

{Number} scale

The current scale of map. This property is updated when adf.Map#changeLevel or adf.Map#updateAsync are called

{adf.ScaleBar} scaleBar

'adf.ScaleBar' instance used by map

Default Value:: null

{Boolean} showCoordinateTracker

Turns on the CoordinateDisplayTracker element (default position is at the bottom right of the map display)

{Boolean} showNavigator

Turns on the default adf.MapNavigator.

Default Value:: true

{Boolean} showZoomSlider

Turns on the default adf.MapSlider.

Default Value:: true

{Number} slideAnimDuration

The number of milliseconds for slide animation to last when using adf.Map#offsetView

{Element} webGraphics

The image element containing the server-side web graphics

{String} webGraphicsId

The id of the this.webGraphics

{Number} webGraphicsZIndex

The CSS z-index value for this.webGraphics

Default Value:: 19

{Number} width

The width of the map

Default Value:: 400

{Boolean} zoomBeyondCache

If set to true, allows the user to zoom outside of cached levels when combining cached and dynamic services

Default Value:: false

Method Detail

activateCurrentToolItem()

activates the current adf.MapToolItem

addMapSource(name, mapSource, updateWebGraphics)

Adds a new map source to this map

Parameters:
{String} name: String value to use as a internal identifier
{adf.MapSource} mapSource
{Boolean} updateWebGraphics Optional, Default: false: Update web graphics after adding this new map source

addScaleBar(url, position, width, height, screenDistance, mapDistance, units, type)

Adds an adf.ScaleBar to the maps display.

Parameters:
{String} url: The url to the scale bar's server implementation
{String} position: Describes the anchor position over the map. Supported values include "top-left", "top-right", "bottom-left", "bottom-right" or "none". When set to "none", the CSS clas "esriScaleBar" is applied to the DOM node and position can be set in a CSS document.
{Number} width
{Number} height
{Number} screenDistance: The distance in pixels displayed on the scale bar
{Number} mapDistance: The distance in map units displayed on the scale bar
{String} units: The units displayed on the scale bar
{String} type: One of the following render types: "Alternating", "SteppedScaleLine", "SingleDivision" or "DoubleAlternating"

centerAt(x, y, activeToolId)

This asynchronous call re-centers the map control on the server at the x and y coordinates. If the parameter activeToolId is supplied, this active tool will remain active when the server response is handled. adf.Map#extent will be updated when the response is handled.

Parameters:
{Number} x: the x coordinate to center at
{Number} y: the y coordinate to center at
{String} activeToolId Optional: The id of the adf.MapToolItem that is currently active (to be handled with the response)

changeLevel(newLevel)

Asynchronous operation to change the zoom factor. Response for this asynchronous request is handled by adf.Map.updateAsync.

Parameters:
{Number} newLevel: The level to change to

clearCurrentToolItem()

Deactivates the current tool, then sets the current tool to null

clearImages()

Clears all map images from the DOM

createCurrentToolItem(id, elementId, clientAction, showLoading, clientPostBack, lineColor, lineWidth, defaultStyleClass, hoverStyleClass, selectedStyleClass, disabledStyleClass)

Establishes a new current tool and sets the tool to be active

Parameters:
{String} id: the id of the tool
{String} elementId: the id of the HTML element associated with this tool
{adf.Action} clientAction
{Boolean} showLoading: if true, shows the progress bar when the tool's action performs its operation
{boolean} clientPostBack: submit form asynchronously
{String} lineColor Optional
{Number} lineWidth Optional
{String} defaultStyleClass Optional
{String} hoverStyleClass Optional
{String} selectedStyleClass Optional
{String} disabledStyleClass Optional

createToolItem(id, elementId, showLoading, clientPostBack, lineColor, lineWidth, defaultStyleClass, hoverStyleClass, selectedStyleClass, disabledStyleClass, toolCollection, toolCollection)

Establishes a new map tool for this map

Parameters:
{String} id: the id of the tool
{String} elementId: the id of the HTML element associated with this tool
{Boolean} showLoading: if true, shows the progress bar when the tool's action performs its operation
{boolean} clientPostBack: submit form asynchronously
{String} lineColor Optional
{Number} lineWidth Optional
{String} defaultStyleClass Optional
{String} hoverStyleClass Optional
{String} selectedStyleClass Optional
{String} disabledStyleClass Optional
{adf.ToolItemCollection} toolCollection
toolCollection

deactivateCurrentToolItem()

deactivates the current adf.MapToolItem

drawGraphic(args)

This method draws client graphics on adf.Map#graphics based on the provided map coordinates.
The follwoing graphic types are supported:

image
line
polyline
polygon
circle
oval
rectangle
text

var map = adf.Controls.maps['map1'];
map.graphics.clear();
var width = map.extent.getWidth();
var height = map.extent.getHeight();
var point1 = new adf.Point(map.extent.xmin + Math.floor(width / 4), map.extent.ymin + Math.floor(height / 4));
var point2 = new adf.Point(map.extent.xmin + Math.floor((width / 4) * 3), map.extent.ymin + Math.floor((height / 4) * 3));
map.drawGraphic({type:'line', geometry: [point1, point2], symbol:{lineWidth:20, lineColor:'#0066FF', lineOpacity: 0.8 } });
map.drawGraphic({
       type: "text",
       geometry: {center: point1, text:"Welcome to ADF JavaServer", height:20 , width: 200}, 
	         symbol: { 	          
	          lineColor: "#f44",
             lineWidth: 1,
             fillColor: "#03f",
             fillOpacity:1 
        }
     });

Parameters:
{Object} args
{String} args.type
{adf.Point|adf.Point[]|Object} args.geometry
{adf.Point} args.geometry.center Optional
{Number} args.geometry.height Optional
{Number} args.geometry.width Optional
{String} args.geometry.text Optional
{adf.GraphicsSymbol} args.symbol

hideLoading()

Hides the map's progress indicator

init(container)

Initializes map with the given HTML container.

Parameters:
{Node} container: container of map, which is usually a DIV element

offsetView(x, y, dontCenterAt, dontDragImages, dontCleanUpTiles, dontUpdateTiles)

Moves the the map in pixels by x and y values. By calling this.offsetView(10, 5), the top left point of the map will move 10 pixels to the right and 5 pixels down. Pass true for dontCenterAt if you plan on explicitly calling this.centerAt() on your own. Pass true for dontDragImages if you plan to move the imageGrid (map tiles) on your own just as MapContinuousPan uses DragElementAction to move the image grid.

Parameters:
{Integer} x: the x delta to offset the map by
{Integer} y: the y delta to offset the map by
{Boolean} dontCenterAt: when true, omits the call to this.centerAt() at the end of the offset
{Boolean} dontDragImages: when true, leaves the map images where they are at, only update the view bounds (in case you want to use with)
{Boolean} dontCleanUpTiles: when true, does not remove tiles that are no longer visible
{Boolean} dontUpdateTiles: this parameter works in sync with adf.Map#panningMode, when dontUpdateTiles = true : adf.Map#panningMode = 0 (hybrid pan) Dynamic services tiles are not updated, adf.Map#panningMode = 1 (contnuous pan) Dynamic services tiles are not updated, adf.Map#panningMode = 2 (traditional pan) Dynamic and Tiled services tiles are not updated

onRefresh()

Event occurs when this map has been refreshed on the client and all display contents have been reset. This event will likely occur with a combintion of other event such as adf.Map#onZoom or adf.Map#onResize.

panTo(mapPoint)

Pans the map so that the given mapPoint is at the center of the map. If the given map coordinate is within the current visible extent, the pan is animated with a slide effect, otherwise there is no animation.

Parameters:
{adf.Point} mapPoint

placeElement(args)

Places an element within the map. If args.mapPoint is defined, the referred node is placed on the map and will remain at the specified map coordinate even after extent changes.
If mapPoint is not defined and screenPoint is defined, the referred node will be placed within the maps containing element and will remain fixed at that position until the mode is either removed or explicitly moved.
The values for offsetX and offsetY will be applied to either screenPoint or mapPoint when placed.
Use adf.Map#removeElement to remove elements placed within the map by this function.

var node1 = adfdojo.create("div", {id: "node1", style: {width:"100px", height:"100px", backgroundColor:"#fc0", border:"10px solid #f06"}});
var args = {};
args.node = node1;
args.mapPoint = new adf.Point(-100,39.2);
var map = adf.Controls.maps['map1'];
map.placeElement(args);

Parameters:
{Object} args
{Element} args.node: the element to place on the map
{adf.Point} ags.mapPoint Optional
{adf.Point} args.screenPoint Optional
{Number} args.offsetX Optional, Default: 0
{Number} args.offsetY Optional, Default: 0

reactivateCurrentToolItem(forceActivate)

reactivates the current adf.MapToolItem

Parameters:
{Boolean} forceActivate: This parameter when set to true forces the re-activation of the current toolitem even when the currentTool's action is active

removeAllMapSources()

Removes all map sources from this map

removeElement(node)

Removes the specified node reference from the DOM if it is found to be a descendant of the maps containing node, otherwise ignored.

Parameters:
{Element} node: {Element} the node to remove from the map DOM

removeMapSource(name, updateWebGraphics)

Removes the map source keyed by the provide map source name.

Parameters:
{String} name: The name of the map source to remove
{Boolean} updateWebGraphics Optional, Default: false: Update web graphics after adding this new map source

resize(width, height)

This asynchronous call will resize the map control on the server. When the response is handled, the map image will reflect this new map size.

Parameters:
{Number} width: the new width
{Number} height: the new height

setCurrentToolItem(toolItem, toolBarId)

Activates the specified toolItem so that it's action gains control over the user input.

Parameters:
{adf.MapToolItem} toolItem: The tool item to activate
{String} toolBarId Optional: If the tool item isn't part of the current tool bar, specify the tool bar id

setDoubleClickCenterZoom(iseffect)

sets the double click center effect

Parameters:
iseffect

showLoading()

Shows the map's loadng through a progress bar widget.

toMapPoint(point)

Converts an adf.Point which contains screen coordinates to the maps coordinate system.

Parameters:
{adf.Point} point

toScreenPoint(point)

Converts an adf.Point with map coordinates to to an adf.Point with screen coordinates The screen coordinate system uses x, y coordinate system for graphic operation whose origin {X: 0, Y: 0} is the upper left corner of map's viewport. The x coordinate is the pixel distance from the left. The y cooridnate is the pixel distance from the top.

Parameters:
{adf.Point} point

updateAsync(xml, eventSources)

Updates the client-side map control with the server-side xml response after the server control has been modified.

Parameters:
{XMLDocument} xml: the xml response document
{String[]} eventSources

updateWebGraphics()

Sends an AJAX request to retreive the server-side web graphics image output

Event Detail

onCenterAtComplete()

Event occurs after the map has re-centered on the server

onExtentChange(newExtent, previousExtent)

Event occurs after this.extent has been updated

adfdojo.connect(myMapObj, "onExtentChange", function(new, old) {
  alert("my map has changed extent from " + old + " to " + new ".");
});

Parameters:
{adf.Extent} newExtent: The extent that the map has been changed to
{adf.Extent} previousExtent: The extent prior to the change

onPanEnd()

Event occurs after a pan operation has finished.

onPanStart()

Event occurs just as a pan has been initiated by user interaction, should always be followed by an adf.Map#onPanEnd event.

onResize()

Event occurs when the height and/or width of the map have changed

onWebResultsChange()

Event occurs when the contents of the WebResults object on the server has been changed. Either a result has been added, removed or modified. This serves as notification for MapTips.

onZoom(delta)

Event occurs when map's scale has changed

Parameters:
{Number} delta

Classes

Class adf.Map