Skip to content
This repository has been archived by the owner on Feb 8, 2023. It is now read-only.

Latest commit

 

History

History
executable file
·
1813 lines (1246 loc) · 62 KB

index.md

File metadata and controls

executable file
·
1813 lines (1246 loc) · 62 KB
Raw

map(config: object)

Create and configure a map with baseLayers, overlays, controls, and modules.

Extends: L.Map

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) div (Object or String): Either a reference to an HTML element or the id of an HTML element to render the map into.
  • (Optional) baseLayers (Array): An array of baseLayer configuration objects AND/OR baseLayer preset strings. Defaults to ['outerspatial-landscape'].
  • (Optional) description (String): A description for the map. Used by some templates.
  • (Optional) detectAvailablePopupSpace (Boolean): Defaults to false. If true, OuterSpatial Map Library will detect the height and width available in your map and set the maxHeight and maxWidth properties of the map's popups automatically.
  • (Optional) editControl (Boolean or Object): Defaults to undefined.
  • (Optional) events (Array): An array of event objects to attach to the map. Defaults to undefined.
  • (Optional) fullscreenControl (Boolean or Object): Defaults to undefined.
  • (Optional) geocoderControl (Boolean or Object): Defaults to undefined.
  • (Optional) hashControl (Boolean): Defaults to undefined.
  • (Optional) homeControl (Boolean or Object): Defaults to true.
  • (Optional) hooks (Object): Add init and/or preinit hooks to the map. These must be functions that accept a callback parameter, and execute the callback function. Defaults to undefined.
  • (Optional) infoboxControl (Boolean): Defaults to undefined.
  • (Optional) legendControl (Boolean or Object): Defaults to undefined.
  • (Optional) locateControl (Boolean or Object): Defaults to undefined.
  • (Optional) measureControl (Boolean or Object): Defaults to undefined.
  • (Optional) name (String): A name for the map. Used by some templates.
  • (Optional) overlays (Array): An array of overlay configuration objects. Defaults to undefined.
  • (Optional) overviewControl (Boolean or Object): Defaults to undefined.
  • (Optional) printControl (Boolean or Object): Defaults to undefined.
  • (Optional) scaleControl (Boolean or Object): Defaults to undefined.
  • (Optional) smallzoomControl (Boolean or Object): Defaults to true.
  • (Optional) zoomdisplayControl (Boolean or Object): Defaults to undefined.

You can also (optionally) provide any of the options supported by L.Map.

Returns: a map object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map'
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

Working Examples:

[⬆]

Layers

Layers can be added to a map via the baseLayers and/or overlays configs.

Only one baseLayer can be visible at a time. If multiple baseLayers are specified, the first baseLayer will be visible when the map initializes. baseLayer preset strings are supported in the baseLayers property.

Multiple overlays can be visible at the same time. Overlays will be added to the map in the order they are specified in the overlays property, and will display from bottom-to-top on the map.

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  baseLayers: [
    'bing-aerial'
  ],
  overlays: [{
    table: 'parks',
    type: 'cartodb',
    user: 'nps'
  }]
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.bing().addTo(map);
L.outerspatial.layer.cartodb({
  table: 'parks',
  type: 'cartodb',
  user: 'nps'
}).addTo(map);

You can add events to a layer by adding an events array to the layer config. The array should contain event objects with fn and type properties. These objects can also (optionally) be given a single property if the event should only be fired one time. An example:

var OuterSpatial = {
  div: 'map',
  overlays: [{
    events: [{
      fn: function() {
        console.log('tileloadstart');
      },
      type: 'tileloadstart'
    }],
    table: 'parks',
    type: 'cartodb',
    user: 'nps'
  }]
};

Supported event "types" include all of the Leaflet layer events for a given layer type, as well as the following event types added by OuterSpatial Map Library:

  • error: Fired when a layer error occurs. Passes the error event object to the event function.
  • load: Fired when a layer is loaded. Only available for layers that extend L.GeoJson.
  • ready: Fires when a layer is initialized and ready to interact with programatically.

Working Examples:

[⬆]

arcgisserver(config: object)

Create a layer from an ArcGIS Server tiled or dynamic map service, including map services hosted on ArcGIS Online, and add it to a map.

Note: If you want to bring in an ArcGIS Online feature service, you will need to add it as a GeoJSON layer to OuterSpatial Map Library. You can get GeoJSON in WGS84 out of the feature service by appending ?f=geojson&outSR=4326 to the end of the query URL, e.g.:

http://services1.arcgis.com/fBc8EJBxQRMcHlei/ArcGIS/rest/services/GRSM_RESTROOMS/FeatureServer/0/query?f=geojson&outSR=4326&where=OBJECTID+IS+NOT+NULL

Extends:

  • Dynamic ArcGIS Server layers extend L.Class.
  • Tiled ArcGIS Server layers extend L.TileLayer.

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) tiled (Boolean): Should be true if the service is tiled and false if it is not.
  • (Required) url (String): A URL string ending with MapServer for the service's endpoint.
  • (Optional) attribution (String): An attribution string for the layer. HTML is allowed.
  • (Optional) clickable (Boolean): Should interactivity (click) operations be enabled for this layer? Defaults to true.
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) dynamicAttribution (String): The URL of a dynamic attribution endpoint for the service.
  • (Optional) layers (String): A comma-delimited string of the ArcGIS Server integer layer identifiers to bring into the OuterSpatial Map Library layer.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) popup (String, Object, or Function): Configures the contents of the overlay's popups.

For tiled ArcGIS Server layers, you can also (optionally) provide any of the options supported by L.TileLayer.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    attribution: '<a href="http://www.esri.com" target="_blank">Esri</a>',
    opacity: 0.5,
    tiled: true,
    type: 'arcgisserver',
    url: 'http://services.arcgisonline.com/ArcGIS/rest/services/Demographics/USA_Unemployment_Rate/MapServer'
  }]
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.arcgisserver({
  attribution: '<a href="http://www.esri.com" target="_blank">Esri</a>',
  opacity: 0.5,
  tiled: true,
  url: 'http://services.arcgisonline.com/ArcGIS/rest/services/Demographics/USA_Unemployment_Rate/MapServer'
}).addTo(map);

Working Examples:

[⬆]

bing(config: object)

Create a layer from the Bing Imagery API and add it to a map.

Extends: L.TileLayer

Arguments:

The first, and only, argument is optional. It may be a config object with the following properties:

  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) layer (String): The layer you want to bring in from the Bing Imagery API. Defaults to aerial. Valid options are aerial, aerialwithlabels, and road.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.

You can also (optionally) provide any of the options supported by L.TileLayer.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  baseLayers: [{
    layer: 'aerialwithlabels',
    type: 'bing'
  }]
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.bing({
  layer: 'aerialwithlabels'
}).addTo(map);

Working Examples:

[⬆]

cartodb(config: object)

Create a CartoDB layer and add it to a map.

Extends: L.TileLayer

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) table (String): The name of the CartoDB table.
  • (Required) user (String): The name of the CartoDB user.
  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) cartocss (String): A CartoCSS string to apply to the layer.
  • (Optional) clickable (Boolean): Should interactivity (hover and click) operations be enabled for this layer? Defaults to true.
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) interactivity (String): A comma-delimited string of fields to pull from CartoDB for interactivity (available via mouseover and click operations).
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) popup (String, Object, or Function): Configures the contents of the overlay's popups.
  • (Optional) sql (String): A SQL query to pass to CartoDB.
  • (Optional) styles (Object): Configures the overlay's styles.
  • (Optional) tooltip (String, Object, or Function): Configures the contents of the overlay's tooltips.

You can also (optionally) provide any of the options supported by L.TileLayer.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    table: 'parks',
    type: 'cartodb',
    user: 'nps'
  }]
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.cartodb({
  table: 'parks',
  type: 'cartodb',
  user: 'nps'
}).addTo(map);

Working Examples:

[⬆]

csv(config: object)

Create a CSV layer and add it to a map.

Extends: L.GeoJSON

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) data (String): A string of CSV data. Required if url is not provided.

OR

  • (Required) url (String): A URL to load the CSV data from. Required if data is not provided.

AND

  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) clickable (Boolean): Should interactivity (hover and click) operations be enabled for this layer? Defaults to true.
  • (Optional) cluster (Boolean): Should the layer's markers be clustered?
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) popup (String, Object, or Function): Configures the contents of the overlay's popups.
  • (Optional) styles (Object): Configures the overlay's styles.
  • (Optional) tooltip (String, Object, or Function): Configures the contents of the overlay's tooltips.
  • (Optional) zoomToBounds (Boolean): Should the map zoom to the bounds of this overlay when it is loaded?

You can also (optionally) provide any of the options supported by L.GeoJSON, minus these exceptions:

  1. pointToLayer
  2. style
  3. onEachFeature

These three options are not supported because they are used internally by OuterSpatial Map Library. If provided, they will be overwritten.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    type: 'csv',
    url: 'data/colorado_cities.csv'
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.csv({
  url: 'data/colorado_cities.csv'
}).addTo(map);

Working Examples:

[⬆]

geojson(config: object)

Create a GeoJSON layer and add it to a map.

Extends: L.GeoJSON

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) data (Object): A GeoJSON or TopoJSON object. Required if url is not provided.

OR

  • (Required) url (String): A URL to load the GeoJSON or TopoJSON data from. Required if data is not provided.

AND

  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) clickable (Boolean): Should interactivity (hover and click) operations be enabled for this layer? Defaults to true.
  • (Optional) cluster (Boolean): Should the layer's markers be clustered?
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) popup (String, Object, or Function): Configures the contents of the overlay's popups.
  • (Optional) styles (Object): Configures the overlay's styles.
  • (Optional) tooltip (String, Object, or Function): Configures the contents of the overlay's tooltips.
  • (Optional) zoomToBounds (Boolean): Should the map zoom to the bounds of this overlay when it is loaded?

You can also (optionally) provide any of the options supported by L.GeoJSON, minus these exceptions:

  1. pointToLayer
  2. style
  3. onEachFeature

These three options are not supported because they are used internally by OuterSpatial Map Library. If provided, they will be overwritten.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    type: 'geojson',
    url: 'data/national_parks.geojson'
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.geojson({
  url: 'data/national_parks.geojson'
}).addTo(map);

Working Examples:

[⬆]

github(config: object)

Create a layer from a GeoJSON or TopoJSON file stored on GitHub and add it to a map.

NOTE: This layer handler utilizes the GitHub API to pull data in. This API is limited to 60 requests per hour, so GitHub layers should only be used in development maps. If you want to use GitHub to host data for your production maps, you should setup a GitHub Pages site and utilize the CSV, GeoJSON, or KML layer handlers.

Extends: L.GeoJSON

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) path (String): The path to your GitHub file. This should not include your GitHub organization/user name or the name of the repository. This is the path to the GeoJSON file in your GitHub repository, e.g. fire/CA-STF-HV2F.geojson.
  • (Required) repo (String): The name of the repository that contains the data.
  • (Required) user (String): The name of the organization or user that owns the repository.
  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) branch (String) The name of the branch your GitHub file should be pulled in from. Defaults to master.
  • (Optional) clickable (Boolean): Should interactivity (hover and click) operations be enabled for this layer? Defaults to true.
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) popup (String, Object, or Function): Configures the contents of the overlay's popups.
  • (Optional) styles (Object): Configures the overlay's styles.
  • (Optional) tooltip (String, Object, or Function): Configures the contents of the overlay's tooltips.
  • (Optional) zoomToBounds (Boolean): Should the map zoom to the bounds of this overlay when it is loaded?

You can also (optionally) provide any of the options supported by L.GeoJSON, minus these exceptions:

  1. pointToLayer
  2. style
  3. onEachFeature

These three options are not supported because they are used internally by OuterSpatial Map Library. If provided, they will be overwritten.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    branch: 'gh-pages',
    path: 'base_data/boundaries/parks/yose.topojson',
    repo: 'data',
    type: 'github',
    user: 'nationalparkservice'
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.github({
  branch: 'gh-pages',
  path: 'base_data/boundaries/parks/yose.topojson',
  repo: 'data',
  user: 'nationalparkservice'
}).addTo(map);

Working Examples:

[⬆]

kml(config: object)

Create a KML layer and add it to a map.

NOTE: For OuterSpatial Map Library to load KML data, the data must be properly formatted. OuterSpatial Map Library uses toGeoJSON internally to convert KML to GeoJSON, so if your KML isn't loading properly, go and test it on the website.

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) data (Object): The string of KML data. Required if url is not provided.

OR

  • (Required) url (String): A URL to load the KML data from. Required if data is not provided.

AND

  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) clickable (Boolean): Should interactivity (hover and click) operations be enabled for this layer? Defaults to true.
  • (Optional) cluster (Boolean): Should the layer's markers be clustered?
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) popup (String, Object, or Function): Configures the contents of the overlay's popups.
  • (Optional) styles (Object): Configures the overlay's styles.
  • (Optional) tooltip (String, Object, or Function): Configures the contents of the overlay's tooltips.
  • (Optional) zoomToBounds (Boolean): Should the map zoom to the bounds of this overlay when it is loaded?

You can also (optionally) provide any of the options supported by L.GeoJSON, minus these exceptions:

  1. pointToLayer
  2. style
  3. onEachFeature

These three options are not supported because they are used internally by OuterSpatial Map Library. If provided, they will be overwritten.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    type: 'kml',
    url: 'data/national_parks.kml'
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.kml({
  url: 'data/national_parks.kml'
}).addTo(map);

Working Examples:

[⬆]

mapbox(config: object)

Create a Mapbox layer and add it to a map.

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) id (String): The id (account.id) of the Mapbox map or dataset you want to add to the map. Can also be a comma-delimited string with multiple account.id strings if you want to take advantage of Mapbox's compositing feature. Required if tileJson is not provided.

OR

  • (Required) tileJson (Object): A tileJson object for the Mapbox map or tileset you want to add to the map. Required if id is not provided.

AND

  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) clickable (Boolean): Should interactivity (hover and click) operations be enabled for this layer? Defaults to true.
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) format (String): The output format of the raster tiles. Valid values include: jpg70, jpg80, jpg90, png, png32, png64, png128, or png256. Defaults to png.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) popup (String, Object, or Function): Configures the contents of the overlay's popups.
  • (Optional) tooltip (String, Object, or Function): Configures the contents of the overlay's tooltips.

You can also (optionally) provide any of the options supported by L.TileLayer.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    id: 'examples.map-20v6611k',
    type: 'mapbox'
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.mapbox({
  id: 'examples.map-20v6611k'
}).addTo(map);

Working Examples:

[⬆]

spot(config: object)

Create a layer from a SPOT satellite device and add it to a map.

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) id (String): The id of the SPOT device whose data you want to add to the map.
  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) clickable (Boolean): Should interactivity (hover and click) operations be enabled for this layer? Defaults to true.
  • (Optional) cluster (Boolean): Should the layer's markers be clustered?
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) latest (Boolean): Only show the latest SPOT message (per device). If latest and minutesAgo are both specified, latest takes precedence.
  • (Optional) minutesAgo (Number): Show SPOT messages from this number of minutes ago. Maximum is 10080 (7 days). If latest and minutesAgo are both specified, latest takes precedence.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) password (String): SPOT feed password.
  • (Optional) popup (String, Object, or Function): Configures the contents of the overlay's popups.
  • (Optional) styles (Object): Configures the overlay's styles.
  • (Optional) tooltip (String, Object, or Function): Configures the contents of the overlay's tooltips.
  • (Optional) zoomToBounds (Boolean): Do you want to zoom the map to the extent of the points loaded from the SPOT device?

You can also (optionally) provide any of the options supported by L.GeoJSON, minus these exceptions:

  1. pointToLayer
  2. style
  3. onEachFeature

These three options are not supported because they are used internally by OuterSpatial Map Library. If provided, they will be overwritten.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    id: '08HVpMLpDksQjCeBL1FbTkqGHP4Bk7dfg',
    type: 'spot'
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map',
});

L.outerspatial.layer.spot({
  id: '08HVpMLpDksQjCeBL1FbTkqGHP4Bk7dfg'
}).addTo(map);

Working Examples:

[⬆]

tiled(config: object)

Create a tiled layer and add it to a map.

Arguments:

The first, and only, argument is required, and must be a config object with the following properties:

  • (Required) url (String): The templated URL string. Accepted parameters are:
    • {{s}}: Subdomain
    • {{x}}: X coordinate
    • {{y}}: Y coordinate
    • {{z}}: Zoom level
  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.

You can also (optionally) provide any of the options supported by L.TileLayer.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    attribution: '&copy; <a href="http://openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    type: 'tiled',
    url: 'http://{s}.tile.osm.org/{z}/{x}/{y}.png'
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.tiled({
  attribution: '&copy; <a href="http://openstreetmap.org/copyright">OpenStreetMap</a> contributors',
  url: 'http://{s}.tile.osm.org/{z}/{x}/{y}.png'
}).addTo(map);

Working Examples:

[⬆]

wms(config: object)

Create a WMS layer and add it to a map.

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) layers (String): A comma-delimited string of the layers from the WMS service to add to the layer.
  • (Required) url (String): The URL to the WMS service.
  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.

You can also (optionally) provide any of the options supported by L.TileLayer.WMS.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    attribution: 'NOAA',
    format: 'image/png',
    layers: 'RAS_RIDGE_NEXRAD',
    transparent: true,
    type: 'wms',
    url: 'http://nowcoast.noaa.gov/wms/com.esri.wms.Esrimap/obs'
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.wms({
  attribution: 'NOAA',
  format: 'image/png',
  layers: 'RAS_RIDGE_NEXRAD',
  transparent: true,
  url: 'http://nowcoast.noaa.gov/wms/com.esri.wms.Esrimap/obs'
}).addTo(map);

Working Examples:

[⬆]

zoomify(config: object)

Create a Zoomify layer and add it to a map.

NOTE: Zoomify layers do not contain spatial reference information, so they will not work with other layers. Because of this, when a Zoomify layer is added to a map, OuterSpatial Map Library ignores any other layers specified in the baseLayers and/or overlays configs.

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) height (Number): The height, in pixels, of the Zoomify layer.
  • (Required) url (String): The URL path to the directory that contains the Zoomify tiles.
  • (Required) width (Number): The width, in pixels, of the Zoomify layer.
  • (Optional) attribution (String): The attribution string for this layer. HTML is accepted.
  • (Optional) description (String): A description for the layer. Used by some controls and modules.
  • (Optional) name (String): A name for the layer. Used by some controls and modules.
  • (Optional) tolerance (Number): The tolerance to use when calculating the best initial zoom level. Defaults to 0.8.

You can also (optionally) provide any of the options supported by L.TileLayer.

Returns: a layer object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    height: 2737,
    type: 'zoomify',
    url: 'data/parkmaps/maca/img/',
    width: 6543
  }]
});

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.zoomify({
  height: 2737,
  url: 'data/parkmaps/maca/img/',
  width: 6543
}).addTo(map);

