TimeSliderViewModel | API Reference | ArcGIS Maps SDK for JavaScript 4.31

Provides the logic for the TimeSlider widget.

See also

Example

// Add a TimeSlider widget to the top left corner of the view.
const timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  viewModel: {
    view: view,
    mode: "instant",
    fullTimeExtent: {
      start: new Date(2000, 0, 1),
      end: new Date(2010, 0, 1)
    },
    timeExtent: {
      start: new Date(2000, 0, 1),
      end: new Date(2000, 0, 1)
    }
  }
});
view.ui.add(timeSlider, "top-left");

Constructors

TimeSliderViewModel Constructor new TimeSliderViewModel(properties)

Parameter

properties Object

optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Show inherited properties

Hide inherited properties

Type	Summary	Class
Collection<action>	Defines actions that will appear in a menu when the user clicks the ellipsis button in the widget.	TimeSliderViewModel
String	The name of the class.	Accessor
Date []	Defined specific locations on the timeline that the handles will snap to when manipulated.	TimeSliderViewModel
TimeExtent	The temporal extent of the entire slider.	TimeSliderViewModel
Boolean	If animating, the time indicator(s) will restart if they reach the edge.	TimeSliderViewModel
String	The time slider mode.	TimeSliderViewModel
Number	The time (in milliseconds) between animation steps.	TimeSliderViewModel
String	The view model's state.	TimeSliderViewModel
StopsByDates\|StopsByCount\|StopsByInterval	Defines specific locations on the time slider where thumbs will snap to when manipulated.	TimeSliderViewModel
TimeExtent	The current time extent of the time slider.	TimeSliderViewModel
MapView\|SceneView	A reference to the MapView or SceneView.	TimeSliderViewModel

Property Details

actions Property actions Collection<action>autocast Autocasts from Object [] Since: ArcGIS Maps SDK for JavaScript 4.21 TimeSliderViewModel since 4.12, actions added at 4.21.

Defines actions that will appear in a menu when the user clicks the ellipsis button timeSlider-actions-menu in the widget. The ellipsis button will not display if this property is null or if the collection is empty. Each action is defined with a unique id, a title, and an icon.

The trigger-action event fires each time an action in the menu is clicked. This event can be used to execute custom code such as setting the timeExtent to a specific date or copying the timeExtent to the browser's clipboard.

Example

// Create a TimeSlider with two actions to snap the thumb to two specific time extents.
const timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  viewModel: {
    fullTimeExtent: {
      start: new Date(2011, 0, 1),
      end: new Date(2012, 0, 1)
    },
    mode: "instant",
    actions: [
      {
        id: "quake",
        icon: "exclamation-mark-triangle",
        title: "Jump to Earthquake"
      },
      {
        id: "quake-plus-one-month",
        icon: "organization",
        title: "One month later"
      }
    ]
  }
});
timeSlider1.on("trigger-action", (event) => {
  const quake = new Date(Date.UTC(2011, 3, 11, 8, 16, 12));
  const oneMonthLater = new Date(quake.getTime()).setMonth(quake.getMonth() + 1);
  switch(event.action.id) {
    case "quake":
      timeSlider1.timeExtent = {
        start: quake,
        end: quake
      };
      break;
    case "quake-plus-one-month":
      timeSlider1.timeExtent = {
        start: oneMonthLater,
        end: oneMonthLater
      };
      break;
  }
});

declaredClass Inherited Property declaredClass Stringreadonly Inherited from Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

effectiveStops Property effectiveStops Date[]readonly

Defined specific locations on the timeline that the handles will snap to when manipulated.

Default Value:null

Example

// Add yearly stops starting from the beginning of 2001.
let timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  viewModel: {
    fullTimeExtent: {
      start: new Date(2000, 5, 1),
      end: new Date(2010, 0, 1)
    },
    stops: {
      interval: {
        value: 1,
        unit: "years"
      }
    },
   timeExtent: {
     start: new Date(2001, 0, 1),
     end: new Date(2010, 0, 1)
   }
  }
});
timeSlider.viewModel.effectiveStops.forEach((stop) => {
  console.log(stop);
});

fullTimeExtent Property fullTimeExtent TimeExtentautocast

The temporal extent of the entire slider. It defines the entire time period within which you can visualize your time aware data using the time slider widget.

Example

// Create a new TimeSlider
let timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  viewModel: {
    view: view
  }
});

// wait for the time-aware layer to load
layer.when(() => {
  // set up time slider properties based on layer timeInfo
  timeSlider.fullTimeExtent = layer.timeInfo.fullTimeExtent;
  timeSlider.stops = {
    interval: layer.timeInfo.interval
    timeExtent: timeSlider.fullTimeExtent
  };
});

loop Property loop Boolean

If animating, the time indicator(s) will restart if they reach the edge.

Default Value:false

Example

// Start a time slider animation that advances every second and restarts when it reaches the end.
let timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  viewModel: {
    loop: true,
    playRate: 1000
  }
});
timeSlider.viewModel.play();

mode Property mode String

The time slider mode. This property is used for defining if the temporal data will be displayed cumulatively up to a point in time, a single instant in time, or within a time range. See the following table for possible values.

Possible Values	Description	Example
instant	The slider will show temporal data that falls on a single instance in time. Set the timeExtent property's `start` and `end` dates to same date: `{start: sameDate, end: sameDate}`
time-window	The slider will show temporal data that falls within a given time range. This is the default. Set timeExtent property's `start` and `date` properties to desired dates.
cumulative-from-start	Similar to `time-window` with the start time is always pinned to the start of the slider. Set the timeExtent property's `start` date to `null` and set `end` date to a desired date: `{start: null, end: date}`
cumulative-from-end	Also, similar to the `time-window` with the end time pinned to the end of the slider. Set the timeExtent property's `start` date to a desired date and set `end` date to `null`: `{start: date, end: null}`

Possible Values:"instant" |"time-window" |"cumulative-from-start" |"cumulative-from-end"

Default Value:"time-window"

Example

// Create a single thumbed time slider that includes all historic content.
let timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  viewModel: {
    view: view,
    mode: "cumulative-from-start",
    fullTimeExtent: {
      start: new Date(2000, 0, 1),
      end: new Date(2010, 0, 1)
    },
    timeExtent: {
      start: null,
      end: new Date(2001, 0, 1)
    }
  }
});

playRate Property playRate Number

The time (in milliseconds) between animation steps.

When a View is associated with a TimeSlider and the TimeSlider is playing, the playback will pause before advancing if the View is still updating. For example, if the playRate is set to 1,000 (one second) and the View takes 1.5 seconds to render then the TimeSlider thumb(s) will advance every 1.5 seconds rather than every second.

Default Value:1000

Example

// Start a time slider animation that advances
// ten times a second and stops when it reaches the end.
timeSlider.set({
  loop: false,
  playRate: 100
});
timeSlider.play();

state Property state Stringreadonly

The view model's state.

Value	Description
disabled	Widget is not ready yet.
ready	Ready for time navigation.
playing	Time is playing in the navigator.

Possible Values:"disabled" |"ready" |"playing"

Default Value:"disabled"

Example

// Display the current state of the view model.
switch (timeSlider.viewModel.state) {
  case "disabled":
    console.log("The view is not ready or some property are not set.");
    break;
  case "ready":
    console.log("The time slider is ready for use.");
    break;
  case "playing":
    console.log("The time slider is currently animating.");
    break;
}

stops Property stops StopsByDates |StopsByCount |StopsByIntervalautocast Autocasts from Object

Defines specific locations on the time slider where thumbs will snap to when manipulated. If unspecified, ten evenly spaced stops will be added.

For continuous sliding set stops to null.

timeSlider.viewModel.stops = null;

To define regularly spaced stops, parse an object with interval and timeExtent properties with types TimeInterval and TimeExtent respectively. The timeExtent property is optional and used to confine stops to a certain date range. This property is useful to commence stops on a specific day or the week or month. If a stop definition by interval results in excess of 10,000 stops then the view model will default to ten evenly spaced stops.

// Add yearly intervals starting from the beginning of the TimeSlider.
timeSlider.viewModel.stops = {
  interval: {
    value: 1,
    unit: "years"
  }
};

Rather than regular time intervals the TimeSlider can be divided into evenly spaced stops. As with the previous method, divisions can be confined to a specific date range using the optional timeExtent property.

// Add stops at 15 evenly spaced intervals.
timeSlider.viewModel.stops = {
  count: 15
};

For irregular spaced stops simply assign an array of dates as demonstrated below.

// Add nine irregular stops.
timeSlider.viewModel.stops = {
  dates: [
    new Date(2000, 0, 1), new Date(2001, 3, 8), new Date(2002, 0, 10),
    new Date(2003, 12, 8), new Date(2004, 2, 19), new Date(2005, 7, 5),
    new Date(2006, 9, 11), new Date(2007, 11, 21), new Date(2008, 1, 10)
  ]
};

