ui.rimMap

This is a jQuery widget encapsulating the MapDotNet UX RIM (Rich Interactive Mapping) HTML5 map control usage: $(myContainerDOMElement).rimMap('[widget function]', param1, param2...);

addFixedContentElement(element, mapUnitsX, mapUnitsY, addAction, dragOptions)

Add a fixed element to the content area which resides at a z-level above tiled map content. These elements do not scale with the map scale. This is used to place markers or callouts on the map.

Parameters

element - any html that can be added to the DOM
mapUnitsX - is the insertion point X value in map units
mapUnitsY - is the insertion point Y value in map units
addAction - is an optional function which is passed the DOM element after it is placed into the fixed element content area
dragOptions - is an optional object to support making the placed object draggable, the properties include:

  • dragEnabled is a boolean property that must be true to enable dragging
  • useElementInsteadOfNewGestureOverlay is a boolean defining whether to use the element as the event target or a gesture panel automatically created over the element which is helpful for composite elements
  • downAction is an optional function taking an isc.rim.point that is called when a pointer down occurs on the element (if your function returns an isc.rim.point, the start point will be updated to use your point).
  • moveAction is an optional function taking an isc.rim.point that is called when the element moves under pointer movement
  • upAction is an optional function taking an isc.rim.point that is called when a pointer up occurs on the element
  • wheelAction is an optional function taking an integer (1 or -1) that is called when a mouse wheel event occurs on the element

addPathGeometry(styledGeom, key)

Add a styled path geometry to the content area which resides at a z-level above tiled map content. The geometry is converted to SVG and added to the content area DOM. If an attempt to add a geometry is made with the same key, the geometry is swapped out. You must remove using removePathGeometry for resource cleanup.

Parameters

styledGeom - rim.styledGeometry to render
key - string used to tie a geometry to its SVG rendering in the DOM and is used to remove the geometry
addAction - optional function that takes the svg element added to the DOM by this method
removeAction - optional function that takes the svg element removed from the DOM by other methods
simplificationToleranceMapUnits - optional simplification tolerance in pixels >= 1 (if < 1 then simplification is omitted)

Returns

SVG path element added to the DOM

beginDigitize(beginDigitize)

Start a new manual digitizing path.

Parameters

options is an associative array with the following properties:
  • options.key is a unique key to identify shape (not required for envelope or circle)
  • options.shapeType is the type of shape to digitize using the key string 'polygon', 'polyline', 'multipoint', 'envelope' or 'circle'
  • options.geometryStyle is an optional isc.rim.geometryStyle for new paths, set this to enter new path mode
  • options.styledGeometry is an optional isc.rim.styledGeometry for existing paths to edit, set this to enter edit mode
  • options.nodeTapAndHoldAction is an optional function with the signature action(setIdx, idx)
  • + setIdx is the set index (0 based)
  • + idx is the x coordinate index into the set (0 based)
  • + if the action returns true, the node is deleted
  • options.nodeMoveAction is an optional function with the signature action(x, y, actionType)
  • + x is the x coordinate of the current node position
  • + y is the y coordinate of the current node position
  • + actionType is a string ('append', 'move')
  • + if the action returns an isc.rim.point the node will be moved to that position
  • shapeChangeAction is an optional function that is called anytime the digitized geometry changes (it takes no parameters as you can easily get a snapshot if desired)
  • shapeDragAction is an optional function that is called when a drag-envelope or drag-circle is changing through a drag action (it takes the start and end points)
  • envelopeEndAction is an optional function taking a single isc.rim.envelope parameter that is called at the end of envelope creation
  • circleEndAction is an optional function taking a single isc.rim.geometry.polygon parameter that is called at the end of circle creation
  • options.suppressNodeAdd is an optional boolean that will hide ghost nodes and prohibit adding nodes when true, default is false
  • options.leavePath is an optional boolean instructing the shape should be left on the drawing context after completion (either gesture or end of digitizing)

computeMapPointFromPixelLocation(x, y)

Gets a map point in map units from a supplied point in pixel units from the currently displayed extents.

Parameters

