How to add the Locate Me function (aka Get Location)

The Locate Me function (aka Get Location) allows the user to show their physical location on the current map. This function uses the Geolocation API and therefore the user's device must contain a wireless card (Wi-Fi) and/or a GPS in order for the location to be accurate. If the device does not contain either of those devices, the location will be estimated based on the user's IP address, which will very likely be inaccurate.
 
IMPORTANT NOTE: the functions on this page are added as custom command buttons to the map toolbar. See that article for how to add such a button.
 

Locate Me / Get Location

 
This function allows a user to show their physical location on the current map by clicking the associated button.
 
Configure the button for the target Web Layout as follows:
 
Under the Settings tab, enter the following (you can change these values if you wish):
 
 
    Command name: Locate Me
    Name to display in the interface: Locate Me
    Tool tip to appear on hover: Locate Me
    Description to appear on the status barLocate Me
    URL to an image for enabled state: ../stdicons/icon_restorecenter.gif
    URL to an image for disabled state: ../stdicons/icon_restorecenter_disabled.gif
 
Under the Additional Parameters tab, enter the following under Script to invoke:
 
(function () {
     var legendLabel = "";
     var selectMapTab = true;
     var zoomToViewAtCurrentScale = true;
     var refreshMap = true;
     var maximumAge = 5000;
     var timeout = 10000;
     var enableHighAccuracy = false;
     var useWatchPosition = false;
     var useWatchPositionUntil = 20000;
     var locationIsSelectable = false;
 
    WSD.GetLocation(legendLabel, selectMapTab, zoomToViewAtCurrentScale, refreshMap, maximumAge, timeout, enableHighAccuracy, useWatchPosition, useWatchPositionUntil, locationIsSelectable);
 })();
 
For builds 1608 and before, use parent.GetLocation(); instead of this script.
 
You may adjust the various parameters as desired. Note that the Locate Me function makes use of the Geolocation API, and that more detail about the maximumAge, timeout, and timeout parameters can be found here.
 
The parameters work as follows:
 
legendLabel: The legend label to use for the point that will be added to the map to indicate the location. Leaving this parameter set to "" causes the label to be set to "Current Location".
selectMapTab: Whether or not to switch to the map tab once the location is found.
zoomToViewAtCurrentScale: Whether or not to zoom to the location at the current zoom scale once the location is found.
refreshMap: Whether or not to refresh the map once the location is found. This should be set to true.
maximumAge: The maximum age in milliseconds that a cached location (that is acceptable) can be used. Setting this to 0 prevents a cached location from being used.
timeout: The number of milliseconds to wait for a location to be found. If no location is found before the timeout is reached, an error will occur.
enableHighAccuracy: Whether or not to try and find a more accurate location (using, for example, the GPS on a device) at the expense of extra time and/or power.
useWatchPosition: Uses the watchPosition() function from the Geolocation API (this is used by the Start Watching Location function) to watch for location changes until useWatchPositionUntil milliseconds have passed. Using this may provide more accurate results.
useWatchPositionUntil: The number of milliseconds to watch for location changes when using useWatchPosition (this is ignored otherwise).
locationIsSelectable: Whether or not the point added to the map to indicate the location is selectable or not.
 
Note: locationIsSelectable only works in builds 2502 or higher (it will be ignored in lower builds).
 
Note that the Locate Me function will not drop a point if the browser determines that the user falls in a location outside of the bounds of the current map. Additionally, a user may need elevated privileges in the browser in order for this function to work properly.
 
If you wish to use more than one set of parameters at once (for example, one button that zooms to the current location and one that does not), simply make another script using these same steps and add another button to the toolbar.
 

Start Watching Location

The Locate Me function only gets the current location one time when its button is pressed. The Start Watching Location function allows the user's current location to be constantly updated; this is useful if the user is traveling in the field. If you decide to use this function, you should also add the Stop Watching Location function (described below) so that the user can stop the location watch if they desire (it will also stop if they reload the browser page).
 
Configure the button for the target Web Layout as follows:
 
Under the Settings tab, enter the following (you can change these values if you wish):
 
 
    Command name: Start Watching Location
    Name to display in the interface: Start Watching Location
    Tool tip to appear on hover: Start Watching Location
    Description to appear on the status bar: Start Watching Location
    URL to an image for enabled state: ../stdicons/icon_popupscrolldown.gif
    URL to an image for disabled state: ../stdicons/icon_popupscrolldown_disabled.gif
 
Under the Additional Parameters tab, enter the following under Script to invoke:
 
(function () {
     var legendLabel = "";
     var selectMapTab = true;
     var zoomToViewAtCurrentScale = true;
     var refreshMap = true;
     var maximumAge = 5000;
     var timeout = 10000;
     var enableHighAccuracy = false;
     var enableWatchTimeLimiting = false;
     var watchTime = 10000;
     var idleTime = 30000;
     var locationIsSelectable = false;
 
    WSD.StartWatchingLocation(legendLabel, selectMapTab, zoomToViewAtCurrentScale, refreshMap, maximumAge, timeout, enableHighAccuracy, enableWatchTimeLimiting, watchTime, idleTime, locationIsSelectable);
 })();
 
You may adjust the various parameters as desired. Note that the Start Watching Location function makes use of the Geolocation API, and that more detail about the maximumAge, timeout, and timeout parameters can be found here.
 
The parameters work as follows:
 
legendLabel: The legend label to use for the point that will be added to the map to indicate the location. Leaving this parameter set to "" causes the label to be set to "Current Location".
selectMapTab: Whether or not to switch to the map tab once the location is found.
zoomToViewAtCurrentScale: Whether or not to zoom to the location at the current zoom scale once the location is found.
refreshMap: Whether or not to refresh the map once the location is found. This should be set to true.
maximumAge: The maximum age in milliseconds that a cached location (that is acceptable) can be used. Setting this to 0 prevents a cached location from being used.
timeout: The number of milliseconds to wait for a location to be found. If no location is found before the timeout is reached, an error will occur.
enableHighAccuracy: Whether or not to try and find a more accurate location (using, for example, the GPS on a device) at the expense of extra time and/or power.
enableWatchTimeLimiting: Whether or not to limit the amount of time that the browser watches for a new location (it will watch for watchTime milliseconds, then wait idleTime milliseconds, then watch again, etc.). This can be useful to prevent constant location updates from draining the battery of the device.
watchTime: The number of milliseconds to watch for location changes when using enableWatchTimeLimiting (this is ignored otherwise).
idleTime: The number of milliseconds to stop watching for location changes when using enableWatchTimeLimiting (this is ignored otherwise).
locationIsSelectable: Whether or not the point added to the map to indicate the location is selectable or not.
 
Note: locationIsSelectable only works in builds 2502 or higher (it will be ignored in lower builds).

Stop Watching Location

This function stops the location watch started by the Start Watching Location function. Note that this is implicitly called if the user reloads the browser page.
 
Configure the button for the target Web Layout as follows:
 
Under the Settings tab, enter the following (you can change these values if you wish):
 
   
    Command name: Stop Watching Location
    Name to display in the interface: Stop Watching Location
    Tool tip to appear on hover: Stop Watching Location
    Description to appear on the status bar: Stop Watching Location
    URL to an image for enabled state: ../stdicons/icon_error.gif
    URL to an image for disabled state: ../stdicons/icon_error.gif
 
Under the Additional Parameters tab, enter the following under Script to invoke:
 
   
    WSD.StopWatchingLocation();
 
 
[Last updated for version 2904 (04/2013)]
Comments