Lastly, to constrain or offset division by count or interval use the optional timeExtent property.

// Add yearly stops from Christmas 2019 to Christmas 2029 only
timeSlider.viewModel.stops = {
  interval: {
    value: 1,
    unit: "years"
  },
  timeExtent: {
    start: new Date(2019, 11, 25),
    end: new Date(2029, 11, 25)
  }
};

// Likewise, add stops that represent quarters of 2019 only.
timeSlider.viewModel.stops = {
  count: 4,
  timeExtent: {
    start: new Date(2019, 0, 1),
    end: new Date(2020, 0, 1)
  }
};

Default Value:{ count : 10 }

timeExtent Property timeExtent TimeExtent

The current time extent of the time slider. This property can be watched for updates and used to update the time extent property in queries and/or the layer filters and effects. The following table shows the timeExtent values returned for each mode.

Mode	The timeExtent value
`time-window`	`{start: startDate, end: endDate}`
`instant`	`{start: sameDate, end: sameDate}`
`cumulative-from-start`	`{start: null, end: endDate}`
`cumulative-from-end`	`{start: startDate, end: null}`

Default Value:null

Example

// Display the time extent to the console whenever it changes.
const timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  mode: "time-window",
  fullTimeExtent: {
    start: new Date(2019, 2, 3),
    end: new Date(2019, 2, 5)
  },
  timeExtent: {
    start: new Date(2019, 2, 1),
    end: new Date(2019, 2, 28)
  }
});

reactiveUtils.watch(
  () => timeSlider.timeExtent,
  (timeExtent) => {
    console.log("Time extent now starts at", timeExtent.start, "and finishes at:", timeExtent.end);
  }
);

view Property view MapView |SceneView

A reference to the MapView or SceneView. If this property is set, the TimeSlider widget will update the view's timeExtent property whenever the time slider is manipulated or updated programmatically. This property will affect any time-aware layer in the view.

Example

// Create and then add a TimeSlider widget and then listen to changes in the View's time extent.
const timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  viewModel: {
    view: view,
    mode: "instant",
    fullTimeExtent: {
      start: new Date(2000, 0, 1),
      end: new Date(2010, 0, 1)
    },
    timeExtent: {
      start: null,
      end: new Date(2000, 0, 1)
    }
  }
});
view.ui.add(timeSlider, "top-left");

reactiveUtils.watch(
  () => view.timeExtent,
  (timeExtent) => {
    console.log("New view time is: " + timeExtent.start);
  }
);

Method Overview

Show inherited methods

Hide inherited methods

Return Type	Summary	Class
	Adds one or more handles which are to be tied to the lifecycle of the object.	Accessor
Promise<Object>	Extracts time slider settings from a WebMap if the webmap contains a time slider widget definition.	TimeSliderViewModel
Boolean	Returns true if a named group of handles exist.	Accessor
	Incrementally moves the time extent forward one stop	TimeSliderViewModel
	Initiates the time slider's temporal playback.	TimeSliderViewModel
	Incrementally moves the time extent back one stop.	TimeSliderViewModel
	Removes a group of handles owned by the object.	Accessor
	Stops the time slider's temporal playback.	TimeSliderViewModel
	Updates the time slider widget definition in the provided WebMap or WebScene.	TimeSliderViewModel

Method Details

addHandles Inherited Method addHandles(handleOrHandles, groupKey) Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, addHandles added at 4.25.

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();

Parameters

handleOrHandles WatchHandle|WatchHandle []

Handles marked for removal once the object is destroyed.

groupKey *

optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

getPropertiesFromWebMap Method getPropertiesFromWebMap(webMap, signal){Promise<Object>}static Since: ArcGIS Maps SDK for JavaScript 4.22 TimeSliderViewModel since 4.12, getPropertiesFromWebMap added at 4.22. Deprecated since 4.29. Use getTimeSliderSettingsFromWebDocument instead.

Extracts time slider settings from a WebMap if the webmap contains a time slider widget definition. Returns an object with properties that can be used to configure the TimeSlider or TimeSliderViewModel. If a webmap does not contain a time slider definition then null is returned.

Parameters

webMap WebMap

An instance of a webmap to extract time slider settings from.

signal AbortSignal

optional

Signal object that can be used to abort the asynchronous task.

Returns

Type Description

Promise<Object>

When resolved, returns an object with the following properties.

