Class TimeMap

Defined in:: timemap.js

The TimeMap object holds references to timeline, map, and datasets.

Constructor

TimeMap(tElement, mElement, options)

Static Fields

	Field
	TimeMap.version :{String} [constant] Current library version.

Static Methods

	Method
	TimeMap.init(config) Intializes a TimeMap.

Fields

	Field
	chains :{Object} Filter chains for this timemap
	datasets :{Object} Map of datasets
	map :{GMap2} The associated GMap object
	mapBounds :{GLatLngBounds} Bounds of the map
	mElement :{DOM Element} Map element
	opts :{Object} Container for optional settings passed in the "options" parameter
	tElement :{DOM Element} Timeline element
	timeline :{Timeline} The associated timeline object

Methods

	Method
	addExportData(data) Specify additional data for export.
	addFilter(fid, f) Add a function to a filter chain
	addFilterChain(fid, fon, foff, pre, post) Add a new filter chain
	changeMapType(mapType) Change the default map type
	changeTimeIntervals(intervals) Change the intervals on the timeline.
	clear() Delete all datasets, clearing them from map and timeline.
	createDataset(id, options) Create an empty dataset object and add it to the timemap
	deleteDataset(id) Delete one dataset, clearing it from map and timeline
	each(f) Run a function on each dataset in the timemap.
	eachItem(f) Run a function on each item in each dataset in the timemap.
	filter(fid) Update items, hiding or showing according to filters
	getItems() Get all items from all datasets.
	getState() Get a configuration object of state variables
	getStateParamString() Get current state parameters serialized as a hash string
	getStateUrl() Get URL with current state parameters in hash
	hideDataset(id) Hides placemarks for a given dataset
	hideDatasets() Hides all the datasets on the map
	initMap() Initialize the map.
	initState() Initialize state tracking based on URL.
	initTimeline(bands) Initialize the timeline - this must happen separately to allow full control of timeline properties.
	makeOptionData() Make a cleaned up object for the TimeMap options
	parseDate(s) Parse a date in the context of the timeline.
	refreshTimeline() Refresh the timeline, maintaining the current date
	removeFilter(fid, f) Remove a function from a filter chain
	removeFilterChain(fid) Remove a filter chain
	scrollToDate(d, lazyLayout) Scroll the timeline to a given date.
	setState(state) Set the timemap state with a set of configuration options.
	setStateFromUrl() Set the timemap state with parameters in the URL
	showDataset(id) Shows placemarks for a given dataset
	showDatasets() Shows all the datasets on the map
	toJSON() Clean up TimeMap into a nice object for serialization This is called automatically by the JSON.stringify() function

Class Detail

TimeMap(tElement, mElement, options)

Parameters (optional)
tElement	{DOM Element}	The timeline element.
mElement	{DOM Element}	The map element.
options	{Object}	A container for optional arguments
options.theme	{TimeMapTheme\|String}	Color theme for the timemap Default: red
options.syncBands	{Boolean}	Whether to synchronize all bands in timeline Default: true
options.mapCenter	{GLatLng}	Point for map center Default: 0,0
options.mapZoom	{Number}	Initial map zoom level Default: 0
options.mapType	{GMapType\|String}	The maptype for the map Default: physical
options.mapTypes	{Array}	The set of maptypes available for the map Default: normal,satellite,physical
options.mapFilter	{Function\|String}	How to hide/show map items depending on timeline state; options: keys in TimeMap.filters or function Default: TimeMap.filters.hidePastFuture
options.showMapTypeCtrl	{Boolean}	Whether to display the map type control Default: true
options.showMapCtrl	{Boolean}	Whether to show map navigation control Default: true
options.centerMapOnItems	{Boolean}	Whether to center and zoom the map based on loaded item Default: true
options.noEventLoad	{Boolean}	Whether to skip loading events on the timeline Default: false
options.noPlacemarkLoad	{Boolean}	Whether to skip loading placemarks on the map Default: false
options.eventIconPath	{String}	Path for directory holding event icons; if set at the TimeMap level, will override dataset and item defaults
options.infoTemplate	{String}	HTML for the info window content, with variable expressions (as "{{varname}}" by default) to be replaced by option data
options.templatePattern	{String}	Regex pattern defining variable syntax in the infoTemplate
options.openInfoWindow	{Function}	Function redefining how info window opens Default: TimeMapItem.openInfoWindowBasic
options.closeInfoWindow	{Function}	Function redefining how info window closes Default: TimeMapItem.closeInfoWindowBasic
options[...]	{mixed}	Any of the options for TimeMapTheme may be set here, to cascade to the entire TimeMap, though they can be overridden at lower levels

