8. Datalayers

Scott Fairgrieve edited this page Dec 14, 2016 · 17 revisions

Support loading and displaying data from any JSON-based object/collection

L.DataLayer

Display data values using L.RegularPolygonMarker instances. To override the default marker behavior, use the getMarker option or inherit from DataLayer and override _getMarker. In thematic mapping, this class displays data using proportional symbols.

NOTE: If the location features are lines/polygons (e.g. GeoJSON), this class will use the centroid of each line/polygon to place each marker. When dealing with line/polygon features, you must include a reference to the JavaScript Topology Suite (JSTS) JS files. These files are used to calculate centroids. If these files are not included, the DataLayer class will fallback to using the center of the bounds of the layer's geometry.

Usage

L.DataLayer(<Object> data, <DataLayer options> options?);

Options

recordsField

Type: String

Default: 'features'

A pointer to the field in the input data that contains the records to be visualized. Use null when the data being passed in is the set of records to be visualized. Use dot notation to specify child properties (e.g. data.election.resultsByState), see note below.

locationMode

Type: String

Default: 'latlng' OR L.LocationModes.LATLNG

The mode used to determine a location for each record. Use a string or the L.LocationModes constant values

latitudeField

Type: String

Default: 'coordinates.1'

The property of each record that contains the latitude NOTE: Use with 'latlng' locationMode

longitudeField

Type: String

Default: 'coordinates.0'

The property of each record that contains the longitude NOTE: Use with 'latlng' locationMode

codeField

Type: String

Default: null

The property of each record that contains the code used to lookup a location NOTE: Use with 'state', 'country', or 'lookup' locationMode values

geohashField

Type: String

Default: null

The property of each record that contains the geohash used to determine a location NOTE: Use with 'geohash' locationMode values

layerOptions

Type: Object

Default: null

Default style - An object containing Leaflet L.Path style properties that will be used as the default style for DataLayer markers/polygons. These properties will be overridden by the displayOptions.

displayOptions

Type: Object

Default: null

Dynamic styles - An object containing pointers to one or property values of each record with associated L.Path style properties and LinearFunction objects

tooltipOptions

Type: Object

Default: null

Options used to configure the tooltips that are displayed on mouseover (iconSize and iconAnchor)

showLegendTooltips

Type: Boolean

Default: true

Set this to false to disable tooltips on DataLayer layers displayed on the map

dynamicOptions

Type: Function

Default: null

A function that takes a record as input and returns an object with layerOptions and legendDetails properties. Both properties are key/value pairs. layerOptions follows the Leaflet layer style conventions (e.g. color, fillColor, etc.) and legendDetails are key/value pairs that describe what fields/values to display, where the value is an object with name and value properties. These options are used to control the appearance of tooltips.

onEachRecord

Type: Function

Default: null

A function that performs additional operations (e.g. binding a popup) on a created layer based on the record associated with that layer (similar to the L.GeoJSON onEachFeature method). Note that the parameter ordering is: layer, record. This is slightly different from the L.GeoJSON onEachFeature method, where the ordering is: featureData, layer.

includeLayer OR filter

Type: Function

Default: null

A function for determining whether or not the layer for a given record should be added to the map.

getLocation

Type: Function

Default: null

A function for getting a custom location from a record (e.g. looking up an address) NOTE: Use with 'custom' locationMode value

locationLookup

Type: Object (GeoJSON FeatureCollection)

Default: null

A GeoJSON FeatureCollection that will be used to lookup the location associated with a given record. This is useful when you have some data that maps to political/statistical boundaries other than US states or countries. NOTE: Use with 'lookup locationMode

locationIndexField

Type: String

Default: null

A string identifying the field that will be used to index GeoJSON Feature objects when the locationMode is L.LocationModes.LOOKUP. If you don't specify this field, the DataLayer will use the codeField value as the property to use when indexing GeoJSON Features

includeBoundary

Type: Boolean

Default: false

true/false - whether or not the boundary polygon should be displayed when displaying proportional symbols. This is useful for identifying the boundary associated with each symbol.

boundaryStyle

Type: Object

Default: null

Path style options used for specifying how the boundary associated with the point will be displayed

getMarker

Type: Function

Default: null

A function for overriding the default marker that gets placed at each location. The function takes a latlng and options as parameters.

deriveProperties

Type: Function

Default: null

A function that takes a record as input and returns a new record derived from that input record. This is useful for styling features based on properties derived from some combination of properties in the base record or for augmenting records with additional properties.

getIndexKey

Type: Function

Default: null

A function that takes a location and record as input and returns a string that will be used to uniquely identify a layer created from a given record. Supplying this function optimizes layer management behind the scenes and ensures that layers won't be removed and re-added when you change data or call setDisplayOptions/setDisplayOption, which should result in better performance.

getTrack

Type: Function

Default: null

A function that takes a layer, location, and reference to an existing track layer and returns an updated track layer. This is used in conjunction with getIndexKey to highlight the movement of layers.

Referencing Data Properties

Use dot notation to reference items in the passed in data object. This applies to all field options (e.g. recordsField) as well as displayOptions.

Given an object like:

{
	data: {
		values: [
			{
				property1: 1,
				property2: 'akdfljlkfds',
				property3: 234,
				location: [-1.234324, 13.123213],
				additional: {
					property1: 2,
					property2: 56
				}
			},
			...
			{
				property1: 34,
				property2: 'werewrwer',
				property3: 56,
				location: [5.435444, 8.999345],
				additional: {
					property1: 88,
					property2: 3
				}
			}
		]
	}
}

You might specify the following options:

{
	recordsField: 'data.values',
	locationMode: L.LocationModes.LATLNG,
	latitudeField: 'location.1'  // Points to the second item in the location array
	longitudeField: 'location.0' // Points to the first item in the location array,
	displayOptions: {
		'additional.property1': {
			... // See displayOptions below
		}
	}
}

displayOptions

The displayOptions option is used to define how data properties are dynamically mapped to display styles. It's a JavaScript object of key/value pairs that follows the pattern:

{
	<reference to data property 1>: {
		displayName: <Human-readable text describing this property>,
		displayText: <Function for converting the value of this property to a human-readable value>,
		// Leaflet L.Path style properties with static values or L.LinearFunction instances
		// or just functions for dynamic mapping
		color:  <Color function or basic function (e.g. L.HSLHueFunction)>,
		fillColor:  <Color function or basic function (e.g. L.HSLHueFunction)>,
		...
	},
	<reference to data property 2>: {
		displayName: ...,
		displayText: ...,
		...
	},
	...
	<reference to data property X>: {
		displayName: ...,
		displayText: ...,
		...
	}
}

Location Modes

Use L.LocationModes to specify the locationMode option. This tells a DataLayer instance how to determine the location of each marker or polygon to draw. There are several different location modes available.

L.LocationModes.LATLNG

The location is a latitude and longitude. Use latitudeField and longitudeField to tell the DataLayer where to look for these values

L.LocationModes.GEOHASH

The location is a geohash. Use geohashField to tell the DataLayer what property contains the geohash

L.LocationModes.GWCOUNTRY

The location is a Gledistch and Ward country code. Use codeField to tell the DVF what property contains the country code

L.LocationModes.COUNTRY

The location is an ISO-2 or ISO-3 country code. Use codeField to tell the DVF what property contains the country code

L.LocationModes.STATE

The location is a US state code. Use codeField to tell the DVF what property contains the state code

L.LocationModes.GEOJSON

The location is a GeoJSON Feature. Use geoJSONField to tell the DVF what property contains the GeoJSON

L.LocationModes.LOOKUP

The location can be found in an object lookup of keys/values. This lookup can be specified by a property called locationLookup, which is expected to be a GeoJSON FeatureCollection. Use codeField to tell the DVF what property of the data contains the code to use along with the lookup. Using codeField only implies that both the GeoJSON FeatureCollection and the data used to lookup locations in that FeatureCollection have properties with the same key (e.g. "code"). If your FeatureCollection does not have a property with the same name as the data you will be using, you can use the locationIndexField option to tell the DVF what property of the GeoJSON FeatureCollection should be used as the key/index in the created lookup. The DVF will use codeField to find a matching value in the data passed to a DataLayer. The text that is displayed for a given location can be specified using the locationTextField option. This is a pointer to a property of each feature in the GeoJSON FeatureCollection specified in locationLookup.

L.LocationModes.CUSTOM

The location is provided through a custom lookup function called getLocation. getLocation has the following signature getLocation(context, locationField, , callback). When a location has been retrieved, this function is expected to call callback, which has a signature of callback(key, location), where key is the value of locationField and location is the associated location. Using a callback function allows getLocation to call out to an asynchronous web service (e.g. an address lookup) and return results when they're available.

ChartDataLayers

Display data values using ChartMarker instances (inherits from L.DataLayer)

Usage

L.BarChartDataLayer(<Object> data, <ChartDataLayer options> options?);
L.RadialBarChartDataLayer(<Object> data, <ChartDataLayer options> options?);
L.PieChartDataLayer(<Object> data, <ChartDataLayer options> options?);
L.CoxcombChartDataLayer(<Object> data, <ChartDataLayer options> options?);
L.StackedRegularPolygonDataLayer(<Object> data, <ChartDataLayer options> options?);
L.RadialMeterMarkerDataLayer(<Object> data, <ChartDataLayer options> options?);

Options

Option Type Default Description

NOTE: You can use the displayOptions option to size ChartMarker instances dynamically by some property of each record. See the DataLayer options above for more information about displayOptions.

L.ChoroplethDataLayer

Display data values using dynamically styled points, lines, and polygons (inherits from L.DataLayer)

Choropleth Data Layer Choropleth Data Layer

Usage

L.ChoroplethDataLayer(<Object> data, <DataLayer options> options?);

Options

Option Type Default Description

L.MarkerDataLayer

Display data values using markers based on L.Icon or L.DivIcon icons (inherits from L.DataLayer)

Usage

L.MarkerDataLayer(<Object> data, <MarkerDataLayer options> options?);

Options

Option Type Default Description

L.Graph

A special type of DataLayer that displays relationships between geographic features using straight or arced lines (inherits from L.DataLayer)

Usage

L.Graph(<Object> data, <Graph options> options?);

Options (in addition to the L.DataLayer style options)

fromField

Type: String

Default: 'from'

A reference to the field (e.g., record.properties.link.id.0) in a record that describes the geospatial feature from which the line will start

toField

Type: String

Default: 'to'

A reference to the field (e.g., record.properties.link.id.1) in a record that describes the geospatial feature to which the line will terminate

getEdge

Type: Function

**Default: L.Graph.EDGESTYLE.STRAIGHT

A function that returns a line connecting the provided from and to features. Out of the box options are L.Graph.EDGESTYLE.ARC and L.Graph.EDGESTYLE.STRAIGHT.

L.PanoramioLayer

Display Panoramio images on the map. Shows the top 50 most popular images for the current map view. NOTE: Requires Moment.js Check out Panoramio Browser for an example of using this layer.

Panoramio Layer

Usage

L.PanoramioLayer(<PanoramioLayer options> options?);

Options (in addition to the L.DataLayer style options)

photoSet

Type: String

Default: 'public'

The Panoramio API photo set to use for retrieving images. Can be one of 'public' - the most popular photos, 'full' - all photos, or a specific author id

updateInterval

Type: Number

Default: 300000

The number of milliseconds to wait before updating the current view

size

Type: String

Default: 'square'

The marker image size ("square" or "mini_square")

refreshEvents

Type: String

Default: 'moveend'

The Leaflet events that will trigger a refresh of photos (separate with spaces)

onEachPhoto

Type: Function

Default: null

A function that will be called for each photo in the collection of retrieved photos. This is similar to the onEachRecord function of a DataLayer.

Legends

Useful for visually informing users about the dynamic styles associated with your L.DataLayer instances

L.Control.Legend

Add this control to your map to automatically display a dynamic legend for any L.DataLayer based instance that you add to your map

var legendControl = new L.Control.Legend();

legendControl.addTo(map);

L.DataLayer - getLegend()

Call getLegend on any L.DataLayer instance to get an HTML element that can be added to your page

Usage

layer.getLegend(<Legend options> options?);

var layer = new L.DataLayer(data, {...});

layer.getLegend(); // Returns HTML

Options

className

Type: String

Default: null

A class name that will be added to the legend element, useful for adding custom CSS styles

numSegments

Type: Number

Default: 10

The number of segments/bars to include in the legend element

width

Type: Number

Default: 100

The desired width of the legend element

gradient

Type: Boolean

Default: false

Whether cells in the legend should use a gradient that blends the min color into the max color for that cell