Skip to content

Latest commit

 

History

History
1201 lines (1198 loc) · 47 KB

API.md

File metadata and controls

1201 lines (1198 loc) · 47 KB
Raw

Notes

  1. NPMap is designed to be as simple and targeted as possible. It is comprised of simple JavaScript modules, and it does not support everything that full-featured mapping libraries support. That said, it does support even the most advanced cases by making the underlying classes and objects that are exposed via whichever base API your map uses available.
  2. Module properties and methods that start with an underscore (i.e. _zoomToLatLngs) are considered private and may change at any time. Do not use them.

Specifications

By design, NPMap doesn't create or utilize traditional JavaScript classes. It, rather, uses simple objects and utility methods specific to whichever base API is being used by the map to convert objects to and from native base API objects.

These specifications document the structure of objects you'll see when interacting directly with NPMap's modules. If you are interacting with objects that aren't proxied through one of the NPMap modules, you'll need to take a look at the API docs for the base API itself to see what the expected format is. Here are links to the API docs for each base API that NPMap supports:

Bounds

NPMap always expects and returns coordinates in Decimal Degrees.

Property Type
e {Number}
n {Number}
s {Number}
w {Number}

LatLng

NPMap always expects and returns coordinates in Decimal Degrees.

Property Type
lat {Number}
lng {Number}

Layer

In NPMap, a layer object is really just a configuration object for either a baseLayer or layer that NPMap appends properties to and uses to manage the layer within the context of the map.

The properties that are defined on an individual layer object depend on the type of layer handler that the layer utilizes. There are, however, some properties that are used fairly consistently across the different types of layers that NPMap supports.

For "vector" layers (GeoJson, Json, Kml, NativeVectors, and Xml), the following properties are added to the layer config object:

Property Type Description
identify {Object}

An object with 'content', 'title', and optionally 'footer' and 'cluster' configs that are used by NPMap to configure the InfoBox display for this layer. If these configs aren't specified in the initial layer config object, NPMap will use the default display parameters to display information for an identify operation.
shapes {Array}

An array of the shapes that have been added to the map for this layer.
styleNpmap {Object}

The set of marker, line, and polygon styles that will be used to style the shapes on the map. If the style config isn't specified in the layer config object, NPMap will utilize a set of default styles.

For "raster" or "tiled" layers (ArcGisServerRest, CartoDb, GoogleFusion, Tiled, TileStream, and Zoomify), the following properties are added to the layer config object:

Property Type Description
api {Object}

The "native" layer object.
identify {Object}

An object with 'content', 'title' and optionally 'footer' and 'cluster' configs that are used by NPMap to configure the InfoBox display for this layer. If these configs aren't specified in the initial layer config object, NPMap will use a set of default display parameters for click (identify) operations.

Point

Property Type
x {Number}
y {Number}

Shape

NPMap stores important metadata as a property on all the lines, markers, and polygons that it creates. It uses these metadata to make information about the shapes available via click and mouseover operations and various modules and tools.

All of the metadata that NPMap stores with a shape is contained in the npmap object, so if you have a reference to a shape, you can access the NPMap metadata via the shape.npmap property. This object contains the following properties:

Property Type
data {Object}
layerName {String}
layerType {String}
type {String}

NPMap.config

The NPMap.config object is used to set configuration properties that NPMap uses to build the map. You must create this object before loading the NPMap library into your web page.

Example

var NPMap = NPMap || {};

NPMap.config = {
center: {
lat: 36,
lng: -96
},
div: 'map',
zoom: 4
};


(function() {
var s = document.createElement('script');
s.src = 'http://www.nps.gov/npmap/1.0.0/bootstrap.js';
document.body.appendChild(s);
})();

Options

The following properties can be set in the NPMap.config object. Note that the only required property is NPMap.config.div.

Option Type Default Description
api {String} 'bing'

The base API to use for the web map.
baseLayers {Array} null

The baseLayers to add to the map. Only one baseLayer can be visible at a time. NPMap will iterate through the baseLayers {Array} and will add the first layer whose visibility property is either undefined or true to the map. The visible baseLayer always lives at the bottom of the map, or, in other words, at zIndex of 0.
center {Object} 
{
  lat: 36,
  lng: -96
}

The latitude/longitude to initialize the map with. If this is null or missing either the lat or lng property, NPMap will default to the center of the continental United States.
credentials {String} 'nps'

This property tells NPMap whether or not you are an NPS employee, contractor, or partner. If you are an NPS employee, you do not need to specify this property. If you are not and you are using either the bing or google base API, you should set this property to either your Bing Maps API key or your Google Maps channel and client URL parameters. See the credentials section of the Bing and Google base API docs for more information.
div {String} null

This property is required. The id of the HTML div element to render the map into. NPMap will automatically size the map to take up 100% of the height and width of the div. If/when this div is resized, NPMap will automatically resize the map and reposition/resize any toolbars or modules that have been added to the map.
events {Object} null

An object with event functions that NPMap should call before, during, and/or after the map creation. The current valid events are preinit and init. The preinit event occurs after the non-mapping dependencies are loaded, but before the mapping library is loaded and the web map is created. The init event occurs after all of the dependencies, including the mapping library, have been loaded and NPMap has created the map. Each of these functions must accept a callback function as a parameter and call the callback function (callback();).
hideLogo {Boolean} false

Tells NPMap to hide the NPMap logo. If possible, help us spread the word by leaving the logo on the map!
infobox {Object} null

The global infobox configuration. You can use this object to customize how the InfoBox looks and behaves.
layers {Array} null

The layers to add to the map.
modules {Array} null

The modules to add to the map.
server {String} 'http://www.nps.gov/npmap/1.0.0'

Allows you to load NPMap from an alternative location. This is only necessary if you're developing or serving NPMap from your own server.
tools {Object} null

Holds configuration information for NPMap's tools.
zoom {Number} 4

An integer zoom level to initialize the map with.
zoomRange {Object} 
{
  min: 0,
  max: 19
}

The minimum and maximum zoom levels to restrict the map to.

NPMap.Map

The map is the core component of NPMap. The NPMap.Map module facilitates creating and interacting with a map built with one of the supported base APIs. To create a map, you will need to create a NPMap.config object and then load the NPMap library into your web page.

Dependencies

Methods

Method Return Value Description
addControl(el:HtmlElement, callback:Function, stopPropagation:Boolean) null

Adds an HTML element to the map div.
addShape(shape) null

Adds a shape (marker, line, or polygon) to the map.
addShapes(shapes) null

Adds an array of shapes (markers, lines, and/or polygons) to the map.
boundsFromApi(bounds) {Object}

Converts an API bounds to an NPMap bounds.
boundsGetCenter(bounds) {Object}

Gets the center lat/lng of a bounds object.
boundsToApi(bounds) {Object}

Converts an NPMap bounds to an API bounds.
center(latLng) null

Centers the map.
centerAndZoom(latLng, zoom, callback?) null

Centers and zooms the map.
closeModules() null

Closes the modules panel.
createLine(latLngs, options?) {Object}

Creates a line.
createMarker(latLng, options?) {Object}

Creates a marker.
createPolygon(latLngs, options?) {Object}

Creates a polygon.
getBounds() {Object}

Gets the map bounds.
getCenter() {Object}

Gets the center of the map.
getLineLatLngs(line) {Array}

Gets the lat/lngs of a line.
getMapElement() {Object}

Gets the map element.
getMarkerLatLng(marker) {Object}

Gets the lat/lng of a marker.
getMaxZoom() {Number}

Gets the maximum zoom level for the map.
getMinZoom() {Number}

Gets the minimum zoom level for the map.
getPolygonLatLngs(polygon) {Array}

Gets the lat/lngs of a polygon.
getZoom() {Number}

Gets the zoom level of the map.
hasClusteredLayer() {Boolean}

Checks to see if a clustered layer has been added to the map.
hasTiledLayer() {Boolean}

Checks to see if a tiled layer has been added to the map.
hideProgressBar() null

Hides the progress bar.
hideShape(shape) null

Hides a shape.
hideTip(shape) null

Hides the tip.
isLatLngWithinMapBounds(latLng) {Boolean}

Tests to see if a latLng is within the map's current bounds.
latLngsAreEqual(latLng1, latLng2) {Boolean}

Tests the equivalency of two lat/lng objects.
latLngFromApi(latLng) {Object}

Converts a base API lat/lng object to an NPMap lat/lng object.
latLngToApi(latLng) {Object}

Converts an NPMap lat/lng object to a base API latLng object.
latLngToPixel(latLng) {Object}

Converts an NPMap lat/lng object to an NPMap pixel object.
metersToZoomLevel(meters) {Number}

Turns meters into a zoom level. This function is not precise, as it is impossible to get precise meter scale values for the entire earth reprojected to web mercator.
notify(message, title?, type?, interval?) null

Shows a notification.
openModule(el) null

Opens the UI for a module.
panByPixels(pixel, callback?) null

Pans the map horizontally and/or vertically based on the pixel object passed in.
panInDirection(direction) null

Pans the map in a direction by a quarter of the current map viewport.
pixelFromApi(pixel) {Object}

Converts a base API pixel object to its NPMap equivalent.
pixelToApi(pixel) {Object}

Converts an NPMap pixel object to its base API equivalent.
pixelToLatLng(pixel) {Object}

Converts an NPMap pixel object to an NPMap lat/lng object.
removeShape(shape) null

Removes a shape from the map.
setBounds(bounds) null

Sets the map bounds.
setCursor(cursor) null

Sets the map cursor.
setInitialCenter(center) null

Sets the initial center of the map. This initial center is stored with the map, and is used by the setInitialExtent method, among other things.
setInitialZoom(zoom) null

Sets the initial zoom of the map. This initial zoom is stored with the map, and is used by the setInitialExtent method, among other things.
setMarkerOptions(marker, options) null

Sets a marker's options.
setNotifyTarget(el) null

Sets the notify target to an HTML element other than the map div. This can only be called after NPMap has been initialized.
setZoomRestrictions(restrictions) null

Sets min and/or max zoom restrictions on the map.
showProgressBar(value) null

Shows the progress bar.
showShape(shape) null

Shows a shape.
showTip(content, position) null

Shows the tip.
toBounds(bounds) null

Zooms the map to a bounding box.
toggleFullScreen() null

Toggles fullscreen mode on or off.
toInitialExtent() null

Zooms and/or pans the map to its initial extent.
toLatLngs(latLngs) null

Zooms the map to the extent of an array of lat/lng objects.
toShapes(shapes) null

Zooms the map to the extent of an array of shapes (markers, lines, and polygons).
updateProgressBar(value) null

Updates the progress bar value.
zoom(zoom) null

Zooms the map to a zoom level.
zoomIn() null

Zooms the map in by one zoom level.
zoomOut() null

Zooms the map out by one zoom level.

Properties

NPMap.Map does not expose any public properties.

Events

The NPMap.Map module exposes both mouse and map events. You can subscribe to and unsubscribe from these events using the NPMap.Event module.

You can see these events in action on the map events example page.

Mouse Events

Once you subscribe to one of these events, your handler will receive the {MouseEvent} as a parameter when the event is fired.

Name Argument Description
click {MouseEvent}

This event is fired whenever the map is single-clicked using the left mouse button.
dblclick {MouseEvent}

This event is fired whenever the map is double-clicked using the left mouse button.
mousedown {MouseEvent}

This event is fired whenever the left mouse button is pushed down, but before it is released.
mousemove {MouseEvent}

This event is fired whenever the mouse is moved over the map. It fires continously.
mouseout {MouseEvent}

This event is fired whenever the mouse is moved off of the map's div element.
mouseover {MouseEvent}

This event is fired whenever the mouse is moved onto the map's div element.
mouseup {MouseEvent}

This event is fired whenever the left mouse button is released after is has been pushed down.
rightclick {MouseEvent}

This event is fired whenever the map is right clicked.
shapeclick {MouseEvent}