Working Examples:

[⬆]

Controls

Add functionality to your map using OuterSpatial Map Library' controls. Controls are added to either a control bar overlaid in one of the four corners of the map or a toolbar that displays above the map.

[⬆]

edit(config: object)

Create an edit control that supports adding markup shapes (points, lines, and polygons), and add it to a map.

Extends: L.Control

Arguments:

You can (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  editControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.edit().addTo(map);

Working Examples:

[⬆]

fullscreen()

Create a fullscreen control and add it to a map. The fullscreen control contains a button that toggles the map in and out of fullscreen mode.

Extends: L.Control

Arguments:

No arguments are accepted.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  fullscreenControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.fullscreen().addTo(map);

Working Examples:

[⬆]

geocoder(config: object)

Create a geocoder control that searches through both an index of National Parks and a more detailed geocoding service and add it to a map.

Extends: L.Control

Arguments:

The first, and only, argument is optional, and may be a control config object with the following properties:

  • (Optional) provider (String): Which supported provider should be used? Defaults to esri. Valid options are bing, esri, mapbox, mapquest, mapzen, and nominatim. Note that the mapquest and nominatim providers are limited to 15,000 transactions per month, so they are not recommended for production usage.
  • (Optional) searchPlaces (Boolean): Should the geocoder search through points of interest from the National Park Service's Places system? Defaults to false.

You can also (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  geocoderControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.geocoder().addTo(map);

Working Examples:

[⬆]

hash()

Create a control that updates the web browser's URL with current location (latitude and longitude) and zoom level information and add it to a map.

Extends: L.Class

Arguments:

No arguments are accepted.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  hashControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.hash().addTo(map);

Working Examples:

[⬆]

home(config: object)

Create a control that zooms and/or pans the map back to its initial center and zoom and add it to a map. This control is added to maps, by default.

Extends: L.Control

Arguments:

You can (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map'
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

[⬆]

infobox(config: object)

Create a control that displays "pinned" tooltip information.

Extends: L.Control

Arguments:

You can (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  infoboxControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.infobox().addTo(map);

[⬆]

legend(config: object)

Create a control that displays legend information and add it to a map.

Extends: L.Control

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required property:

  • (Required) html (String): A string of HTML to add to the control.

You can also (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  legendControl: {
    html: '' +
      '<h3>Legend</h3>' +
      '<ul>' +
        '<li>Item 1</li>' +
        '<li>Item 2</li>' +
      '</ul>' +
    ''
  }
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.legend({
  html: '' +
    '<h3>Legend</h3>' +
    '<ul>' +
      '<li>Item 1</li>' +
      '<li>Item 2</li>' +
    '</ul>' +
  ''
}).addTo(map);

Working Examples:

[⬆]

locate(config: object)

Create a control that uses the web browser geolocation functionality to display the location of the current user and add it to a map.

Extends: L.Control

Arguments:

You can (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  locateControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.locate().addTo(map);

Working Examples:

[⬆]

measure(config: object)

Create a control that supports drawing area and distance measurements and add it to a map.

Extends: L.Control

Arguments:

The first, and only, argument is optional, and may be a config object with the following properties:

  • (Optional) units (Object): An object, with one or both area (Array) and distance (Array) properties that tell OuterSpatial Map Library which units to support with the control. Valid area units are acres (ac) and hectares (ha). Valid distance units are feet (f), meters (m), and miles (mi). The control defaults to all available area and distance units.

You can also (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  measureControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.measure().addTo(map);

Working Examples:

[⬆]

overview(config: object)

Create a map control that provides context for the currently-visible area of the map and it to a map. Adapted from the Leaflet-MiniMap plugin.

Extends: L.Control

Arguments:

The first, and only, argument is required. It must be a config object comprised of the following required and optional properties:

  • (Required) layer (String|Object): A config object that you would like to add to the map. Can either be a layer preset string or a config object.
  • (Optional) autoToggleDisplay (Boolean): Should the overview hide automatically if the parent map bounds does not fit within the bounds of the overview map? Defaults to false.
  • (Optional) height (Number): The height of the overview map. Defaults to 150 pixels.
  • (Optional) toggleDisplay (Boolean): Should the overview map be togglable? Defaults to true.
  • (Optional) width (Number): The width of the overview map. Defaults to 150 pixels.
  • (Optional) zoomLevelFixed (Number): Overrides zoomLevelOffset, sets the map to a fixed zoom level.
  • (Optional) zoomLevelOffset (Number): A positive or negative number that configures the overview map to a zoom level relative to the zoom level of the main map.

You can also (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overviewControl: {
    layer: 'mapbox-light'
  }
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.overview({
  layer: 'mapbox-light'
}).addTo(map);

Working Examples:

[⬆]

print(config: object)

Create a print control and add it to a map. The print control loads a print-optimized web page with the current map, including latitude, longitude, and zoom level, in a new browser tab or window.

Extends: L.Control

Arguments:

The first, and only, argument is optional, and may be a config object with the following properties:

  • (Optional) ui (Boolean): Should the control add its user interface (UI) to the map? Defaults to true.
  • (Optional) url (String): A URL to a print-optimized web page. Defaults to https://www.trailheadlabs.com/labs/outerspatial-map-library/print/.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  printControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.print().addTo(map);

Working Examples:

[⬆]

scale(config: object)

Create a scale control and add it to a map.

Extends: L.Control.Scale

Arguments:

You can (optionally) provide any of the options supported by L.Control.Scale.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  scaleControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.scale().addTo(map);

Working Examples:

[⬆]

smallzoom(config: object)

Create a map control that contains zoom in/out buttons and add it to a map. This control is added to maps, by default.

Extends: L.Control

Arguments:

You can (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map'
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

[⬆]

switcher()

The switcher control is used internally by OuterSpatial Map Library. It is automatically created and added to a map when more than one config object is present in a map's baseLayers property. It should not be created manually.

[⬆]

zoomdisplay()

Create a control to display the map's current zoom level and add it to a map.

Extends: L.Control

Arguments:

You can (optionally) provide any of the options supported by L.Control.

Returns: a control object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  zoomdisplayControl: true
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.control.zoomdisplay().addTo(map);

Working Examples:

[⬆]

Modules

OuterSpatial Map Library modules are standalone pieces of functionality that can be added and integrated into a map.

directions

Docs coming soon.

[⬆]

Icons

maki(config: object)

Create an icon using the Maki icon set.

Extends: L.Icon

Arguments:

You can (optionally) provide any of the options supported by L.Icon.

Returns: an icon object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    cluster: true,
    styles: {
      point: {
        'marker-color': '#5e9fd5',
        'marker-size': 'small',
        'marker-symbol': 'city'
      }
    },
    type: 'csv',
    url: 'data/colorado_cities_simplestyle.csv'
  }]
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.csv({
  cluster: true,
  styles: {
    point: {
      'marker-color': '#5e9fd5',
      'marker-size': 'small',
      'marker-symbol': 'city'
    }
  },
  type: 'csv',
  url: 'data/colorado_cities_simplestyle.csv'
}).addTo(map);

Working Examples:

[⬆]

outerspatialsymbollibrary(config: object)

Create an icon using the OuterSpatial Symbol Library icon set.

Extends: L.Icon

Arguments:

You can (optionally) provide any of the options supported by L.Icon.

Returns: an icon object

Example (Bootstrap):

var OuterSpatial = {
  div: 'map',
  overlays: [{
    cluster: true,
    styles: {
      point: {
        'marker-color': '#5e9fd5',
        'marker-library': 'outerspatialsymbollibrary',
        'marker-size': 'small',
        'marker-symbol': 'campsite-white'
      }
    },
    type: 'csv',
    url: 'data/campsites.csv'
  }]
};

Example (API):

var map = L.outerspatial.map({
  div: 'map'
});

L.outerspatial.layer.csv({
  cluster: true,
  styles: {
    point: {
      'marker-color': '#5e9fd5',
      'marker-library': 'outerspatialsymbollibrary',
      'marker-size': 'small',
      'marker-symbol': 'campsite-white'
    }
  },
  type: 'csv',
  url: 'data/campsites.csv'
}).addTo(map);

Working Examples:

[⬆]

Presets

Presets in OuterSpatial Map Library can be be used as shortcuts to add commonly-used layers and styling to a map.

[⬆]

baseLayer

OuterSpatial Map Library includes support for adding baseLayers via string presets. This makes it easy to add one or more baseLayers to your map without knowing the technical details required to manually configure it. To use presets, simply add one or more preset strings (outlined below) to the baseLayers property:

var OuterSpatial = {
  div: 'map',
  baseLayers: [
    'mapbox-streets'
  ]
};

The following baseLayer preset strings are supported:

  • Bing
    • bing-aerial
    • bing-aerialLabels
    • bing-roads
  • CartoDB
    • cartodb-darkMatter
    • cartodb-darkMatterNoLabels
    • cartodb-positron
    • cartodb-positronNoLabels
  • Esri
    • esri-gray
    • esri-imagery
    • esri-nationalGeographic
    • esri-oceans
    • esri-shadedRelief
    • esri-streets
    • esri-terrain
    • esri-topographic
  • Mapbox
    • mapbox-dark
    • mapbox-emerald
    • mapbox-highContrast
    • mapbox-landsatLive
    • mapbox-light
    • mapbox-outdoors
    • mapbox-pencil
    • mapbox-satellite
    • mapbox-satelliteLabels
    • mapbox-streets
    • mapbox-terrain
  • OpenStreetMap
    • openstreetmap
  • OuterSpatial
    • landscape
    • outdoors
    • satellite
  • Stamen
    • stamen-terrain
    • stamen-toner
    • stamen-watercolor

Take a look at the baseLayer presets example for more information.

[⬆]

Utils

Docs coming soon.

[⬆]

Concepts

Understanding a few fundamental concepts will help you get the most out of OuterSpatial Map Library.

[⬆]

Bootstrap vs. API

There are three ways to use OuterSpatial Map Library: The "Bootstrap" method, the "API" method, and the "Hybrid" method.

Bootstrap

To create a map using the Bootstrap method, create an OS config object and add configuration properties to it as documented above. Then load os-bootstrap.js and OuterSpatial Map Library takes over from there.

This method is the recommended (and easiest) way to create maps with OuterSpatial Map Library, and it takes full advantage of the power of OuterSpatial Map Library. It includes "extras" like a spinning loading indicator and automatic loading of os.css.

API

It is also possible to create maps by interacting directly with the OuterSpatial Map Library API in a way similar to other more "traditional" web mapping libraries like Google Maps and the ArcGIS JavaScript API. This method requires a manual load of both outerspatial.css and outerspatial.js, and it lacks the "extras" that come along with the Bootstrap method. It also requires at least a general understanding of JavaScript.

Hybrid

Trailhead Labs builds many of its maps using a hybrid approach that uses outerspatial-bootstrap.js to do the initial configuration and load of a map and then takes advantage of OuterSpatial Map Library' hooks and API to add custom functionality.

This approach gets the best of both the Bootstrap and API methods: Easy initial configuration with advanced programmatic access for complete control. This approach also has an added benefit of consistency. Every map built using this hybrid approach is laid out (or "scaffolded") in a consistent way.

This hybrid approach is possible because OuterSpatial Map Library exposes the underlying Map, Layer, Control, and Module objects so they can be interacted with programatically after they are initialized.

For example, once OuterSpatial Map Library creates a map it exposes the internal map object via a L property on the OS.config object. This means you can access the object like this: OuterSpatial.config.L.

You can also access the baseLayers and overlays objects initialized by OuterSpatial Map Library in a similar way:

  • OuterSpatial.config.baseLayers[0].L gets a reference to the layer object for the first baseLayer
  • OuterSpatial.config.overlays[0].L gets a reference to the layer object for the first overlay

[⬆]

Hooks

You can use the preinit and init hooks to add custom functionality to your map. Both hooks must accept a callback function and execute it to pass control back to OuterSpatial Map Library.

var OuterSpatial = {
  div: 'map',
  hooks: {
    preinit: function(callback) {
      // Add custom code here.
      callback();
    },
    init: function(callback) {
      // Add custom code here.
      callback();
    }
  }
};

The preinit hook is called after OuterSpatial Map Library has loaded all of its dependencies and any plugins specified in the plugins config. The init hook is called after OuterSpatial Map Library creates the map and has created any layers specified in the baseLayers or overlays configs.

[⬆]

Multiple Maps

Unlike previous versions of the OuterSpatial Map Library library, the Bootstrap method supports adding multiple maps to the same web page. To add multiple maps, make the OuterSpatial config object an array of map configuration objects:

var OuterSpatial = [{
  div: 'map-1'
},{
  div: 'map-2'
}];

[⬆]

Plugins

If you need to add functionality that isn't supported by OuterSpatial Map Library to a map, you can load a Leaflet plugin. The plugins configuration can be used to load plugins:

var OuterSpatial = {
  div: 'map',
  plugins: [{
    js: 'plugins/Leaflet.GeometryUtil/0.8.0/plugin.min.js'
  },{
    js: 'plugins/Leaflet.Snap/0.4.0/plugin.min.js'
  }]
};

OuterSpatial Map Library will load any CSS files (specified in the css property) and JavaScript files (specified in the js property). These plugins will be available in both the preinit and init hooks.

Working Examples:

[⬆]

Using Popups

Popups display when you click on a feature in an overlay. Each popup is made up of three markup sections, with each having one or more nested subsection:

  1. Header
    • Title
  2. Content
    • Media
    • Description
  3. Footer
    • Actions

If you do not specify a popup property on your layer object, OuterSpatial Map Library will use a set of sensible defaults to configure the popup. If, however, you specify a popup property on your layer object, OuterSpatial Map Library will only implement what you have specified. For example, if your popup property looks like the following:

popup: {
  title: '{{Name}}'
}

OuterSpatial Map Library will only display the title in the popup and will not render any other popup elements.

The content for each of the sections of a popup should be specified individually via a popup configuration object:

var OuterSpatial = {
  div: 'map',
  overlays: [{
    ...
    popup: {
      // {Array}, {String}, or {Function}. If a {Function}, it must return an {Array} or {String}.
      actions: [{
        handler: function() {
          window.alert('Clicked!');
        },
        text: 'Click Me!' // No HTML allowed, but Handlebars is supported
      },{
        menu: [{
          handler: function() {
            window.alert('You clicked Menu Item 1');
          },
          text: 'Menu Item 1' // No HTML allowed, but Handlebars is supported
        },{
          handler: function() {
            window.alert('You clicked Menu Item 2');
          },
          text: 'Menu Item 2' // No HTML allowed, but Handlebars is supported
        }],
        text: 'Menu' // No HTML allowed, but Handlebars is supported
      }],
      // {Object}, {String} or {Function}. If a {Function}, it must return an {Object} or {String}.
      description: '<p style="color:red;">{{description}}</p>',
      description: {
        // {Array} (if undefined, all fields and values are displayed)
        fields: [
          'Name',
          'Description'
        ],
        // {String} ('table' or 'list') (if undefined, defaults to 'table')
        format: 'table'
      },
      // {Array}, {String}, or {Function} (that returns an {Array} or {String})
      media: [{
        id: '',
        type: 'focus' // Focus is currently the only supported system
      }],
      // Used to configure the "more" title for layers that support multiple results. No HTML allowed, but Handlebars is supported.
      more: '{{Name}}',
      // {String} or {Function}. If a {Function} it must return a {String}. {String}s support both HTML and Handlebars.
      title: function(data) {
        if (data.level > 5) {
          return 'Greater than 5!';
        } else {
          return 'Less than 5!';
        }
      }
    }
  }]
};

If you are embedding media (images, audio, and/or video) in your popup, you should hardcode the height and width of the media in your HTML so OuterSpatial Map Library can size the popup appropriately:

var OuterSpatial = {
  div: 'map',
  overlays: [{
    ...
    popup: {
      description: '<img src="{{img_url}}" style="height:300px;width:400px;">'
    }
  }]
};

HTML and Handlebars are supported for many popup elements (take a look at the comments in the code sample above to see which elements support HTML and/or Handlebars).

OuterSpatial Map Library also adds a number of "helpers" to Handlebars. These helpers can be used to format popups:

  • ifCond (available operators include '!=', '!==', '==', '===', '<', '<=', '>', '>=', '&&', and '||')
    description: "I am {{#ifCond Name '===' 'A Rectangle'}}indeed{{else}}not{{/ifCond}} a rectangle! (Verified by a custom Handlebars helper.)"
  • toLowerCase
    title: '{{toUpperCase Name}}'
  • toUpperCase
    title: '{{toUpperCase Name}}'
  • toInt
    description: '{{toInt StrInt}}'

You can see examples of configuring popups for overlays in the popups example.

[⬆]

Using Tooltips

Tooltips display when you hover over a feature in an overlay. Tooltips only work for layer handlers that support mouseover and mouseout operations (currently CartoDB, CSV, GeoJSON, GitHub, KML, Mapbox, and SPOT).

Tooltips should be short and succinct. Both HTML and Handlebars strings are supported by tooltips.

var OuterSpatial = {
  div: 'map',
  overlays: [{
    ...
    tooltip: '{{UnitCode}}'
  }]
};

You can see examples of configuring tooltips for overlays in the tooltips example.

[⬆]

Styling Vectors

OuterSpatial Map Library uses the simplestyle specification internally. It currently, at v1.1.0, includes the following properties:

fill
fill-opacity
marker-color
marker-size
marker-symbol
stroke
stroke-opacity
stroke-width

In addition, OuterSpatial Map Library supports the following property that is not supported by the simplestyle specification:

marker-library

This property is optional. It defaults to maki, and can also be outerspatial.

Styles for vector shapes can be set in multiple ways. OuterSpatial Map Library looks in the following order for styles:

  1. In the properties pulled in for each feature from the data source. You can tell OuterSpatial Map Library to ignore feature styles by setting the ignoreFeatureStyles property to true. For example, if a GeoJSON point feature has a marker-symbol property, it will be used to style the marker on the map unless ignoreFeatureStyles is set to true in the styles geometry (line, point, or polygon) object of an overlay's configuration.
  2. In an overlay's configuration object, via a styles property, with line, point, and/or polygon properties designated as:
    1. an object
    2. a function that is passed a data object for each feature and returns a style object

If no styles are found in these two places, OuterSpatial Map Library falls back to a set of default styles.

If you prefer not to use the simplestyle specification, you can utilize the out-of-the-box Leaflet styles for the line (L.Path), point (L.Icon), and polygon (L.Path) styles object on your overlay configuration. OuterSpatial Map Library will then pass the object directly to Leaflet.

Note: Style properties cascade. This means that if a marker-symbol property is passed in via the data source (e.g. a GeoJSON feature's properties) and a marker-color property is passed in via the overlay config object, the geometry will be styled with both the marker-symbol and marker-color properties unless the ignoreFeatureStyles property is present.

Take a look at the Styling Vectors example to see an example of using the different configuration options to style overlay's.

[⬆]