d3.Timeslider

d3.Timeslider is a time slider based on the D3.js javascript library. It is written in CoffeeScript and Less

The software is licensed under a MIT compatible license, for more information see License.

For a list of recent changes, please see the Changelog.

Usage

Include the JavaScript and CSS files (and D3.js as D3.Timeslider depends on it) and then instantiate a new slider like in the following snippet.

You can download the latest version of D3 directly from d3js.org/d3.v3.zip

If you want to display datasets loaded from an EOWCS server, you also need to include libcoverage.js.

Options

domain - { start: <Date>, end: <Date> }

The maximum domain of the timeslider. When constrain is set, it is not possible to zoom/pan outside of this domain.

brush - { start: <Date>, end: <Date> }

The initial selection.

display - { start: <Date>, end: <Date> }

The initially displayed interval. This defaults to the domain.

ticksize - Number

The height of the displayed ranges or the diameter of the displayed dots.

debounce - Number

The time (in milliseconds) to wait between accessing the sources fetch function.

brushTooltip - boolean

Whether or not to display the brush tooltips. Defaults to false.

tooltipFormatter - function

This function is invoked when a tooltip is to be displayed for a record. It is passed the record, an Array in the following form: start, end, and params. By default, a function is used that displays either the id or name property (in that order).

When the function returns a falsy value, then no tooltip is displayed.

binTooltipFormatter - function

This function is invoked when a tooltip is to be displayed for a histogram bin. It is passed the bin - an array of records (again an array of [start, end, params]). By default, the tooltipFormatter is invoked for each record and joined by a <br>.

alternativeBrush - boolean

When set to true, the selection brush is displayed below other parts of timeslider and looks like a thin strip with circle handles on sides. Defaults to false.

constrain - boolean

When set, the viewable interval is constrained to the domain.

selectionLimit - String|Number

When set, this limits the maximum interval allowed to brush. This can either be a number (number of seconds) or a ISO8601 duration.

displayLimit - String|Number

When set, this limits the maximum interval allowed to display. This can either be a number (number of seconds) or a ISO8601 duration.

recordFilter - function

A function to be called for each record with the following parameters: record (an array: start, end, and params) and the dataset. When the function returns a truthy value, the record is displayed whole, and hollow otherwise.

datasets - [ {...}, ]

An array of dataset definitions (objects) with the following layout

• id: The ID of the dataset. This is used in events and callbacks

• color: The color to display the dataset. Anything possible for CSS works here

• noBorder: Boolean option to disable individual record/bucket borders.

• lineplot: Whether this dataset will be displayed as a line

• histogramThreshold: Sets the threshold, when this dataset will be displayed in a quantized manner.

• histogramBinCount: Sets the number of bins to use when drawing histograms.

• sourceParams: Anything you want to pass to the source function.

• records: The records for this dataset. When the records are set this way, the dataset is static, and does not change.

• source: Either a function or an object with a fetch method. This function/method is passed the following arguments: start, end, sourceParams and a callback. The callback is expected to be called with an array of either:

  • single Dates
  • an Array of
    • one Date and parameters (or a single value for lineplots)
    • two Dates
    • two Dates and parameters

  The parameters are used for the recordFilter and to display the tooltip on the mouseover: either the id or name properties are used when available.

• cacheRecords: Use an internal cache to only request intervals that have not been requested before.

• cacheIdField: Field to check the equality of records. This is necessary when two intervals of records need to be merged. When not set, then the time stamps of the records are used.

• cluster: Use a clustering algorithm to unify records that are so close to each other that they cannot not be distinguished.

Public API

hide / show

Hide/show the timeslider (using the CSS display property).

domain - start, end

Sets the domain to the new start/end. This method redraws the timeslider.

select - start, end

Sets the selection of the timeslider.

center - start, end

Immediatly show the given interval. Redraws.

zoom - start, end

Zoom to the given interval over a small amount of time. Redraws in the transition.

addDataset - definition

Adds a new dataset by definition. See the initial options for the layout. This starts the reloading of the dataset.

removeDataset - id

Remove a dataset by its ID. Redraws.

hasDataset - id

Returns true when the dataset with the id exists.

reset

Reset the view to the domain using zoom.

setBrushTooltip - boolean

Enable/disable the brush tooltip.

setBrushTooltipOffset

Set the pixel offsets of the brush tooltips.

setRecordFilter - function

Set the recordFilter. See the options for details. Redraws.

setTooltipFormatter - function

Sets the tooltip formatting function.

setBinTooltipFormatter - function

Sets the tooltip formatter for histogram bins.

Events raised

The timeslider raises several custom events. All arguments are stored in the events detail property.

selectionChanged

This event is emitted when the user has finished brushing a new selection. The details are:

• start: the new start time of the selection
• end: the new end time of the selection

displayChanged

This event is emitted after zooming or panning the timeslider. The details are:

• start: the new start time of the viewable interval
• end: the new end time of the viewable interval

recordMouseover / recordMouseout / recordClicked

These events are raised when a record is hovered, stopped hovering or clicked. The details always include:

• dataset: the dataset ID
• start: the start time of the record
• end: the end time of the record
• params: optional record parameters when available

clusterMouseover / clusterMouseout / clusterClicked

These events are raised when clustered records are hovered, stopped being hovering or clicked. The details always include:

• dataset: the dataset ID
• start: the start time of the cluster of records
• end: the end time of the cluster of records
• records: the array of records in that cluster

binMouseover / binMouseout / binClicked

These events are raised when a bin of a histogram dataset is hovered, stopped hovering or clicked. The details always include:

• dataset: the dataset ID
• start: the start time of the histogram bin
• end: the end time of the histogram bin
• bin: the array of records in that bin

Available sources

EO-WCS - EOWCSSource

This source uses libcoverage.js to send DescribeEOCoverageSet requests to the specified EO-WCS server. The result is parsed for all entailed coverages and their respective start/end times. The record params include the coverages EOID which is used as the id for display in the tooltip and the events.

This source allows the following parameters:

• url: The URL of the WCS server
• eoid: The EO-ID of the collection or coverage to perform the request on

EOxServer WPS - EOxServerWPSSource

This source is specialized to access the getTimeData Process, that ships with EOxServer. The response format is a CSV file, which is parsed. Sources of this type accept the following parameters:

• url: The URL of the EOxServer WPS instance.
• eoid: The ID of the collection to query.

WMS - WMSSource

The WMSSource fetches the WMS Capabilities of a server to parse the time dimension of a specific layer to produce the time-marks. Capabilities responses are globally cached. The source accepts the following parameters:

• url: The URL of the WMS endpoint.
• layer: The layer name.

This source is somewhat limited by the underlying protocol and is thus not able to subset the records on a request basis and cannot provide additional metadata (such as record ID) to display as a tooltip or provide in timeslider events.

Example

An example on how to use it is provided below.

<!-- libcoverage.js-->
<script src="dependencies/libcoverage.js/libcoverage.min.js" charset="utf-8"></script>

<!-- TimeSlider -->
<script src="build/d3.timeslider.js"></script>
<script src="build/d3.timeslider.plugins.js"></script>
<link href="build/d3.timeslider.css" rel="stylesheet" type="text/css" media="all" />
<script>
  window.addEventListener('load', function() {
    // Initialize the TimeSlider
    slider = new TimeSlider(document.getElementById('d3_timeslider'), {
      debounce: 50,
      domain: {
        start: new Date("2012-01-01T00:00:00Z"),
        end: new Date("2013-01-01T00:00:00Z"),
      },
      brush: {
        start: new Date("2012-01-05T00:00:00Z"),
        end: new Date("2012-01-10T00:00:00Z")
      },
      datasets: [
        {
          id: 'img2012',
          color: 'red',
          data: function(start, end, callback) {
            return callback('img2012', [
              [ new Date("2012-01-01T12:00:00Z"), new Date("2012-01-01T16:00:00Z") ],
              [ new Date("2012-01-02T12:00:00Z"), new Date("2012-01-02T16:00:00Z") ],
              new Date("2012-01-04T00:00:00Z"),
              new Date("2012-01-05T00:00:00Z"),
              [ new Date("2012-01-06T12:00:00Z"), new Date("2012-01-26T16:00:00Z") ],
            ]);
          }
        }
      ]
    });

    // Register a callback for changing the selected time period
    document.getElementById('d3_timeslider').addEventListener('selectionChanged', function(e){
      console.log("Custom event handler on the time slider");
      console.log(e.detail);
    });

    // Change the TimeSlider domain, or the selected interval, then reset the
    // TimeSlider to it's initial state
    slider.domain(new Date("2011-01-01T00:00:00Z"),  new Date("2013-01-01T00:00:00Z"));
    slider.select(new Date("2011-02-01T00:00:00Z"),  new Date("2013-02-08T00:00:00Z"))
    slider.reset();

    // Add a new dataset and remove another one
    slider.addDataset({
      id: 'fsc',
      color: 'green'
      data: new TimeSlider.Plugin.EOWCS({ url: 'http://neso.cryoland.enveo.at/cryoland/ows', eoid: 'daily_FSC_PanEuropean_Optical', dataset: 'fsc' })
    });
    slider.addDataset({
      id: 'asar',
      color: 'purple',
      data: new TimeSlider.Plugin.WMS({ url: 'http://data.eox.at/instance01/ows', eoid: 'ASAR_IMM_L1_view', dataset: 'asar' })
    })
    slider.removeDataset('img2012');
)
  }, false);
</script>

Development

Install development dependencies, and start grunt via the following two commands.

npm install
grunt watch

You can then open the preview page and any changes to the CoffeeScript and Less files will be automatically compiled and reloaded in the browser.

To lint the CoffeeScript source run the following command.

grunt lint