Static Field Details

TimeMap.version :{String}

[constant] Current library version.

Static Method Details

TimeMap.init(config) :{TimeMap}

Intializes a TimeMap.

The idea here is to throw all of the standard intialization settings into a large object and then pass it to the TimeMap.init() function. The full data format is outlined below, but if you leave elements out the script will use default settings instead.

See the examples and the UsingTimeMapInit wiki page for usage.

Parameters (optional)
config	{Object}	Full set of configuration options.
config.mapId	{String}	DOM id of the element to contain the map
config.timelineId	{String}	DOM id of the element to contain the timeline
config.options	{Object}	Options for the TimeMap object (see the TimeMap constructor)
config.datasets	{Object[]}	Array of datasets to load
config.datasets[x]	{Object}	Configuration options for a particular dataset
config.datasets[x].type	{String\|Class}	Loader type for this dataset (generally a sub-class of TimeMap.loaders.base)
config.datasets[x].options	{Object}	Options for the loader. See the TimeMap.loaders.base constructor and the constructors for the various loaders for more details.
config.datasets[x].id	{String}	Optional id for the dataset in the TimeMap#datasets object, for future reference; otherwise "ds"+x is used
config.datasets[x][...]	{String}	Other options for the TimeMapDataset object
config.bandIntervals	{String\|Array}	Intervals for the two default timeline bands. Can either be an array of interval constants or a key in TimeMap.intervals
config.bandInfo	{Object[]}	Array of configuration objects for Timeline bands, to be passed to Timeline.createBandInfo (see the Timeline Getting Started tutorial). This will override config.bandIntervals, if provided.
config.bands	{Timeline.Band[]}	Array of instantiated Timeline Band objects. This will override config.bandIntervals and config.bandInfo, if provided.
config.dataLoadedFunction	{Function}	Function to be run as soon as all datasets are loaded, but before they've been displayed on the map and timeline (this will override dataDisplayedFunction and scrollTo)
config.dataDisplayedFunction	{Function}	Function to be run as soon as all datasets are loaded and displayed on the map and timeline
config.scrollTo	{String\|Date}	Date to scroll to once data is loaded - see TimeMap.parseDate for options; default is "earliest"

Returns:: {TimeMap} The initialized TimeMap object

Field Details

chains :{Object}

Filter chains for this timemap

datasets :{Object}

Map of datasets

map :{GMap2}

The associated GMap object

mapBounds :{GLatLngBounds}

Bounds of the map

mElement :{DOM Element}

Map element

opts :{Object}

Container for optional settings passed in the "options" parameter

tElement :{DOM Element}

Timeline element

timeline :{Timeline}

The associated timeline object

Method Details

addExportData(data) :{Object}

Specify additional data for export. Replace this function to change settings.

Parameters (optional)
data	{Object}	Initial map of export data

Returns:: {Object} Expanded map of export data
Defined in:: export.js

addFilter(fid, f)

Add a function to a filter chain

Parameters (optional)
fid	{String}	Id of the filter chain
f	{Function}	Function to add

addFilterChain(fid, fon, foff, pre, post)

Add a new filter chain

Parameters (optional)
fid	{String}	Id of the filter chain
fon	{Function}	Function to run on an item if filter is true
foff	{Function}	Function to run on an item if filter is false
pre	{Function}	Function to run before the filter runs
post	{Function}	Function to run after the filter runs

changeMapType(mapType)

Change the default map type

Parameters (optional)
mapType	{String\|Object}	New map type If string, looks up in TimeMap.mapTypes.

Defined in:: manipulation.js

changeTimeIntervals(intervals)

Change the intervals on the timeline.