x - x coordiante in map pixels
y - y coordinate in map pixels

Return

converted point as an isc.rim.point

deleteNodeOnDigitizePath()

Programatically delete a node (or nodes) while digitizing

Parameters

setIdx - the set index (0-based) of the ring or path to remove the node from
nodeIdx - the node index to remove (0-based) in the specified ring or path optional count (defaults to 1) item to delete

endDigitize()

End manual digitizing from a call to beginDigitize

Returns

isc.rim.styledGeometry of the final shape digitized except for envelopes which are passed into the envelope end-action

flyTo(mc, zl, duration, onCompleteAction)

Animates between two locations (map center and zoom level) and does so as a parabolic path.

Parameters

mc - destination map center as an isc.rim.point
zl - destination zoom level as an integer
duration - animation duration as a float in mS
onCompleteAction - optional function, if provided, is call when the animation is completed

getActualMapScale()

Gets the current actual map scale. This is the ratio of units on the screen to actual units on the earth's surface at the latitude of the current map center.

Return

ratio (1 to N) as a float

getBestFitZoomLevelByExtents(extentsNew)

Gets the best fit zoom level based on the supplied map extents for the current display extents in pixels.

Parameters

extentsNew - the new map extents to fit to as an isc.rim.envelope

Return

integer between the min and max supported zoom levels.

getDigitizeSnapshot()

Get a snapshot copy of the current digitizing path while editing.

Returns

isc.rim.geometry

getMapCenter()

Gets the center of the map in spherical mercator. Use isc.rim.sphericalMercator.deprojectToLatLon static function to convert to a lat/lon.

Return

isc.rim.point map center.

getMapExtents()

Gets the current map extents in spherical mercator units

Return

isc.rim.envelope map extents

getMapUnitsPerPixel()

Gets the current map units per pixel (meters)

Return

meters as a float

getProjectedMapScale()

Gets the current projected map scale. This is the ratio of units on the screen to map units depicted.

Return

ratio (1 to N) as a float

getTileLayer(key)

Gets a tile layer on the display stack by its key

Return

the tile layer found as an isc.rim.tile.layer or null if not found

getTileLayerCount()

Gets the current number of tile layers on the display stack

Return

count as an integer.

getViewExtentsInPix()

Gets the map extents width and height in pixels

Return

associative array
  • w: width in pixels as an integer
  • h: height in pixels as an integer

getZoomLevel()

Gets the current zoom level from 1 to 20

Return

zoom level as a float

insertNodeOnDigitizePath()

Programatically insert a node while digitizing

Parameters

ptArr = point or points to insert as an isc.rim.point array

setIdx - the set index (0-based) of the ring or path to insert the node on
nodeIdx - the node index to insert (0-based) in the specified ring or path

isDigitizingEnabled()

Return true if digitizing is enabled

Returns

true if digitizing is enabled, otherwise false

moveFixedContentElement(element, mapUnitsX, mapUnitsY)

Move an existing fixed element on the content area.

Parameters

element - is the existing DOM element to move
mapUnitsX - is the new point X value in map units
mapUnitsY - is the new point Y value in map units
duration - optional float in mS to animate the movement of the element

moveNodeOnDigitizePath()

Programatically move a node while digitizing

Parameters

pt = point to move the node to as an isc.rim.point

setIdx - the set index (0-based) of the ring or path to move the node on
nodeIdx - the node index to remove (0-based) in the specified ring or path

offsetMapCenterByPixelDelta(dx, dy)

Offsets the current map center by the specified deltas in pixels.

Parameters

dx - delta x in pixels
dy - delta y in pixels

offsetMapCenterByPixelDeltaAnimate(dx, dy)

Offsets the current map center by the specified deltas in pixels, animated version.

Parameters

dx - delta x in pixels
dy - delta y in pixels
duration - float in mS

options

Widget options that may be passed in during create.

