• Crater Lake National Park

    NPMap

    Web maps for the National Park Service

The NPMap 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 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.

NPMap 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, Google, Leaflet, and Modest Maps, and makes it easy to build a map without understanding the nuances of these underlying APIs. NPMap 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>

NPMap 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. NPMap 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 NPMap 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 with NPMap.
  2. Flexibility - NPMap 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 NPMap, no matter how custom, is laid out in the same way. This means that anyone who understands the scaffolding established by NPMap can look at the code for your map and understand what is going on. This helps ensure long-term maintainability for your map.
  4. Embeddability - Maps built with NPMap are designed to be embedded into existing web pages. You don’t have to have complete control of a web page to embed an NPMap map in it; NPMap loads all of its CSS, HTML, and JavaScript requirements on its own.
  5. Look-and-feel - All the components that are built into NPMap – 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 NPMap, you are helping the NPS present its spatial information in a consistent way.
  6. Accessibility and usability - All NPMap 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 NPMap’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 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 library. 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 are added to the library.

Versioning

The NPMap 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 NPMap 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 at 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 on www.nps.gov/npmap, 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 NPMap 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 NPMap library. 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 dependencies are not shown on this chart.

Dependencies

As you can see in the chart above, NPMap itself depends on a number of open source JavaScript libraries. These dependencies are automatically loaded by the library, 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, NPMap does its best to detect and use the preloaded library. This ensures there are no 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: