Crater Lake National Park

NPMap

Digital maps for the National Park Service

JavaScript Library

Not a developer? This section of the documentation may not be for you. Perhaps you'd like to take a look at the tutorials?

The NPMap Javascript library is designed to make it easy for NPS employees, partners, and volunteers to build and deploy maps into their web pages - including the nps.gov content management system.

The library wraps a simple and targeted API and a look-and-feel that fits into the graphic identify of the National Park Service around commercial and open source web mapping APIs, like Bing, Leaflet, and Modest Maps, making it easy to build a map without understanding the nuances of these underlying APIs. It allows you to build your map by creating a configuration script that looks like this (this example is a fully-working HTML page, but the pertinent lines (9-14) are highlighted):


<!doctype html>
<html>
  <head>
  </head>
  <body>
    <div id="map" style="height:500px;position:absolute;width:500px;>
    </div>
    <script>
      var NPMap = {
        config: {
          api: 'leaflet',
          div: 'map'
        }
      };

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

The library uses the NPMap.config object defined on your web page to configure your map and then takes care of the heavy-lifting behind the scenes. This means you do not have to have complete control over a web page to embed a map into it. It is also flexible enough to support the entire range of use cases - from simple maps like the one shown above to desktop-class maps.

Advantages

There are many advantages to using the NPMap JavaScript library that you don't get when building "one-off" maps directly against a commercial or open source web mapping API:

  1. Simplicity - You don't need to know how to write code or understand the intricacies and nuances of different web mapping APIs to build a map.
  2. Flexibility - The library makes it easy to switch between different web mapping APIs. This is especially useful for an agency like the National Park Service, where license agreements are in a constant state of flux and requirements range from simple to extremely advanced.
  3. Maintanability - The code structure for all maps built with the library, no matter how custom, is laid out in the same way. This means that anyone who understands the scaffolding established by the library can look at the code for your map and understand what is going on. This helps ensure long-term maintainability for your map - no matter how complex.
  4. Embeddability - Maps built with the library are designed to be embedded into existing web pages. You don't have to have complete control of a web page to embed a map into it; the library loads all of its CSS, HTML, and JavaScript requirements on its own.
  5. Look-and-feel - All the components that are built into the library -- including navigation tools, user interface elements, and modules -- were custom-designed to fit into the graphic identity of the National Park Service. In addition, if you build your maps with the library, you are helping the NPS present its spatial information in a consistent way.
  6. Accessibility and usability - All of the library's components have undergone extensive accessibility and usability testing. (There is still a lot of work to do in regards to accessibility, but we are improving the library's accessibility with each release.)
  7. Licensing - The NPMap team administers enterprise license agreements with a variety of commercial organizations, and access to the services that are covered by these agreements is built into the library.

Architecture

The NPMap JavaScript library was built, from the ground up, to make it as easy as possible for developers to build on and extend. All components of the library are written in the JavaScript modular pattern, so the architecture should make sense even if you don't have previous experience working with the codebase. This also means there are no hard-coded dependencies, so you don't have to worry about unraveling tangled bits of interdependent code when working in the code base.

Tests

You can view the beginnings of a test framework for the library on the tests page. The tests are a work in progress. They are updated as new features and enhancements are added.

Versioning

The NPMap JavaScript library is versioned to ensure that maps built with older versions continue to work even as the library grows. That said, there are occasional releases that break existing functionality. Like many modern code projects, we use semantic versioning to publish version changes. This means that given a version format of X.Y.Z (Major.Minor.Patch):

  • versions that contain changes that break the library's API will be incremented up at the "Major" level (1.0.0 to 2.0.0);
  • versions that contain backwards-compatible API additions/changes increment the "Minor" level (1.0.0 to 1.1.0); and
  • versions that contain bug fixes that do not affect the API will be incremented up at the "Patch" level (1.0.0 to 1.0.1).

You are welcome to link directly to any of the versions hosted on this website, www.nps.gov/npmap. These libraries are served from the National Park Service's content delivery network, which ensures high performance and availability. For a list of all releases, along with a direct link to the bootstrap.js files hosted on our content delivery network, see the releases page.

We will always leave at least three versions of the JavaScript library up and available on the conetnt delivery network, including the current development version of the library, the current production version of the library, and one legacy version. In addition, we will give developers at least three month's notice before deprecating any version and taking it down from our content delivery network. You should join the NPMap mailing list or subscribe to our blog's feed to ensure you receive notification of new releases and deprecations.

Technical details

Loading

All script/dependency loading in the NPMap JavaScript library is done by the RequireJS library. This library loads required NPMap modules and, in conjunction with UglifyJS, helps combine and minify JavaScript for use in production web maps.

Here is a chart that shows the load order of the library's modules. The dotted lines represent asynchronous loads. The solid lines represent synchronous loads. Note that there are a few other classes (InfoBox, etc.) that are loaded as dependencies of other modules. These are not shown on this chart.

Dependencies

As you can see in the chart above, the library itself depends on a number of other open source JavaScript libraries. These dependencies are automatically loaded, so you don't have to worry about loading them into the web page yourself. If any of these libraries has already been loaded into your web page, the library's bootstrap.js does its best to detect and use the preloaded library. This ensures there are no (or at worse, minimal) conflicts between scripts.

Utility libraries

These libraries take care of everything from click/touch events to AJAX communication:

Web mapping libraries

Only one of these web mapping libraries is loaded by NPMap, depending on which base API you specify in your NPMap.config object: