Map Suite MVC Edition JavaScript Reference
This document defines the client JavaScript functions that are applied to the Map's
name. In other words, if you add an MVC Edition map control named "Map1"
to the view page, then you would call these functions like "Map1.functionName()".
For example: Map1.getLayer('layerId').
(Note: For more details, please reference the OpenLayers API Documentation).
| Map's Name | |
| Constants | |
| EVENT_TYPES | {Array(String)} Supported application event types. |
| Properties | |
| id | {String} Unique identifier for the map |
| events | {OpenLayers.Events} An events object that handles all events on the map |
| div | {DOMElement|String} The element that contains the map (or an id for that element). |
| dragging | {Boolean} The map is currently being dragged. |
| size | {OpenLayers.Size} Size of the main div (this.div) |
| layers | {Array(OpenLayers.Layer)} Ordered list of layers in the map |
| controls | {Array(OpenLayers.Control)} List of controls associated with the map. |
| popups | {Array(OpenLayers.Popup)} List of popups associated with the map |
| baseLayer | {OpenLayers.Layer} The currently selected base layer. |
| center | {OpenLayers.LonLat} The current center of the map |
| resolution | {Float} The resolution of the map. |
| zoom | {Integer} The current zoom level of the map |
| tileSize | {OpenLayers.Size} Set in the map options to override the default tile size for this map. |
| projection | {String} Set in the map options to override the default projection string this map - also set maxExtent, maxResolution, and units if appropriate. |
| units | {String} The map units. |
| resolutions | {Array(Float)} A list of map resolutions (map units per pixel) in descending order. |
| maxResolution | {Float} Default max is 360 deg / 256 px, which corresponds to zoom level 0 on gmaps. |
| minResolution | {Float} |
| maxScale | {Float} |
| minScale | {Float} |
| maxExtent | {OpenLayers.Bounds} The maximum extent for the map. |
| minExtent | {OpenLayers.Bounds} |
| restrictedExtent | {OpenLayers.Bounds} Limit map navigation to this extent where possible. |
| numZoomLevels | {Integer} Number of zoom levels for the map. |
| theme | {String} Relative path to a CSS file from which to load theme styles. |
| displayProjection | {OpenLayers.Projection} Requires proj4js support.Projection used by several controls to display data to user. |
| fallThrough | {Boolean} Should OpenLayers allow events on the map to fall through to other elements on the page, or should it swallow them? |
| panDuration | {Integer} The number of steps to be passed to the OpenLayers.Tween.start() method when the map is panned. |
| paddingForPopups | {OpenLayers.Bounds} Outside margin of the popup. |
| Functions | |
| getLayersBy | Get a list of layers with properties matching the given criteria. |
| getLayersByName | Get a list of layers with names matching the given name. |
| getLayersByClass | Get a list of layers of a given class (CLASS_NAME). |
| getControlsBy | Get a list of controls with properties matching the given criteria. |
| getControlsByClass | Get a list of controls of a given class (CLASS_NAME). |
| getLayer | Get a layer based on its id |
| setLayerZIndex | |
| resetLayersZIndex | Reset each layer’s z-index based on layer’s array index |
| addLayer | |
| addLayers | |
| removeLayer | Removes a layer from the map by removing its visual element (the layer.div property), then removing it from the map’s internal list of layers, setting the layer’s map property to null. |
| getNumLayers | {Int} The number of layers attached to the map. |
| getLayerIndex | |
| setLayerIndex | Move the given layer to the specified (zero-based) index in the layer list, changing its z-index in the map display. |
| setBaseLayer | Allows user to specify one of the currently-loaded layers as the Map’s new base layer. |
| addControl | Add the passed over control to the map. |
| addControls | Add all of the passed over controls to the map. |
| getControl | |
| removeControl | Remove a control from the map. |
| addPopup | |
| removePopup | |
| getSize | {OpenLayers.Size} An OpenLayers.Size object that represents the size, in pixels, of the div into which OpenLayers has been loaded. |
| updateSize | This function should be called by any external code which dynamically changes the size of the map div (because mozilla wont let us catch the “onresize” for an element) |
| getCenter | {OpenLayers.LonLat} |
| getZoom | {Integer} |
| pan | Allows user to pan by a value of screen pixels |
| panTo | Allows user to pan to a new lonlat If the new lonlat is in the current extent the map will slide smoothly |
| setCenter | Set the map center (and optionally, the zoom level). |
| moveByPx | Drag the map by pixels. |
| moveTo | |
| isValidZoomLevel | |
| isValidLonLat | |
| getProjection | This method returns a string representing the projection. |
| getMaxResolution | {String} The Map’s Maximum Resolution |
| getMaxExtent | |
| getNumZoomLevels | {Integer} The total number of zoom levels that can be displayed by the current baseLayer. |
| getExtent | {OpenLayers.Bounds} A Bounds object which represents the lon/lat bounds of the current viewPort. |
| getResolution | {Float} The current resolution of the map. |
| getUnits | {Float} The current units of the map. |
| getScale | {Float} The current scale denominator of the map. |
| getZoomForExtent | |
| getResolutionForZoom | |
| getZoomForResolution | |
| zoomTo | Zoom to a specific zoom level |
| zoomIn | |
| zoomOut | |
| zoomToExtent | Zoom to the passed in bounds, recenter |
| zoomToMaxExtent | Zoom to the full extent and recenter. |
| zoomToScale | Zoom to a specified scale |
| getLonLatFromViewPortPx | |
| getViewPortPxFromLonLat | |
| getLonLatFromPixel | |
| getPixelFromLonLat | Returns a pixel location given a map location. |
| getViewPortPxFromLayerPx | |
| getLayerPxFromViewPortPx | |
| getLonLatFromLayerPx | |
| getLayerPxFromLonLat | |
| getMapTools | gets the map tools object which is corresponding to the MapTools of the map on server side. |
| getMapParser | gets the mapParser which is used to convert the Map JSON string to cient map object. |
| toggleExtent | Toggle the map between the previous and the next extent. |
| setDrawMode | Set the map mode by the drawMode parameter. |
| resetLayerZIndex | reset the z-index of each layers in the map. |
| setMeasureMode | sets the measure mode of the measure tool, it can be any of “PathMeasure”, “PolygonMeasure” or “Normal”. |
| setEditSetting | Set current map edit mode to Reshape|Rotate|Resize|Drag mode. |
| clearEditingFeatures | Clear all features drawn on the map. |
| cancelLatestFeature | Delete the latest drawn feature. |
| printMap | Print the current map. |
| redrawLayer | Redraws the layer which is specifed by the id. |
| setCurrentBackgroundMapType | Change current OpenLayers third part layer’s type. |
| redrawBackgound | refresh the map's background. |
| ajaxCallAction | Performs an asynchronous HTTP (Ajax) request to an action of the specified controller with parameters in JSON format. |
| ajaxCall | This is the override for function ajaxCallAction, it performs an asynchronous HTTP (Ajax) request to an action of the specified controller with parameters in JSON format. |
| getFeaturesFromJson | get the features from the specified Json. |
| getEditFeaturesInJson | Gets the drawn geometries from EditOverlay in JSON format. |
| getStaticOverlay | Gets the layer which is corresponding to the StaticOverlay of the map on server side. |
| getDynamicOverlay | Gets the layer which is corresponding to the DyanmicOverlay of the map on server side. |
| getMarkerOverlay | Gets the marker layer which is corresponding to the MarkerOverlay of the map on server side. |
| getEditOverlay | Gets the vector layer for editing, it's corresponding to the EditOverlay of the map on server side. |
| getHighlightOverlay | Gets the layer which is used to render the HighlightOverlay of the map on server side. |
| getAdornmentOverlay | Gets the layer which is corresponding to the AdornmentOverlay of the map on server side. |
| Enumerations | |
| EditSettings | It just can be used when the map is in editing state. |
| MouseCoordinateType | Represents the mouse coodrdinates format supported. |
| Constants | |
| TILE_WIDTH | {Integer} 256 Default tile width (unless otherwise specified) |
| TILE_HEIGHT | {Integer} 256 Default tile height (unless otherwise specified) |
EVENT_TYPES
{Array(String)} Supported application event types. Register a listener for a particular event with the following syntax:
map.events.register(type, obj, listener);
Listeners will be called with a reference to an event object. The properties of this event depends on exactly what happened.
All event objects have at least the following properties
- object {Object} A reference to map.events.object.
- element {DOMElement} A reference to map.events.element.
Browser events have the following additional properties
- xy {OpenLayers.Pixel} The pixel location of the event (relative to the the map viewport).
- other properties that come with browser events
Supported map event types
- preaddlayer triggered before a layer has been added. The event object will include a layer property that references the layer to be added. When a listener returns “false” the adding will be aborted.
- addlayer triggered after a layer has been added. The event object will include a layer property that references the added layer.
- preremovelayer triggered before a layer has been removed. The event object will include a layer property that references the layer to be removed. When a listener returns “false” the removal will be aborted.
- removelayer triggered after a layer has been removed. The event object will include a layer property that references the removed layer.
- changelayer triggered after a layer name change, order change, opacity change, params change, visibility change (due to resolution thresholds) or attribution change (due to extent change). Listeners will receive an event object with layer and property properties. The layer property will be a reference to the changed layer. The property property will be a key to the changed property (name, order, opacity, params, visibility or attribution).
- movestart triggered after the start of a drag, pan, or zoom
- move triggered after each drag, pan, or zoom
- moveend triggered after a drag, pan, or zoom completes
- zoomend triggered after a zoom completes
- mouseover triggered after mouseover the map
- mouseout triggered after mouseout the map
- mousemove triggered after mousemove the map
- changebaselayer triggered after the base layer changes
div
{DOMElement|String} The element that contains the map (or an id for that element). If the OpenLayers.Map constructor is called with two arguments, this should be provided as the first argument. Alternatively, the map constructor can be called with the options object as the only argument. In this case (one argument), a div property may or may not be provided. If the div property is not provided, the map can be rendered to a container later using the render method.
Note
If you are calling render after map construction, do not use maxResolution auto. Instead, divide your maxExtent by your maximum expected dimension.
controls
{Array(OpenLayers.Control)} List of controls associated with the map.
If not provided in the map options at construction, the map will be given the following controls by default:
- OpenLayers.Control.Navigation
- OpenLayers.Control.PanZoom
- OpenLayers.Control.ArgParser
- OpenLayers.Control.Attribution
restrictedExtent
{OpenLayers.Bounds} Limit map navigation to this extent where possible. If a non-null restrictedExtent is set, panning will be restricted to the given bounds. In addition, zooming to a resolution that displays more than the restricted extent will center the map on the restricted extent. If you wish to limit the zoom level or resolution, use maxResolution.
getLayersBy
getLayersBy: function( property, match )
Get a list of layers with properties matching the given criteria.
Parameter
| property | {String} A layer property to be matched. |
| match | {String | Object} A string to match. Can also be a regular expression literal or object. In addition, it can be any object with a method named test. For reqular expressions or other, if match.test(layer[property]) evaluates to true, the layer will be included in the array returned. If no layers are found, an empty array is returned. |
Returns
{Array(OpenLayers.Layer)} A list of layers matching the given criteria. An empty array is returned if no matches are found.
getLayersByName
getLayersByName: function( match )
Get a list of layers with names matching the given name.
Parameter
| match | {String | Object} A layer name. The name can also be a regular expression literal or object. In addition, it can be any object with a method named test. For reqular expressions or other, if name.test(layer.name) evaluates to true, the layer will be included in the list of layers returned. If no layers are found, an empty array is returned. |
Returns
{Array(OpenLayers.Layer)} A list of layers matching the given name. An empty array is returned if no matches are found.
getLayersByClass
getLayersByClass: function( match )
Get a list of layers of a given class (CLASS_NAME).
Parameter
| match | {String | Object} A layer class name. The match can also be a regular expression literal or object. In addition, it can be any object with a method named test. For reqular expressions or other, if type.test(layer.CLASS_NAME) evaluates to true, the layer will be included in the list of layers returned. If no layers are found, an empty array is returned. |
Returns
{Array(OpenLayers.Layer)} A list of layers matching the given class. An empty array is returned if no matches are found.
getControlsBy
getControlsBy: function( property, match )
Get a list of controls with properties matching the given criteria.
Parameter
| property | {String} A control property to be matched. |
| match | {String | Object} A string to match. Can also be a regular expression literal or object. In addition, it can be any object with a method named test. For reqular expressions or other, if match.test(layer[property]) evaluates to true, the layer will be included in the array returned. If no layers are found, an empty array is returned. |
Returns
{Array(OpenLayers.Control)} A list of controls matching the given criteria. An empty array is returned if no matches are found.
getControlsByClass
getControlsByClass: function( match )
Get a list of controls of a given class (CLASS_NAME).
Parameter
| match | {String | Object} A control class name. The match can also be a regular expression literal or object. In addition, it can be any object with a method named test. For reqular expressions or other, if type.test(control.CLASS_NAME) evaluates to true, the control will be included in the list of controls returned. If no controls are found, an empty array is returned. |
Returns
{Array(OpenLayers.Control)} A list of controls matching the given class. An empty array is returned if no matches are found.
removeLayer
removeLayer: function( layer, setNewBaseLayer )
Removes a layer from the map by removing its visual element (the layer.div property), then removing it from the map’s internal list of layers, setting the layer’s map property to null.
a “removelayer” event is triggered.
very worthy of mention is that simply removing a layer from a map will not cause the removal of any popups which may have been created by the layer. this is due to the fact that it was decided at some point that popups would not belong to layers. thus there is no way for us to know here to which layer the popup belongs.
A simple solution to this is simply to call destroy() on the layer. the default OpenLayers.Layer class’s destroy() function automatically takes care to remove itself from whatever map it has been attached to.
The correct solution is for the layer itself to register an event-handler on “removelayer” and when it is called, if it recognizes itself as the layer being removed, then it cycles through its own personal list of popups, removing them from the map.
Parameters
| layer | {OpenLayers.Layer} |
| setNewBaseLayer | {Boolean} Default is true |
setLayerIndex
setLayerIndex: function ( layer, idx )
Move the given layer to the specified (zero-based) index in the layer list, changing its z-index in the map display. Use map.getLayerIndex() to find out the current index of a layer. Note that this cannot (or at least should not) be effectively used to raise base layers above overlays.
Parameters
| layer | {OpenLayers.Layer} |
| idx | {int} |
raiseLayer
raiseLayer: function ( layer, delta )
Change the index of the given layer by delta. If delta is positive, the layer is moved up the map’s layer stack; if delta is negative, the layer is moved down. Again, note that this cannot (or at least should not) be effectively used to raise base layers above overlays.
Paremeters
| layer | {OpenLayers.Layer} |
| delta | {int} |
addControls
addControls: function ( controls, pixels )
Add all of the passed over controls to the map. You can pass over an optional second array with pixel-objects to position the controls. The indices of the two arrays should match and you can add null as pixel for those controls you want to be autopositioned.
Parameters
| controls | {Array(OpenLayers.Control)} |
| pixels | {Array(OpenLayers.Pixel)} |
removeControl
removeControl: function ( control )
Remove a control from the map. Removes the control both from the map object’s internal array of controls, as well as from the map’s viewPort (assuming the control was not added outsideViewport)
Parameters
| control | {OpenLayers.Control} The control to remove. |
pan
pan: function( dx, dy, options )
Allows user to pan by a value of screen pixels
Parameters
| dx | {Integer} |
| dy | {Integer} |
| options | {Object} Options to configure panning: |
- animate {Boolean} Use panTo instead of setCenter. Default is true.
- dragging {Boolean} Call setCenter with dragging true. Default is false.
setCenter
setCenter: function( lonlat, zoom, dragging, forceZoomChange )
Set the map center (and optionally, the zoom level).
Parameters
| lonlat | {OpenLayers.LonLat} The new center location. |
| zoom | {Integer} Optional zoom level. |
| dragging | {Boolean} Specifies whether or not to trigger movestart/end events |
| forceZoomChange | {Boolean} Specifies whether or not to trigger zoom change events (needed on baseLayer change) |
TBD: reconsider forceZoomChange in 3.0
getProjection
getProjection: function()
This method returns a string representing the projection. In the case of projection support, this will be the srsCode which is loaded -- otherwise it will simply be the string value that was passed to the projection at startup.
FIXME: In 3.0, we will remove getProjectionObject, and instead return a Projection object from this function.
Returns
{String} The Projection string from the base layer or null.
getMaxExtent
getMaxExtent: function ( options )
Parameters
| options | {Object} |
Allowed Options
| restricted | {Boolean} If true, returns restricted extent (if it is available.) |
Returns
{OpenLayers.Bounds} The maxExtent property as set on the current baselayer, unless the ‘restricted’ option is set, in which case the ‘restrictedExtent’ option from the map is returned (if it is set).
getZoomForExtent
getZoomForExtent: function ( bounds, closest )
Parameters
| bounds | {OpenLayers.Bounds} |
| closest | {Boolean} Find the zoom level that most closely fits the specified bounds. Note that this may result in a zoom that does not exactly contain the entire extent. Default is false. |
Returns
{Integer} A suitable zoom level for the specified bounds. If no baselayer is set, returns null.
getZoomForResolution
getZoomForResolution: function( resolution, closest )
Parameter
| resolution | {Float} |
| closest | {Boolean} Find the zoom level that corresponds to the absolute closest resolution, which may result in a zoom whose corresponding resolution is actually smaller than we would have desired (if this is being called from a getZoomForExtent() call, then this means that the returned zoom index might not actually contain the entire extent specified... but it’ll be close). Default is false. |
Returns
{Integer} A suitable zoom level for the specified resolution. If no baselayer is set, returns null.
zoomToExtent
zoomToExtent: function( bounds, closest )
Zoom to the passed in bounds, recenter
Parameters
| bounds | {OpenLayers.Bounds} |
| closest | {Boolean} Find the zoom level that most closely fits the specified bounds. Note that this may result in a zoom that does not exactly contain the entire extent. Default is false. |
getPixelFromLonLat
getPixelFromLonLat: function ( lonlat )
Returns a pixel location given a map location. The map location is translated to an integer pixel location (in viewport pixel coordinates) by the current base layer.
Parameters
| lonlat | {OpenLayers.LonLat} A map location. |
Returns
{OpenLayers.Pixel} An OpenLayers.Pixel corresponding to the OpenLayers.LonLat translated into view port pixels by the current base layer.
getMapTools
getMapTools: function ()
gets the map tools object which is corresponding to the MapTools of the map on server side.
Returns
{OpenLayers.Control} Map tools object.Examples
var panzoomBar = Map1.getMapTools().panZoomBar; var mousecoordinate = Map1.getMapTools().mouseCoordinate; var measureMapTool = Map1.getMapTools().measureMapTool; var touchMapTool = Map1.getMapTools().touchMapTool; var animationPanMapTool = Map1.getMapTools().animationPanMapTool; var overlaySwitcher = Map1.getMapTools().overlaySwitcher; var mouseMapTool = Map1.getMapTools().mouseMapTool; var mouseCoordinate = Map1.getMapTools().mouseCoordinate; var miniMap = Map1.getMapTools().miniMap; var panZoom = Map1.getMapTools().panZoom; var panZoomBar = Map1.getMapTools().panZoomBar; var scaleLine = Map1.getMapTools().scaleLine; var logo = Map1.getMapTools().logo; var keyboardMapTool = Map1.getMapTools().keyboardMapTool;
setDrawMode
setDrawMode: function ( drawMode )
Set the map mode by the drawMode parameter. The map mode can be set as “Point”, “Line”, “Polygon”, “Rectangle”, “Square”, “Circle”, “Ellipse”, “Normal” and “Modify”. In the “Normal” mode, the map is in its normal state. In the “Modify” mode, the shapes on the map can be edited. In other modes, you can draw the specified shapes on the map.
Parameters
| drawMode | {String} it can be specified as Point”, “Line”, “Polygon”, “Rectangle”, “Square”, “Circle”, “Ellipse”, “Normal”, “Modify”. |
Examples
Map1.SetDrawMode(“Normal”); Map1.SetDrawMode(“Modify”); Map1.SetDrawMode(“Point”); Map1.SetDrawMode(“Line”); Map1.SetDrawMode(“Polygon”); Map1.SetDrawMode(“Rectangle”); Map1.SetDrawMode(“Square”); Map1.SetDrawMode(“Circle”); Map1.SetDrawMode(“Ellipse”);
setMeasureMode
setMeasureMode: function ( measureMode )
sets the measure mode of the measure tool, it can be any of “PathMeasure”, “PolygonMeasure” or “Normal”. In the “Normal” mode, the map is in its normal state, and the measure tool is disabled.
Parameters
| measureMode | {String} measure mode of the measure tool. |
Examples
Map1.setMeasureMode('PathMeasure');
Map1.setMeasureMode('PolygonMeasure');
setEditSetting
setEditSetting: function ( editMode )
Set current map edit mode to Reshape|Rotate|Resize|Drag mode.
Parameters
| editMode | {String} the edit mode of editSetting. It can be specified as: EditSettings.Reshape, EditSettings.Resize, EditSettings.Rotate, EditSettings.Drag |
Examples
Map1.setEditSetting(EditSettings.Reshape); Map1.setEditSetting(EditSettings.Resize); Map1.setEditSetting(EditSettings.Rotate); Map1.setEditSetting(EditSettings.Drag);
setCurrentBackgroundMapType
setCurrentBackgroundMapType: function ( backgroundMapType )
Change current OpenLayers third part layer’s type. Please reference the Google, Virtual Earth, or Yahoo API you registered on the web page, and then find what type of map they support.
For example, Google v2 support types: G_HYBRID_MAP, G_NORMAL_MAP, G_SATELLITE_MAP, G_PHYSICAL_MAP. Google v3 support types: google.maps.MapTypeId.HYBRID,google.maps.MapTypeId.ROADMAP,google.maps.MapTypeId.SATELLITE,google.maps.MapTypeId.TERRAIN
Yahoo supports: YAHOO_MAP_SAT, YAHOO_MAP_REG, YAHOO_MAP_HYB.
Virtual Earth supports: VEMapStyle.Road, VEMapStyle.Aerial, VEMapStyle.Hybrid. Please reference the latest API to get more supported Map Types.
Parameters
| backgroundMapType | {String} An Id of a layer which you added on the map. |
Examples
//If current map layer is Google: Map1.SetCurrentBackgroundMapType(G_HYBRID_MAP); //If current map layer is Virtual Earth: Map1.SetCurrentBackgroundMapType(VEMapStyle.Road); //If current map layer is Yahoo: Map1.SetCurrentBackgroundMapType(YAHOO_MAP_SAT);
ajaxCallAction
ajaxCallAction: function ( controller, action, params, callback )
Performs an asynchronous HTTP (Ajax) request to an action of the specified controller with parameters in JSON format.
It requires to access the paramters passed from here in action, it requires apllying the MapActionFilterAttribute to the specified action.
Parameters
| controller | {String} The name of the controller |
| action | {String} The name of the action |
| params | {object} The parameters in JSON format. |
| callback | {function} The callback function which is used to process the data sent from server. |
Examples
var params = {clickedX: 90.2657, clickedY: 60.2548};
var controller = "ClickToShowTheMarker";
var action = "UpdateMarker";
Map1.ajaxCallAction(controller, action, params,fucntion(result){
if (result.get_statusCode() != '404') {
var layerId = result.get_responseData();
Map1.redrawLayer(layerId);
}
});
ajaxCall
ajaxCall: function ( url, params, callback )
This is the override for function ajaxCallAction, it performs an asynchronous HTTP (Ajax) request to an action of the specified controller with parameters in JSON format.
It requires to access the paramters passed from here in action, it requires apllying the MapActionFilterAttribute to the specified action.
Parameters
| url | {String} the access URL that should contain a action applied MapActionFilterAttribute. |
| params | {object} The parameters in JSON format. |
| callback | {function} The callback function which is used to process the data sent from server. |
Examples
var params = {clickedX: 90.2657, clickedY: 60.2548};
Map1.ajaxCall('http://localhost/ClickToShowTheMarker/UpdateMarker?name="Jo"', params,fucntion(result){
if (result.get_statusCode() != '404') {
var layerId = result.get_responseData();
Map1.redrawLayer(layerId);
}
});