From f2786324f70480467326aebaa3f8b7ad0a165ca2 Mon Sep 17 00:00:00 2001 From: Nate Irwin Date: Tue, 27 Aug 2013 22:48:38 -0600 Subject: [PATCH] Add presets, a few new layer handlers, and update docs --- API.md | 192 ++++++++++++++++++---- Makefile | 12 +- README.md | 23 ++- UPGRADING.md | 5 + examples/baselayer-presets-bootstrap.html | 57 +++++++ examples/basic-api.html | 1 + examples/basic-bootstrap.html | 3 +- leaflet.js | 2 +- npmap.js | 11 +- package.json | 7 +- src/bootstrap.js | 141 +++++++++++----- src/layer/arcgisserver.js | 76 +++++++++ src/layer/cartodb.js | 18 -- src/layer/geojson.js | 22 --- src/layer/mapbox.js | 89 +++++----- src/layer/tiled.js | 20 +++ src/map/map.js | 14 +- src/presets/baseLayers.json | 139 ++++++++++++++++ src/request.js | 21 --- src/url.js | 49 ------ src/util.js | 115 ++++++++++--- 21 files changed, 749 insertions(+), 268 deletions(-) create mode 100644 UPGRADING.md create mode 100644 examples/baselayer-presets-bootstrap.html create mode 100644 src/layer/arcgisserver.js delete mode 100644 src/layer/cartodb.js delete mode 100644 src/layer/geojson.js create mode 100644 src/layer/tiled.js create mode 100644 src/presets/baseLayers.json delete mode 100644 src/request.js delete mode 100644 src/url.js diff --git a/API.md b/API.md index a738543..1575ab2 100644 --- a/API.md +++ b/API.md @@ -1,40 +1,176 @@ # NPMap.js API Docs -## baseLayer - -- Presets: - - bing - - esri - - google - - mapbox - - nps - - stamen - -## layer - -- arcgisserver -- cartodb -- geojson -- kml -- mapbox (aliased from `tilestream` to preserve backwards-compatibility) - - Required: - - `id` OR `tileJson` - - `type` (Required if using `npmap-bootstrap.js`) - - Optional: - - `opacity` (Optional) - - `retinaVersion` (Optional) - -## module +## Map + +### L.npmap.map(config: object) + +Create and configure a map. + +*Arguments:* + +The first, and only, argument is required, and must a map config object with the following properties: + +- (Required) `div` (Object or String): Either an HTML element or the id of an HTML element to render the map into. +- + +You can also (optionally) provide it with any of the options supported by [`L.Map`](http://leafletjs.com/reference.html#map-options). + +*Example:* + + var map = L.npmap.map('map'); + +## Layers + +### L.npmap.layer.arcgisserver(config: object) + +Add a layer from an ArcGis Server map or feature service, including services hosted on ArcGIS Online, to your map with `L.npmap.layer.arcgisserver()`. + +*Arguments:* + +The first, and only, argument is required, and must be a layer config object with the following properties: + +- (Required) `url` (Object): A templated URL string for the ArcGIS Server service you want to create a layer. +- (Optional) `dynamicAttribution` (String): The URL of a [dynamic attribution](http://blogs.esri.com/esri/arcgis/2012/08/15/dynamic-attribution-is-here/) endpoint for the service. +- (Optional) `icon` (String) +- (Optional) `name` (String) + +You can also (optionally) provide it with any of the options supported by [`L.TileLayer`](http://leafletjs.com/reference.html#tilelayer). + +*Example:* + + var layer = L.npmap.layer.arcgisserver({ + url: 'http://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}/' + }); + +### L.npmap.layer.mapbox(config: object) + +Add a layer from MapBox hosting, with interactivity, to your map with `L.npmap.layer.mapbox()`. + +*Arguments:* + +The first, and only, argument is required, and must be a layer config object with the following properties: + +- (Depends) `id` (String): The id ('account.id') of the MapBox map or tileset you want to add to the map. Required if `tileJson` is not provided. +- (Depends) `tileJson` (Object): A tileJson object for the MapBox map or tileset you want to add to the map. Required if `id` is not provided. +- (Optional) `format` (String): One of the following: 'jpg70', 'jpg80', 'jpg90', 'png', 'png32', 'png64', 'png128', or 'png256'. If not provided, defaults to 'png'. +- (Optional) `icon` (String) +- (Optional) `name` (String) +- (Optional) `retinaVersion` (String): The id ('account.id') of the MapBox map or tileset designed specifically for retina devices. + +You can also (optionally) provide it with any of the options supported by [`L.TileLayer`](http://leafletjs.com/reference.html#tilelayer). + +*Example:* + + var layer = L.npmap.layer.mapbox({ + id: 'examples.map-20v6611k' + }); + + + + + + + + + + + + + + +### Layer + +#### Modules + +- L.TileLayer + - arcgisserver + - Required: + - `type` (Only required if using `bootstrap.js`) + - Optional: + - `attribution` + - cartodb + - Required: + - `type` (Only required if using `bootstrap.js`) + - Optional: + - `attribution` + - mapbox (aliased from `tilestream` to preserve backwards-compatibility) + - Required: + - `id` OR `tileJson` + - `type` (Only required if using `bootstrap.js`) + - Optional: + - `attribution` + - `composited` + - `opacity` + - `retinaVersion` + - tiled + - wms +- L.GeoJSON + - csv + - geojson + - Required: + - `type` (Only required if using `bootstrap.js`) + - Optional: + - `attribution` + - gpx + - json + - kml + - Required: + - `type` (Only required if using `bootstrap.js`) + - Optional: + - `attribution` + - shapefile + - xml + +#### Concepts + +- baseLayer vs. layer + - `icon` + - Presets: + - `baseLayers.json` +- Raster + - UTFGrid +- Vector + - Clustering + - Symbology + - Defaults + - NPS Maki + +### Module + +#### Modules - edit +- itinerary - route -## tool +#### Concepts +- Accessibility +- Usability and look-and-feel + +### Tool + +#### Modules + +- fullscreen - geocode +- hash +- infobox - navigate +- overviewmap +- print +- scalebar +- share + +#### Concepts + +- Accessibility +- Usability and look-and-feel + +### Util ## Notes -- If you are using `npmap-bootstrap.js`, a `leaflet` property will be added to every baseLayer, layer, map, module, or tool config object. You can use this property to interact directly with Leaflet's classes. -- `npmap-bootstrap.js` supports adding multiple maps to a page. Just make the `NPMap.config` property an array, and you are good to go. \ No newline at end of file +- If you are using `bootstrap.js`, a `L` property will be added to every layer, map, module, or tool config object. You can use this property to interact directly with the `NPMap.js` objects. +- `NPMap.js` extends Leaflet's classes and only provides the interfaces outlined above. You can use the larger [Leaflet API](http://leafletjs.com/reference.html) as well. +- Unlike previous versions of the NPMap library, `bootstrap.js` now supports adding multiple maps to a page. Just make the `NPMap.config` property an array, and you are good to go. \ No newline at end of file diff --git a/Makefile b/Makefile index e01f1bf..707f1b3 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,8 @@ BROWSERIFY = node_modules/.bin/browserify all: \ dist/images \ - dist/npmap-bootstrap.js \ + dist/presets \ + dist/bootstrap.js \ dist/npmap-standalone.css \ dist/npmap.css \ dist/npmap.ie.css \ @@ -11,7 +12,7 @@ all: \ dist/npmap-standalone.min.js node_modules/.install: package.json - npm install && npm install leaflet-hash && touch node_modules/.install + npm install && touch node_modules/.install npmap%js: @cat $(filter %.js,$^) > $@ @@ -22,8 +23,11 @@ dist: dist/images: cp -r node_modules/Leaflet/dist/images dist/images -dist/npmap-bootstrap.js: src/bootstrap.js - cp src/bootstrap.js dist/npmap-bootstrap.js +dist/presets: + cp -r src/presets dist/presets + +dist/bootstrap.js: src/bootstrap.js + cp src/bootstrap.js dist/bootstrap.js dist/npmap-standalone.css: theme/nps.css cp theme/nps.css > dist/npmap-standalone.css diff --git a/README.md b/README.md index 77b6732..4ad9c51 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,24 @@ # NPMap.js -A JavaScript mapping library for the National Park Service, built as a Leaflet plugin. Includes functionality and a look-and-feel that fits into the strong graphic tradition of the National Park Service. +A JavaScript mapping library for the National Park Service, built as a Leaflet plugin. Includes functionality and a look-and-feel that fits into the graphic tradition of the National Park Service. -This is pre-alpha software - not production ready! NPMap.js will eventually take the place of the [NPMap JavaScript library](https://github.com/nationalparkservice/npmap). +This is pre-alpha software that is nowhere close to being production ready! NPMap.js will eventually take the place of the [NPMap JavaScript library](https://github.com/nationalparkservice/npmap), but it isn't ready for that yet. ## Building +The build process uses [node.js](http://nodejs.org/). After installing node.js: + git clone https://github.com/nationalparkservice/npmap.git + cd npmap npm install make -This project uses [browserify](https://github.com/substack/node-browserify) to combine dependencies and installs a local copy when you run `npm install`. `make` will build NPMap.js in `dist/`. +The [browserify](https://github.com/substack/node-browserify) package is used to combine dependencies. It, along with other required packages, are installed locally when you run `npm install`. Running `make` will build NPMap.js, using [UglifyJS](https://github.com/mishoo/UglifyJS) to create minified versions, in https://github.com/mishoo/UglifyJS. + +## Hosted Version + +NPMap.js is also hosted on the National Park Service's content delivery network. Feel free to load the library directly from there. You can access the hosted versions at http://www.nps.gov/npmap/dev/tools/npmap.js/x.y.z/. You should replace "x.y.z" with the number of the version you want to access and append the name of the file you are loading to the end of the URL: `bootstrap.js`, `npmap.min.js`, `npmap.css`, or `npmap.ie.css`. ## Credits @@ -22,15 +29,15 @@ Heavily inspired (cough cough) by [MapBox.js](https://github.com/mapbox/mapbox.j ## Docs -None available yet, but will eventually live in `API.md`. +Take a look at [API.md](https://github.com/nationalparkservice/npmap.js/blob/master/API.md). ## Examples -Take a look in the `examples` directory. Again, not much there at the moment, but lots of examples coming soon. +Take a look in the `examples` directory. Again, not much there at the moment, but more examples coming soon. -Each example that is there has two versions: An "api" version and a "bootstrap" version. This reflects the different ways NPMap.js can be used: +Each example has two versions: A `-api` version and a `-bootstrap` version. This reflects the two different ways NPMap.js can be used: -1. If you have control of the web page you are embedding the map into and want to build your map with a traditional API, you should manually include `npmap.js`, along with the required CSS files, in your HTML and then build the map using the API. -2. If you want a simplified way of building your map and/or don't have control over the web page you are embedding your map into, you should create a config object and then load `npmap-bootstrap.js` into your web page dynamically. The bootstrap script will then take care of loading all the JavaScript and CSS dependencies for you. +1. Like most "traditional" mapping APIs. This works well if you are familiar with JavaScript *and* have access to include JavaScript and CSS files in the web page your map is going to be included in. These examples use `npmap.js` directly, and utilize the [API](https://github.com/nationalparkservice/npmap.js/blob/master/API.md) to build the map. +2. Indirectly, through the use of `bootstrap.js`. This allows you to configure your map using the `NPMap.config` property. This is the better approach for non-technical users and/or those who don't have access to the web page the map is going to be included in. [![Build Status](https://travis-ci.org/nationalparkservice/npmap.js.png)](https://travis-ci.org/nationalparkservice/npmap.js) \ No newline at end of file diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 0000000..85dcbf2 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,5 @@ +Follow these steps to upgrade from a legacy version of the NPMap library to NPMap.js: + +- To maintain consistency with Leaflet, the `zoomRange` property is now broken up into two separate properties: `minZoom` and `maxZoom`. These properties are available for the `L.npmap.map` and `L.npmap.layer` classes. +- Layer handler types are now all lowercase. +- The `TileStream` layer handler has been renamed to `mapbox`. \ No newline at end of file diff --git a/examples/baselayer-presets-bootstrap.html b/examples/baselayer-presets-bootstrap.html new file mode 100644 index 0000000..db953d7 --- /dev/null +++ b/examples/baselayer-presets-bootstrap.html @@ -0,0 +1,57 @@ + + + + + + 'baseLayer' Presets (Bootstrap) | Examples | NPMap.js + + + +
+ + + \ No newline at end of file diff --git a/examples/basic-api.html b/examples/basic-api.html index 08c0e55..3995b52 100644 --- a/examples/basic-api.html +++ b/examples/basic-api.html @@ -3,6 +3,7 @@ + Basic (API) | Examples | NPMap.js