Property	Type	Description
fullTimeExtent	TimeExtent	The temporal extent of the entire slider.
loop	Boolean	When `true`, the time slider will play its animation in a loop.
mode	"instant" \| "time-window" \| "cumulative-from-start" \| "cumulative-from-end"	The time slider mode.
playRate	Number	The time (in milliseconds) between animation steps.
stops	StopsByDates \| StopsByCount \| StopsByInterval	Defines specific locations on the time slider where thumbs will snap to when manipulated.
timeExtent	TimeExtent	The current time extent of the time slider.

See also

Sample - Time-enabled bookmarks

Example

// Import and apply time slider settings stored in a webmap.
const map = new WebMap({
  portalItem: {
    id: "your-webmap-id",
  }
});

TimeSliderViewModel.getPropertiesFromWebMap(map).then((timeSliderSettings) => {
  const timeSliderViewModel = new TimeSliderViewModel({
    ...timeSliderSettings,
    view
  });
});

hasHandles Inherited Method hasHandles(groupKey){Boolean} Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, hasHandles added at 4.25.

Returns true if a named group of handles exist.

Parameter

groupKey *

optional

A group key.

Returns

Type	Description
Boolean	Returns `true` if a named group of handles exist.

Example

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

next Method next()

Incrementally moves the time extent forward one stop

Example

// Advance the slider's time extent.
const timeSlider = new TimeSlider({
  container: "timeSliderDiv",
  viewModel: {
    mode: "instant",
    fullTimeExtent: {
      start: new Date(2000, 0, 1),
      end: new Date(2010, 0, 1)
    },
    timeExtent: {
      start: new Date(2000, 0, 1),
      end: new Date(2000, 0, 1)
    }
  }
});
timeSlider.viewModel.next();

play Method play()

Initiates the time slider's temporal playback.

Example

// Start a TimeSlider animation if not already playing.
if (timeSlider.viewModel.state === "ready") {
  timeSlider.viewModel.play();
}

previous Method previous()

Incrementally moves the time extent back one stop.

Example

timeSlider.viewModel.previous();

removeHandles Inherited Method removeHandles(groupKey) Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, removeHandles added at 4.25.

Removes a group of handles owned by the object.

Parameter

groupKey *

optional

A group key or an array or collection of group keys to remove.

Example

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

stop Method stop()

Stops the time slider's temporal playback.

Example

// Stop the current TimeSlider animation.
if (timeSlider.viewModel.state === "playing") {
  timeSlider.viewModel.stop();
}

updateWebDocument Method updateWebDocument(document) Since: ArcGIS Maps SDK for JavaScript 4.18 TimeSliderViewModel since 4.12, updateWebDocument added at 4.18.

Updates the time slider widget definition in the provided WebMap or WebScene.

Parameter

document WebMap|WebScene

The webmap or webscene to be updated.

Example

// Load a webmap containing a timeslider widget into a MapView. Once loaded, advance the current time
// extent by one stop and then update the original webmap.

const webmap = new WebMap({
  portalItem: {
    id: "acea555a4b6f412dae98994bcfdbc002"
  }
});

const view = new MapView({
  container: "viewDiv",
  map: webmap
});
await view.when();

const timeSlider = new TimeSlider({
  view
});
// Advance to thumb to next time extent
timeSlider.next();
timeSlider.updateWebDocument(webmap);
webmap.save();

Type Definitions

action Type Definition action Object

Definition of an action that can be assigned to the actions property on the TimeSlider or the TimeSliderViewModel. It is displayed in a menu when the user clicks the ellipsis button timeSlider-actions-menu on the TimeSlider widget.

Properties: icon String

The name of the icon to display. The value of this property must match the icon name from Calcite UI Icons.

id String

Unique identifier of the action.

title String

The title of the action that will be displayed in the menu.

Event Overview

Name	Type	Summary	Class
	{action: action}	Fires when a user clicks on an action in the actions menu.	TimeSliderViewModel

Event Details

trigger-action Event trigger-action Since: ArcGIS Maps SDK for JavaScript 4.21 TimeSliderViewModel since 4.12, trigger-action added at 4.21.

Fires when a user clicks on an action in the actions menu.

Property

action action

The action that was clicked.

See also

TimeSlider.actions

Example

// Add an action to reset the time extent to the full time extent.
timeSlider.actions.add({
  id: "full-extent",
  icon: "content-full",
  title: "Full Extent"
});
timeSlider.on("trigger-action", (event) => {
  if (event.action.id === "full-extent") {
    timeSlider.timeExtent = timeSlider.fullTimeExtent;
  }
});