Parameters

  • mapCenter in spherical mercator as {x:??, y:??} or an isc.rim.point, can also be a ko observable if this option set is used in a rimMap data-bind
  • zoomLevel from 1 to 20 (integer), can also be a ko observable if this option set is used in a rimMap data-bind
  • onGeoLocated is an optional function (takes no parameters) and is called if the map successfully uses geolocation to set the map center.
  • stopPointerEventPropagation is an option to stop all pointer event propagation (defaults to true) - you may want to turn this off if you need to process pointer events over the map
  • drawnContentZorderToTop sets the z-order of drawn content in relation to the gesture capture panel. If true, is on top of gesture capture panel. Defaults to false.
  • contentExtentsMarginInPixels sets the number of pixel margin to fetch tiles around the perimeter of the map (defaults to 128). Increase for very large maps and decrease for smaller (mobile) maps.
  • mouseWheelZoomsOverCenter (default false) when set to true, zooms over map center instead of the default behavior of over mouse pointer
  • extentChangeCompleteAction is a function called when the map extents have stopped changing (e.g. after an animated pan or zoom).
  • contentRepositionAction is a function called when tiled content or fixed element content is repositioned in the DOM at the map is panned and zoomed
  • pointerClickAction is a function to call on a pointer click event on the map.
  • pointerHoverAction is a function to call on a pointer hover event over the map.
  • mapInitializeLocationAction is an optional function with two parameters, an instance of this map and a callback function which takes a map center (either isc.rim.point or {x: ??, y: ??}) and zoom level.
  • mapInitializedAction is an optional function to call after the map has constructed its elements in the DOM, inline layers added and optionally located. It is passed an instance of this map.
  • layers is an optional array of isc.rim.tile.layer or isc.rim.tile.layerOptions to facilitate a nested associative array declaration style
  • navigatorGeolocationFailAction is an optional function to call when the map cannot position itself because a geolocation call failed. It is passed the PositionError from the navigator.geolocation.getCurrentPosition call. The method can return an isc.rim.point for position, or null. Position, if provided, shuld be in Spherical Mercator.

popSetFromDigitizePath()

Remove last set from the digitizing path

popTileLayer()

Pop an isc.rim.tile.layer off of the top of the display stack.

Return

the removed tile layer as an isc.rim.tile.layer

pushSetOnDigitizePath()

Add set to the end of the digitizing path

pushTileLayer(tl)

Push an isc.rim.tile.layer onto the top of the display stack.

Parameters

tl - an isc.rim.tile.layer

redraw()

Forces the map to redraw the currently loaded tile and geometry content. You should not have to call this as redraws are automatically handled during programatic state changes. This would be for edge cases where the developer is affecting internal state in an undocumented way.

removeAllTileLayers()

Remove all isc.rim.tile.layer instances off the display stack.

removeFixedContentElement(element)

Remove a fixed element from the display by reference.

Parameters

element - a DOM element added via addFixedContentElement

removePathGeometry(key)

Remove a styledGeometry from the display by its key.

Parameters

key - a string used to lookup the geometry to remove based on the key used in addPathGeometry

Returns

SVG path element removed from the DOM

removeTileLayer(tl)

Remove an isc.rim.tile.layer instance off the display stack by reference.

Parameters

tl - an isc.rim.tile.layer

resize()

Updates the map to the size of its container. This updates internal parameters for computing map extents and handling the amount of tile content to download. This is handled automatically if the browser window is resized. But if you are sizing the map programatically (e.g. resizable panel or slider) then call this after the parent container has resized.

setBackground(b)

Sets the background style on the map widget.

Parameters

b - a background css string.

setContentExtentsMarginInPixels(cem)

Sets the margin around the map in pixels for extra content fetched so that tile rebuilding of the display is minimized. This is an advanced property and does not generally need to be adjusted. The default is 128 pixel (one half tile width) Increase for very large maps (width and height in pixels is large) or panning is active. Decrease for very small maps (e.g. mobile devices) or where panning is minimal.

Parameters

cem - a pixel margin as an integer

setContentRepositionAction(a)

Set the function called when map content (map tiles and fixed elements) are re-positioned in the DOM This is done automatically as the map is panned beyond existing content and zoomed to a new level requiring content.

Parameters