Parameters (optional)
intervals	{String\|Array}	New intervals. If string, looks up in TimeMap.intervals.

Defined in:: manipulation.js

clear()

Delete all datasets, clearing them from map and timeline. Note that this is more efficient than calling clear() on each dataset.

Defined in:: manipulation.js

createDataset(id, options) :{TimeMapDataset}

Create an empty dataset object and add it to the timemap

Parameters (optional)
id	{String}	The id of the dataset
options	{Object}	A container for optional arguments for dataset constructor - see the options passed to TimeMapDataset

Returns:: {TimeMapDataset} The new dataset object

deleteDataset(id)

Delete one dataset, clearing it from map and timeline

Parameters (optional)
id	{String}	Id of dataset to delete

Defined in:: manipulation.js

each(f)

Run a function on each dataset in the timemap. This is the preferred iteration method, as it allows for future iterator options.

Parameters (optional)
f	{Function}	The function to run, taking one dataset as an argument

eachItem(f)

Run a function on each item in each dataset in the timemap.

Parameters (optional)
f	{Function}	The function to run, taking one item as an argument

filter(fid)

Update items, hiding or showing according to filters

Parameters (optional)
fid	{String}	Filter chain to update on

getItems() :{TimeMapItem[]}

Get all items from all datasets.

Returns:: {TimeMapItem[]} Array of all items

getState() :{Object}

Get a configuration object of state variables

Returns:: {Object} Object with state config settings
Defined in:: state.js

getStateParamString() :{String}

Get current state parameters serialized as a hash string

Returns:: {String} State parameters serialized as a hash string
Defined in:: state.js

getStateUrl() :{String}

Get URL with current state parameters in hash

Returns:: {String} URL with state parameters
Defined in:: state.js

hideDataset(id)

Hides placemarks for a given dataset

Parameters (optional)
id	{String}	The id of the dataset to hide

Defined in:: manipulation.js

hideDatasets()

Hides all the datasets on the map

Defined in:: manipulation.js

initMap()

Initialize the map.

initState()

Initialize state tracking based on URL. Note: continuous tracking will only work on browsers that support the "onhashchange" event.

Defined in:: state.js

initTimeline(bands)

Initialize the timeline - this must happen separately to allow full control of timeline properties.

Parameters (optional)
bands	{BandInfo Array}	Array of band information objects for timeline

makeOptionData()

Make a cleaned up object for the TimeMap options

Defined in:: export.js

parseDate(s) :{Date}

Parse a date in the context of the timeline. Uses the standard parser (TimeMapDataset.hybridParser) but accepts "now", "earliest", "latest", "first", and "last" (referring to loaded events)

Parameters (optional)
s	{String\|Date}	String (or date) to parse

Returns:: {Date} Parsed date

refreshTimeline()

Refresh the timeline, maintaining the current date

Defined in:: manipulation.js

removeFilter(fid, f)

Remove a function from a filter chain

Parameters (optional)
fid	{String}	Id of the filter chain
f	{Function}	The function to remove

removeFilterChain(fid)

Remove a filter chain

Parameters (optional)
fid	{String}	Id of the filter chain

scrollToDate(d, lazyLayout)

Scroll the timeline to a given date. If lazyLayout is specified, this function will also call timeline.layout(), but only if it won't be called by the onScroll listener. This involves a certain amount of reverse engineering, and may not be future-proof.

Parameters (optional)
d	{String\|Date}	Date to scroll to (either a date object, a date string, or one of the strings accepted by TimeMap#parseDate)
lazyLayout	{Boolean}	Whether to call timeline.layout() if not required by the scroll.

setState(state)

Set the timemap state with a set of configuration options.

Parameters (optional)
state	{Object}	Object with state config settings

Defined in:: state.js

setStateFromUrl()

Set the timemap state with parameters in the URL

Defined in:: state.js

showDataset(id)

Shows placemarks for a given dataset

Parameters (optional)
id	{String}	The id of the dataset to hide

Defined in:: manipulation.js

showDatasets()

Shows all the datasets on the map

Defined in:: manipulation.js

toJSON()

Clean up TimeMap into a nice object for serialization This is called automatically by the JSON.stringify() function