Util
| Util | |||
| Functions and Properties | |||
| getElement | This is the old $() from prototype | ||
| isElement | A cross-browser implementation of “e instanceof Element”. | ||
| isArray | Tests that the provided object is an array. | ||
| removeItem | Remove an object from an array. | ||
| indexOf | Seems to exist already in FF, but not in MOZ. | ||
| modifyDOMElement | Modifies many properties of a DOM element all at once. | ||
| createDiv | Creates a new div and optionally set some standard attributes. | ||
| createImage | Creates an img element with specific attribute values. | ||
| IMAGE_RELOAD_ATTEMPTS | {Integer} How many times should we try to reload an image before giving up? | ||
| makeInitOnceGetter | Returns a function that initializes a value once, and then just returns the value on subsequent calls | ||
| alphaHack | Checks whether it’s necessary (and possible) to use the png alpha hack which allows alpha transparency for png images under Internet Explorer. | ||
| modifyAlphaImageDiv | |||
| createAlphaImageDiv | |||
| upperCaseObject | Creates a new hashtable and copies over all the keys from the passed-in object, but storing them under an uppercased version of the key at which they were stored. | ||
| applyDefaults | Takes an object and copies any properties that don’t exist from another properties, by analogy with ALKMaps.Util.extend() from Prototype.js. | ||
| getParameterString | |||
| urlAppend | Appends a parameter string to a url. | ||
| getImagesLocation | {String} The fully formatted image location string | ||
| getImageLocation | {String} The fully formatted location string for a specified image | ||
| Try | Execute functions until one of them doesn’t throw an error. | ||
| getXmlNodeValue | |||
| mouseLeft | |||
| precision | {Number} The number of significant digits to retain to avoid floating point precision errors. | ||
| toFloat | Convenience method to cast an object to a Number, rounded to the desired floating point precision. | ||
| rad | |||
| deg | |||
| VincentyConstants | {Object} Constants for Vincenty functions. | ||
| distVincenty | Given two objects representing points with geographic coordinates, this calculates the distance between those points on the surface of an ellipsoid. | ||
| destinationVincenty | Calculate destination point given start point lat/long (numeric degrees), bearing (numeric degrees) & distance (in m). | ||
| getParameters | Parse the parameters from a URL or from the current page itself into a JavaScript Object. | ||
| createUniqueID | Create a unique identifier for this session. | ||
| Constants | |||
| INCHES_PER_UNIT | {Object} Constant inches per unit -- borrowed from MapServer mapscale.c derivation of nautical miles from https://en.wikipedia.org/wiki/Nautical_mile Includes the full set of units supported by CS-MAP (http://trac.osgeo.org/csmap/) and PROJ.4 (https://proj.org/) The hardcoded table is maintain in a CS-MAP source code module named CSdataU.c The hardcoded table of PROJ.4 units are in pj_units.c. | ||
| DOTS_PER_INCH | {Integer} 72 (A sensible default) | ||
| Functions | |||
| normalizeScale | |||
| getResolutionFromScale | |||
| getScaleFromResolution | |||
| pagePosition | Calculates the position of an element on the page | getViewportElement | Returns die viewport element of the document. |
| isEquivalentUrl | Test two URLs for equivalence. | ||
| createUrlObject | |||
| removeTail | Takes a url and removes everything after the ? | ||
| Constants | |||
| IS_GECKO | {Boolean} True if the userAgent reports the browser to use the Gecko engine | ||
| CANVAS_SUPPORTED | {Boolean} True if canvas 2d is supported. | ||
| BROWSER_NAME | {String} A substring of the navigator.userAgent property. | ||
| Functions | |||
| getBrowserName | {String} A string which specifies which is the current browser in which we are running. | ||
| getRenderedDimensions | Renders the contentHTML offscreen to determine actual dimensions for popup sizing. | ||
| getScrollbarWidth | This function has been modified by the ALKMaps from the original version, written by Matthew Eernisse and released under the Apache 2 license here: | ||
| getFormattedLonLat | This function will return latitude or longitude value formatted as | ||
| buildTableCell | Deprecated. | ||
| buildTableOrRow | Deprecated. | ||
| convertToStringArray | Convert string to string array. | ||
| getRegion | Determines the correct region number for the corresponding enumeration string, and defaults to NA(4). | ||
| getDataSet | Determines if the value of the dataset passed in is valid, and if not defaults to Current. | ||
| getDatasetFromRegion | Returns the dataset corresponding to the given region. | ||
| rgbToHex | Convert RGB value to HEX | ||
| hexToRgb | Converts hex to rgb. | ||
| buildLabelElement | This method can be used to build HTML lable element. | ||
| buildSelectElement | Build HTML Select element with options. | ||
| getScriptSrc | Gets the source path from the HTML script tag of the given file. | ||
| getAPIKey | Gets the user given API key from either the script query string or the ALKMaps property. | ||
| getYear | Gets the current year. | ||
| enableContextMenu | Enables the default right-click context menu of the provided div; | ||
| disableContextMenu | Disables the default right-click context menu of the provided div; |
modifyDOMElement
ALKMaps.Util.modifyDOMElement = function ( element, id, px, sz, position, border, overflow, opacity )
Modifies many properties of a DOM element all at once. Passing in null to an individual parameter will avoid setting the attribute.
Parameters
| element | {DOMElement} DOM element to modify. |
| id | {String} The element id attribute to set. |
| px | {<ALKMaps.Pixel>|Object} The element left and top position, ALKMaps.Pixel or an object with a ‘x’ and ‘y’ properties. |
| sz | {<ALKMaps.Size>|Object} The element width and height, ALKMaps.Size or an object with a ‘w’ and ‘h’ properties. |
| position | {String} The position attribute. eg: absolute, relative, etc. |
| border | {String} The style.border attribute. eg: solid black 2px |
| overflow | {String} The style.overview attribute. |
| opacity | {Float} Fractional value (0.0 - 1.0) |
createDiv
ALKMaps.Util.createDiv = function ( id, px, sz, imgURL, position, border, overflow, opacity )
Creates a new div and optionally set some standard attributes. Null may be passed to each parameter if you do not wish to set a particular attribute. Note - zIndex is NOT set on the resulting div.
Parameters
| id | {String} An identifier for this element. If no id is passed an identifier will be created automatically. |
| px | {<ALKMaps.Pixel>|Object} The element left and top position, ALKMaps.Pixel or an object with a ‘x’ and ‘y’ properties. |
| sz | {<ALKMaps.Size>|Object} The element width and height, ALKMaps.Size or an object with a ‘w’ and ‘h’ properties. |
| imgURL | {String} A url pointing to an image to use as a background image. |
| position | {String} The style.position value. eg: absolute, relative etc. |
| border | {String} The the style.border value. eg: 2px solid black |
| overflow | {String} The style.overflow value. Eg. hidden |
| opacity | {Float} Fractional value (0.0 - 1.0) |
Returns
{DOMElement} A DOM Div created with the specified attributes.
createImage
ALKMaps.Util.createImage = function ( id, px, sz, imgURL, position, border, opacity, delayDisplay )
Creates an img element with specific attribute values.
Parameters
| id | {String} The id field for the img. If none assigned one will be automatically generated. |
| px | {<ALKMaps.Pixel>|Object} The element left and top position, ALKMaps.Pixel or an object with a ‘x’ and ‘y’ properties. |
| sz | {<ALKMaps.Size>|Object} The element width and height, ALKMaps.Size or an object with a ‘w’ and ‘h’ properties. |
| imgURL | {String} The url to use as the image source. |
| position | {String} The style.position value. |
| border | {String} The border to place around the image. |
| opacity | {Float} Fractional value (0.0 - 1.0) |
| delayDisplay | {Boolean} If true waits until the image has been loaded. |
Returns
{DOMElement} A DOM Image created with the specified attributes.
modifyAlphaImageDiv
ALKMaps.Util.modifyAlphaImageDiv = function ( div, id, px, sz, imgURL, position, border, sizing, opacity )
Parameters
| div | {DOMElement} Div containing Alpha-adjusted Image |
| id | {String} |
| px | {<ALKMaps.Pixel>|Object} ALKMaps.Pixel or an object with a ‘x’ and ‘y’ properties. |
| sz | {<ALKMaps.Size>|Object} ALKMaps.Size or an object with a ‘w’ and ‘h’ properties. |
| imgURL | {String} |
| position | {String} |
| border | {String} |
| sizing | {String} ‘crop’, ‘scale’, or ‘image’. Default is “scale” |
| opacity | {Float} Fractional value (0.0 - 1.0) |
createAlphaImageDiv
ALKMaps.Util.createAlphaImageDiv = function ( id, px, sz, imgURL, position, border, sizing, opacity, delayDisplay )
Parameters
| id | {String} |
| px | {<ALKMaps.Pixel>|Object} ALKMaps.Pixel or an object with a ‘x’ and ‘y’ properties. |
| sz | {<ALKMaps.Size>|Object} ALKMaps.Size or an object with a ‘w’ and ‘h’ properties. |
| imgURL | {String} |
| position | {String} |
| border | {String} |
| sizing | {String} ‘crop’, ‘scale’, or ‘image’. Default is “scale” |
| opacity | {Float} Fractional value (0.0 - 1.0) |
| delayDisplay | {Boolean} If true waits until the image has been loaded. |
Returns
{DOMElement} A DOM Div created with a DOM Image inside it. If the hack is needed for transparency in IE, it is added.
upperCaseObject
ALKMaps.Util.upperCaseObject = function ( object )
Creates a new hashtable and copies over all the keys from the passed-in object, but storing them under an uppercased version of the key at which they were stored.
Parameters
| object | {Object} |
Returns
{Object} A new Object with all the same keys but uppercased
applyDefaults
ALKMaps.Util.applyDefaults = function ( to, from )
Takes an object and copies any properties that don’t exist from another properties, by analogy with ALKMaps.Util.extend() from Prototype.js.
Parameters
| to | {Object} The destination object. |
| from | {Object} The source object. Any properties of this object that are undefined in the to object will be set on the to object. |
Returns
{Object} A reference to the to object. Note that the to argument is modified in place and returned by this function.
getParameterString
ALKMaps.Util.getParameterString = function ( params )
Parameters
| params | {Object} |
Returns
{String} A concatenation of the properties of an object in http parameter notation. (ex. <i>”key1=value1&key2=value2&key3=value3”</i>) If a parameter is actually a list, that parameter will then be set to a comma-separated list of values (foo,bar) instead of being URL escaped (foo%3Abar).
urlAppend
ALKMaps.Util.urlAppend = function ( url, paramStr )
Appends a parameter string to a url. This function includes the logic for using the appropriate character (none, & or ?) to append to the url before appending the param string.
Parameters
| url | {String} The url to append to |
| paramStr | {String} The param string to append |
Returns
{String} The new url
Try
ALKMaps.Util.Try = function ()
Execute functions until one of them doesn’t throw an error. Capitalized because “try” is a reserved word in JavaScript.
Parameters
| [*] | {Function} Any number of parameters may be passed to Try() It will attempt to execute each of them until one of them successfully executes. If none executes successfully, returns null. |
Returns
{*} The value returned by the first successfully executed function.
precision
{Number} The number of significant digits to retain to avoid floating point precision errors.
We use 14 as a “safe” default because, although IEEE 754 double floats (standard on most modern operating systems) support up to about 16 significant digits, 14 significant digits are sufficient to represent sub-millimeter accuracy in any coordinate system that anyone is likely to use with ALKMaps.
If DEFAULT_PRECISION is set to 0, the original non-truncating behavior of ALKMaps <2.8 is preserved. Be aware that this will cause problems with certain projections, e.g. spherical Mercator.
toFloat
ALKMaps.Util.toFloat = function ( number, precision )
Convenience method to cast an object to a Number, rounded to the desired floating point precision.
Parameters
| number | {Number} The number to cast and round. |
| precision | {Number} An integer suitable for use with Number.toPrecision(). Defaults to ALKMaps.Util.DEFAULT_PRECISION. If set to 0, no rounding is performed. |
Returns
{Number} The cast, rounded number.
distVincenty
ALKMaps.Util.distVincenty = function ( p1, p2 )
Given two objects representing points with geographic coordinates, this calculates the distance between those points on the surface of an ellipsoid.
Parameters
| p1 | {ALKMaps.LonLat} (or any object with both .lat, .lon properties) |
| p2 | {ALKMaps.LonLat} (or any object with both .lat, .lon properties) |
Returns
{Float} The distance (in km) between the two input points as measured on an ellipsoid. Note that the input point objects must be in geographic coordinates (decimal degrees) and the return distance is in kilometers.
destinationVincenty
ALKMaps.Util.destinationVincenty = function ( lonlat, brng, dist )
Calculate destination point given start point lat/long (numeric degrees), bearing (numeric degrees) & distance (in m). Adapted from Chris Veness work, see https://www.movable-type.co.uk
Parameters
| lonlat | {ALKMaps.LonLat} (or any object with both .lat, .lon properties) The start point. |
| brng | {Float} The bearing (degrees). |
| dist | {Float} The ground distance (meters). |
Returns
{ALKMaps.LonLat} The destination point.
getParameters
ALKMaps.Util.getParameters = function ( url )
Parse the parameters from a URL or from the current page itself into a JavaScript Object. Note that parameter values with commas are separated out into an Array.
Parameters
| url | {String} Optional url used to extract the query string. If url is null or is not supplied, query string is taken from the page location. |
Returns
{Object} An object of key/value pairs from the query string.
createUniqueID
Create a unique identifier for this session. Each time this function is called, a counter is incremented. The return will be the optional prefix (defaults to “id_”) appended with the counter value.
Parameters
prefix {String} Optional string to prefix unique id. Default is “id_”.
Returns
{String} A unique id string, built on the passed in prefix.
INCHES_PER_UNIT
{Object} Constant inches per unit -- borrowed from MapServer mapscale.c derivation of nautical miles from https://en.wikipedia.org/wiki/Nautical_mile Includes the full set of units supported by CS-MAP (http://trac.osgeo.org/csmap/) and PROJ.4 (https://proj.org/) The hardcoded table is maintain in a CS-MAP source code module named CSdataU.c The hardcoded table of PROJ.4 units are in pj_units.c.
getResolutionFromScale
ALKMaps.Util.getResolutionFromScale = function ( scale, units )
Parameters
| scale | {Float} |
| units | {String} Index into ALKMaps.INCHES_PER_UNIT hashtable. Default is degrees |
Returns
{Float} The corresponding resolution given passed-in scale and unit parameters. If the given scale is falsey, the returned resolution will be undefined.
pagePosition
ALKMaps.Util.pagePosition = function ( forElement )
Calculates the position of an element on the page
getViewportElement
Returns die viewport element of the document. The viewport element is usually document.documentElement, except in IE,where it is either document.body or document.documentElement, depending on the document’s compatibility mode
isEquivalentUrl
ALKMaps.Util.isEquivalentUrl = function ( url1, url2, options )
Test two URLs for equivalence.
Setting ‘ignoreCase’ allows for case-independent comparison.
Comparison is based on
- Protocol
- Host (evaluated without the port)
- Port (set ‘ignorePort80’ to ignore “80” values)
- Hash ( set ‘ignoreHash’ to disable)
- Pathname (for relative <-> absolute comparison)
- Arguments (so they can be out of order)
Parameters
| url1 | {String} |
| url2 | {String} |
| options | {Object} Allows for customization of comparison: |
| ’ignoreCase’ | Default is True |
| ’ignorePort80’ | Default is True |
| ’ignoreHash’ | Default is True |
Returns
{Boolean} Whether or not the two URLs are equivalent
createUrlObject
ALKMaps.Util.createUrlObject = function ( url, options )
Parameters
| url | {String} |
| options | {Object} A hash of options. |
Valid options
| ignoreCase | {Boolean} lowercase url, |
| ignorePort80 | {Boolean} don’t include explicit port if port is 80, |
| ignoreHash | {Boolean} Don’t include part of url after the hash (#). |
Returns
{Object} An object with separate url, a, port, host, and args parsed out and ready for comparison
getBrowserName
ALKMaps.Util.getBrowserName = function ()
Returns
{String} A string which specifies which is the current browser in which we are running.
Currently-supported browser detection and codes
- ’opera’ -- Opera
- ’msie’ -- Internet Explorer
- ’safari’ -- Safari
- ’firefox’ -- Firefox
- ’mozilla’ -- Mozilla
If we are unable to property identify the browser, we return an empty string.
getRenderedDimensions
ALKMaps.Util.getRenderedDimensions = function ( contentHTML, size, options )
Renders the contentHTML offscreen to determine actual dimensions for popup sizing. As we need layout to determine dimensions the content is rendered -9999px to the left and absolute to ensure the scrollbars do not flicker
Parameters
contentHTML size - {ALKMaps.Size} If either the ‘w’ or ‘h’ properties is specified, we fix that dimension of the div to be measured. This is useful in the case where we have a limit in one dimension and must therefore measure the flow in the other dimension. options - {Object}
Allowed Options
| displayClass | {String} Optional parameter. A CSS class name(s) string to provide the CSS context of the rendered content. |
| containerElement | {DOMElement} Optional parameter. Insert the HTML to this node instead of the body root when calculating dimensions. |
Returns
getScrollbarWidth
ALKMaps.Util.getScrollbarWidth = function ()
This function has been modified by the ALKMaps from the original version, written by Matthew Eernisse and released under the Apache 2 license here:
http://www.fleegix.org
It has been modified simply to cache its value, since it is physically impossible that this code could ever run in more than one browser at once.
Returns
{Integer}
getFormattedLonLat
ALKMaps.Util.getFormattedLonLat = function ( coordinate, axis, dmsOption )
This function will return latitude or longitude value formatted as
Parameters
| coordinate | {Float} the coordinate value to be formatted |
| axis | {String} value of either ‘lat’ or ‘lon’ to indicate which axis is to to be formatted (default = lat) |
| dmsOption | {String} specify the precision of the output can be one of: ‘dms’ show degrees minutes and seconds ‘dm’ show only degrees and minutes ‘d’ show only degrees |
Returns
{String} the coordinate value formatted as a string
This is the old $() from prototype
ALKMaps.Util.getElement = function ()
A cross-browser implementation of “e instanceof Element”.
ALKMaps.Util.isElement = function ( o )
Tests that the provided object is an array.
ALKMaps.Util.isArray = function ( a )
Remove an object from an array.
ALKMaps.Util.removeItem = function ( array, item )
Seems to exist already in FF, but not in MOZ.
ALKMaps.Util.indexOf = function ( array, obj )
Modifies many properties of a DOM element all at once.
ALKMaps.Util.modifyDOMElement = function ( element, id, px, sz, position, border, overflow, opacity )
Creates a new div and optionally set some standard attributes.
ALKMaps.Util.createDiv = function ( id, px, sz, imgURL, position, border, overflow, opacity )
Creates an img element with specific attribute values.
ALKMaps.Util.createImage = function ( id, px, sz, imgURL, position, border, opacity, delayDisplay )
Returns a function that initializes a value once, and then just returns the value on subsequent calls
ALKMaps.Util.makeInitOnceGetter = function ( object, funcName, initFunc )
ALKMaps.Util.modifyAlphaImageDiv = function ( div, id, px, sz, imgURL, position, border, sizing, opacity )
ALKMaps.Util.createAlphaImageDiv = function ( id, px, sz, imgURL, position, border, sizing, opacity, delayDisplay )
Creates a new hashtable and copies over all the keys from the passed-in object, but storing them under an uppercased version of the key at which they were stored.
ALKMaps.Util.upperCaseObject = function ( object )
Takes an object and copies any properties that don’t exist from another properties, by analogy with ALKMaps.Util.extend() from Prototype.js.
ALKMaps.Util.applyDefaults = function ( to, from )
ALKMaps.Util.getParameterString = function ( params )
Appends a parameter string to a url.
ALKMaps.Util.urlAppend = function ( url, paramStr )
{String} The fully formatted location string for a specified image
ALKMaps.Util.getImageLocation = function ( image )
Execute functions until one of them doesn’t throw an error.
ALKMaps.Util.Try = function ()
ALKMaps.Util.getXmlNodeValue = function ( node )
ALKMaps.Util.mouseLeft = function ( evt, div )
Convenience method to cast an object to a Number, rounded to the desired floating point precision.
ALKMaps.Util.toFloat = function ( number, precision )
ALKMaps.Util.rad = function ( x )
ALKMaps.Util.deg = function ( x )
Given two objects representing points with geographic coordinates, this calculates the distance between those points on the surface of an ellipsoid.
ALKMaps.Util.distVincenty = function ( p1, p2 )
Calculate destination point given start point lat/long (numeric degrees), bearing (numeric degrees) & distance (in m).
ALKMaps.Util.destinationVincenty = function ( lonlat, brng, dist )
Parse the parameters from a URL or from the current page itself into a JavaScript Object.
ALKMaps.Util.getParameters = function ( url )
ALKMaps.Util.normalizeScale = function ( scale )
ALKMaps.Util.getResolutionFromScale = function ( scale, units )
ALKMaps.Util.getScaleFromResolution = function ( resolution, units )
Calculates the position of an element on the page
ALKMaps.Util.pagePosition = function ( forElement )
Test two URLs for equivalence.
ALKMaps.Util.isEquivalentUrl = function ( url1, url2, options )
ALKMaps.Util.createUrlObject = function ( url, options )
Takes a url and removes everything after the ?
ALKMaps.Util.removeTail = function ( url )
{String} A string which specifies which is the current browser in which we are running.
ALKMaps.Util.getBrowserName = function ()
Renders the contentHTML offscreen to determine actual dimensions for popup sizing.
ALKMaps.Util.getRenderedDimensions = function ( contentHTML, size, options )
This function has been modified by the ALKMaps from the original version, written by Matthew Eernisse and released under the Apache 2 license here:
ALKMaps.Util.getScrollbarWidth = function ()
This function will return latitude or longitude value formatted as
ALKMaps.Util.getFormattedLonLat = function ( coordinate, axis, dmsOption )
Deprecated.
ALKMaps.Util.buildTableCell = function ( tag, content, colspan, cssClass )
Deprecated.
ALKMaps.Util.buildTableOrRow = function ( tag, trs, cssClass, id )
Convert string to string array.
ALKMaps.Util.convertToStringArray = function ( drawers )
Determines the correct region number for the corresponding enumeration string, and defaults to NA(4).
ALKMaps.Util.getRegion = function ( region )
Determines if the value of the dataset passed in is valid, and if not defaults to Current.
ALKMaps.Util.getDataSet = function ( dataset )
Returns the dataset corresponding to the given region.
ALKMaps.Util.getDatasetFromRegion = function ( region )
Convert RGB value to HEX
ALKMaps.Util.rgbToHex = function ( r, g, b )
Converts hex to rgb.
ALKMaps.Util.hexToRgb = function ( hex )
This method can be used to build HTML lable element.
ALKMaps.Util.buildLabelElement = function ( input )
Build HTML Select element with options.
ALKMaps.Util.buildSelectElement = function ( input )
Gets the source path from the HTML script tag of the given file.
ALKMaps.Util.getScriptSrc = function ( fileName )
Gets the current year.
ALKMaps.Util.getYear = function ()
Enables the default right-click context menu of the provided div;
ALKMaps.Util.enableContextMenu = function ( div )
Disables the default right-click context menu of the provided div;
ALKMaps.Util.disableContextMenu = function ( div )