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 :{Mapstraction} The Mapstraction object
	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
	addFilter(chainId, f) Add a function to a filter chain
	addFilterChain(chainId, fon, foff, pre, post, chain) 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(chainId) Update items, hiding or showing according to filters
	getItems() Get all items from all datasets.
	getNativeMap() Return the native map object (specific to the map provider)
	getSelected() Get the currently selected item
	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.
	parseDate(s) Parse a date in the context of the timeline.
	refreshTimeline() Refresh the timeline, maintaining the current date
	removeFilter(chainId, f) Remove a function from a filter chain
	removeFilterChain(chainId) Remove a filter chain
	scrollToDate(d, lazyLayout, animated) Scroll the timeline to a given date.
	setSelected(item) Save the currently selected item
	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

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	{LatLonPoint}	Point for map center Default: 0,0
options.mapZoom	{Number}	Initial map zoom level Default: 0
options.mapType	{String}	The maptype for the map (see TimeMap.mapTypes for options) Default: physical
options.mapFilter	{Function\|String}	How to hide/show map items depending on timeline state; options: keys in TimeMap.filters or function. Set to null or false for no filter. 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.centerOnItems	{Boolean}	Whether to center and zoom the map based on loaded item Default: true
options.eventIconPath	{String}	Path for directory holding event icons; if set at the TimeMap level, will override dataset and item defaults
options.checkResize	{Boolean}	Whether to update the timemap display when the window is resized. Necessary for fluid layouts, but might be better set to false for absolutely-sized timemaps to avoid extra processing Default: true
options.multipleInfoWindows	{Boolean}	Whether to allow multiple simultaneous info windows for map providers that allow this (Google v3, OpenLayers) Default: false
options[...]	{mixed}	Any of the options for TimeMapDataset, TimeMapItem, or 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. Either this or mapSelector is required.
config.timelineId	{String}	DOM id of the element to contain the timeline. Either this or timelineSelector is required.
config.mapSelector	{String}	jQuery selector for the element to contain the map. Either this or mapId is required.
config.timelineSelector	{String}	jQuery selector for the element to contain the timeline. Either this or timelineId is required.
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 Default: wk
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: earliest

Returns:: {TimeMap} The initialized TimeMap object

Field Details

chains :{Object}

Filter chains for this timemap

datasets :{Object}

Map of datasets

map :{Mapstraction}

The Mapstraction object

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

addFilter(chainId, f)

Add a function to a filter chain

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

addFilterChain(chainId, fon, foff, pre, post, chain)

Add a new filter chain

Parameters (optional)
chainId	{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
chain	{Function[]}	Optional initial filter chain

changeMapType(mapType)

Change the default map type

Parameters (optional)
mapType	{String}	The maptype for the map (see TimeMap.mapTypes for options)

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(chainId)

Update items, hiding or showing according to filters

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

getItems() :{TimeMapItem[]}

Get all items from all datasets.

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

getNativeMap() :{Object}

Return the native map object (specific to the map provider)

Returns:: {Object} The native map object (e.g. GMap2)

getSelected() :{TimeMapItem}

Get the currently selected item

Returns:: {TimeMapItem} Selected item

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

parseDate(s) :{Date}

Parse a date in the context of the timeline. Uses the standard parser (TimeMap.dateParsers.hybrid) 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(chainId, f)

Remove a function from a filter chain

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

removeFilterChain(chainId)

Remove a filter chain

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

scrollToDate(d, lazyLayout, animated)

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.
animated	{Boolean}	Whether to do an animated scroll, rather than a jump.

setSelected(item)

Save the currently selected item

Parameters (optional)
item	{TimeMapItem\|String}	Item to select, or undefined to clear selection

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