a - an action (function reference) that takes one parameter. The parameter passed in is an associative array with the following keys:
  • centerX
  • centerY
  • zoomLevel
  • mapUnitsPerPixel

setDrawnContentZorderToTop(order)

Sets the z-order of drawn content in relation to the gesture capture panel. The default behavior (false) is to have fixed content and geometry underneath the gesture panel in the DOM. If false, all pointer events are handled by the gesture capture panel and optionally parents of the map control. If true, drawn content will receive pointer events first and will block gestures to the map. If true, digitizing will not function and polygons will block map navigation. In some scenarios you may want to set this to true if you are placing fixed-content (such as point features) on the map and need to handle gestures on the placed content. You can call this function at any time to change the order.

Parameters

order - order of the drawn content area in relation to the gesture capture panel. False (default) is below and True is above.

setExtentChangeCompleteAction(a)

Set the function called when the map extents have stopped changing (e.g. after an animated pan or zoom).

Parameters

a - an action (function reference) that takes one parameter. The parameter passed in is an associative array with the following keys:
  • centerX
  • centerY
  • centerLat
  • centerLon
  • zoomLevel
  • mapScale (actual ground scale)
  • mapScaleProjected (map projection scale)
  • mapUnitsPerPixel
  • extents

setMapCenter(mc)

Sets the center of the map in spherical mercator. Use isc.rim.sphericalMercator.projectFromLatLon static function to convert from a lat/lon.

Parameters

mc - map center as an isc.rim.point

setMapCenterAnimate(mc, duration)

Same as setMapCenter except will animate from current map center to the specified location

Parameters

mc - map center as an isc.rim.point
duration - float in mS
onCompleteAction - optional function, if provided, is called when the animation is completed

setMapCenterToGeolocationAnimate(duration, onCompleteAction)

Sets the map center to the current geolocation if supported. The map is animated to the new location.

Parameters

duration - float in mS
onCompleteAction - optional function, if provided, is called when the animation is completed

setMaxZoomLevel(zl)

Sets the maximum zoom level for the map.

Parameters

zl - zoom level as an integer.

setMinZoomLevel(zl)

Sets the minimum zoom level for the map.

Parameters

zl - zoom level as an integer.

setPointerClickAction(a)

Set the function called when the map is clicked (left mouse click or touch on mobile).

Parameters

a - an action (function reference) that takes one parameter.
ptMapUnits - isc.rim.point in map units where clicked.

setPointerHoverAction(a)

Set the function called when the map pointer is moved and then hovers.

Parameters

a - an action (function reference) that takes one parameter.
ptMapUnits - isc.rim.point in map units where hovered.

setSuspendMapExtentChangesByGestures(suspend)

Determines whether or not map extent changes can occur through gestures like mouse or touch drag, mouse wheel or pinch zoom.

Parameters

suspend - set to true to freeze the map and prevent all map extent changes through gestures, or false to resume normal behavior.

setZoomLevel(zl)

Sets the current zoom level from 1 to 20

Parameters

zl - zoom level as an integer.

setZoomLevelAnimate(zl, duration)

Same as setZoomLevel but animates from the current zoom level to the new value

Parameters

zl - zoom level as an integer
duration - float in mS
onCompleteAction - optional function, if provided, is called when the animation is completed

undoLastDigitizePathChange()

Programatically undo the last shape change to the digitize path.

updatePathGeometryStyle(styleNew, key)

Update an existing path geometry to reflect a style change.

Parameters

styleNew - a new isc.rim.geometryStyle
key - string used to identify an existing isc.rim.styledGeometry in the DOM that was added by addPathGeometry
simplificationToleranceMapUnits - optional simplification tolerance in pixels >= 1 (if < 1 then simplification is omitted)

zoomDelta(dz)

Updates the current zoom level by applying a delta.

Parameters

dz - integer zoom level delta to apply

zoomDeltaAnimate(dz, duration)

Same as zoomDelta but animates from the current zoom level to the new value

Parameters

dz - integer zoom level delta to apply
duration - float in mS

Copyright 2017, EasyTerritory, All Rights Reserved

Created with TwinText