This event is fired when a shape object (marker, line, or polygon) is clicked on the map.

Map Events

Name Argument Description
baselayerchanged {Object}

This event is fired whenever the map's base layer is changed.
panend null

This event is fired after the map has been panned.
panstart null

This event is fired when the map starts to pan.
ready null

This event fires once when the map has been loaded and is ready to be interated with programatically.
viewchange null

This event is fired continously while the map's view is changing.
viewchangeend null

This event is fired after the map's view has changed.
viewchangestart null

This event is fired when the map's view starts to change.
zoomend null

This event is fired after the map has been zoomed in or out.
zoomstart null

This event is fired when the map starts to zoom in or out.

Submodules

Base API-specific code lives in one of the submodules that hang off of the NPMap.Map module. Generally speaking, you should not interact directly with these submodules, but if you need to do something programatically that isn't supported by the NPMap.Map module, you may need to.

One property that you may need to access is the underlying map object that has been created using the base API. This property can be accessed at NPMap.Map['Bing'|'Google'|'Leaflet'|'ModestMaps'].map. Once NPMap has initialized the map and loaded all of its tools and modules, you can use this map to access functionality that is provided by the base API but not supported by one of the NPMap modules.

NPMap.InfoBox

Methods

Method Return Value Description
hide() null

Hides the InfoBox.
removeAction(el) null

Removes an action HTML element (<a>) from the InfoBox.
reposition() null

Repositions the npmap-clickdot div then repositions the InfoBox. If the marker or npmap-clickdot is not in the current map bounds, it is hidden.
show(content, title, footer?, actions?, styles?, target?) null

Shows the InfoBox.

Properties

Property Type Description
actions {Array}

An array of action objects associated with the current identify operation. If the InfoBox is hidden, this will be null.
results {Array}

An array of result objects for the current identify operation. If the InfoBox is hidden, this will be null.
latLng {Object}

The current latitude/longitude of the InfoBox. If the InfoBox is hidden, this will be null.
marker {Object}

The current marker, if a marker is present. This is null if the InfoBox is displaying without a marker or if the InfoBox is hidden.
visible {Boolean}

This is true if the InfoBox is currently visible.

Events

The NPMap.InfoBox module exposes a few events that can be utilized. You can subscribe to and unsubscribe from these events using the NPMap.Event module.

Name Argument Description
hide null

This event is fired when the InfoBox is hidden.
show null

This event is fired when the InfoBox is shown.

NPMap.Layer

Methods

Method Return Value Description
add(config, silent?) null

Creates and adds a layer.
getActiveLayerTypes() {Array}

Gets the active layer types for both the baseLayers and layers configs.
getLayerById(id, layers?) {Object}

Gets a layer config object by layer id.
getLayerHandlerMeta(name) {Object}

Get the META information for a layer handler.
getLayerByName(name, layers?) {Object}

Gets a layer config object by layer name.
getName(config) {String}

Gets the layer name.
getType(config) {String}

Gets the layer type.
getVisibleLayers() {String}

Gets the layers that are currently visible.
hide(config, silent?) null

Hides a layer.
iterateThroughAllLayers(func) {Function}

Iterates through all the objects in the NPMap.config.baseLayers and NPMap.config.layers configs.

The function will be passed each of the layer config objects as a parameter.
iterateThroughBaseLayers(func) {Function}

Iterates through all the objects in the NPMap.config.baseLayers config.

The function will be passed each of the layer config objects as a parameter.
iterateThroughLayers(func) {Function}

Iterates through all the objects in the NPMap.config.layers config.

The function will be passed each of the layer config objects as a parameter.
remove(config, silent?) null

Removes a layer.
show(config, silent?) null

Shows a layer.

Properties

NPMap.Layer does not expose any public properties.

Events

The NPMap.Layer module exposes several events that can be utilized to hook custom behaviors up to layers. You can subscribe to and unsubscribe from these events using the NPMap.Event module.

Name Argument Description
added {Object}

This event is fired when a new layer is added to the map.
beforeadd {Object}

This event is fired before a new layer is added to the map.
beforehide {Object}

This event is fired before a layer is hidden.
beforeremove {Object}

This event is fired before a layer is removed from the map.
beforeshow {Object}

This event is fired before a layer is shown.
hidden {Object}

This event is fired when a layer is hidden.
ready null

This event fires once when all the layers the map has been initialized with have been added to the map.
removed {Object}

This event is fired when a layer is removed from the map.
shown {Object}

This event is fired when a layer is shown.

Submodules

Code that is specific to the individual layer handlers hang off of the NPMap.Layer module.

NPMap.Event

Example


// Add an event.
var eventId = NPMap.Event.add('NPMap.Map', 'click', function(e) {
  console.log(e); // The click event.
});

// Remove the event.
NPMap.Event.remove(eventId);

Methods

Method Return Value Description
add(obj, event, func, single?) {Number}

Adds an event.
get(obj?) {Number}

Gets all the events or, optionally, just the events that have been added to a module.
remove(id) null

Removes an event.
trigger(obj, event, e?) null

Triggers an event.

Properties

NPMap.Event does not expose any public properties.

Events

NPMap.Event does not trigger any events.

NPMap.Util

The NPMap.Util module contains helper methods that make certain tasks easier. NPMap also loads and utilizes the Underscore library, so you can utilize any of the methods it exposes in addition to the NPMap.Util methods.

Methods

Method Return Value Description
addClass(el, cls) null

Adds a CSS class to an element.
bindEventToElement(el, name, handler) null

Adds a CSS class to an element.
convertOpacity(opacity) {Number}

Converts a 0-255 opacity to 0-1.0.
doesPropertyExist(obj, prop) {Boolean}

Given an object, does a property exist?
eventCancelMouseWheel(e) null

Cancels a mousewheel event.
eventCancelPropagation(e) null

Cross-browser cancel event propagation.
getElementsByClass(cls) {Array}

Gets elements by class name.
getFirstPropertyOfObject(obj) {Array}|{Boolean}|{Function}|{Object}

Gets the first property of an object.
getMousePositionPage() {Object}

Gets the mouse position, in pixels and relative to the page, for a MouseEvent object.
getNextElement(el) {Object}

Gets the next sibling element.
getOffset(el) {Object}

Gets the offset, in pixels, of an element.
getOuterDimensions(el) {Object}

Gets the outer dimensions, in pixels, of an HTML element.
getScrollBarWidth() {Number}

Gets the width of the browser's vertical scrollbar.
getScrollPosition() {Object}

Gets the current scroll position, in pixels, of the browser window.
getWindowDimensions() {Object}

Gets the current window dimensions, in pixels.
hasClass(el, cls) {Boolean}

Checks to see if an HTML element has a CSS class.
hexToRgb(hex) {String}

Converts a HEX color to RGB.
injectCss(locations, callback? null

Injects a CSS stylesheet or multiple CSS stylesheets into the page.
isBetween(start, end, test {Boolean}

Returns true if the test number falls between the start and end numbers.
isInt(n) {Boolean}

Returns true if the number passed in is an integer.
isRightClick(e) {Boolean}

Detects if a MouseEvent is a right-click event.
iterateThroughChildNodes(el, func) null

Iterates through all of the child nodes of an element.
monitorResize(el, handler) null

Monitors an HTML element and calls the handler when its size changes.
removeClass(el, cls) null

Removes a CSS class from an HTML element.
safeLoad(module, callback) null

Checks to make sure a module has been loaded before calling callback function. This function assumes that the module resides in the NPMap namespace.
stopAllPropagation(el) null

Stops the propagation of all events on an HTML element.
stripHtmlFromString(html) {String}

Strips all HTML from a string.
trimString(string) {String}

Trims whitespace from the beginning and end of a string.

Properties

NPMap.Util does not expose any public properties.

Events

NPMap.Util does not trigger any events.

Submodules

A few utility modules hang off of the NPMap.Util module:

  • NPMap.Util.Json
    • NPMap.Util.Json.GeoJson
  • NPMap.Util.Xml
    • NPMap.Util.Xml.Kml