Timeline Layer - HuTime API Manual

1. Overview

A timeline (e.g., chronological table) is displayed with a timeline layer (HuTime.TLineLayer). The timeline layer, a class derived from the Layer class, can basically be used like other layers, for example, when you put it on a panel. Source data for a timeline can be separately given in a different form, such as a CSV file. You can use a record set for the timeline (HuTime.TLineRecordset) to specify which items (columns) in the source data correspond to the start and end times, as well as which items are displayed.

2. Source Data for a Timeline

We recommend for easier handling that you use a file whose first line is the title row for the csv (comma separated value) file or tsv (tab separated value) file. Here is an example of source data, which contains the list of typhoons in 2015 (the first several rows only):

Number,From,To,Name,PeakWS,PeakAP,Category
1,2015-01-14,2015-01-19,Mekkhala,110,975,1
2,2015-02-08,2015-02-11,Higos,165,940,4
3,2015-03-11,2015-03-17,Bavi,85,990,0
4,2015-03-28,2015-04-05,Maysak,195,910,5
5,2015-04-04,2015-04-04,Haishen,65,998,0

3. Creating a Layer Object

You specify the URL of the source data for the chart when creating an object. The height, as well as the top and bottom margins, of the layer can be specified similarly to other layers.

Constructor

HuTime.TLineLayer([recordset [, vBreadth [, vMarginTop [, vMarginBottom]]]])

recordset: Type: HuTime.TLineRecordset; The record set that contains the source data. You can access the record set specified in the constructor as the first array element in the recordsets property (layer.recordsets[0]). If a record set is not specified, you need to add a record set separately using the appendRecordset method.
vBreadth: Type: Number; The height of the layer (in pixels).
vMarginTop: Type: Number; The size of the top margin of the layer (in pixels).
vMarginBottom: Type: Number; The size of the bottom margin of the layer (in pixels).

Overview of the Record Set

The record set for the timeline is used.

HuTime.CalendarTLineRecordset(source, tBegin, tEnd, label [, calendarId, [, rangeStyle [, labelStyle]]])

source: Type: String or HuTime.StreamReaderBase; When a string is entered, it is interpreted as the URL of the source data for the record set, a new StreamReader object is created, and then the data is read.
tBegin: Type: String or number; The item name or the column number of the start date and time in the record.
tEnd: Type: String or number; The item name or the column number of the end date and time in the record.
label: Type: String or number; The item name or the column number for the strings that are displayed in the timeline, in the record.
calendarId: Type: String; The calendar ID of the start and end dates and times. If omitted, it is set to the Gregorian calendar.
rangeStyle: Type: HuTime.FigureStyle; The format of the band that shows the record duration on the timeline. If omitted, it is formatted with the default for the timeline layer.
labelStyle: Type: HuTime.StringStyle; The format of the record label on the timeline. If omitted, it is formatted with the default for the timeline layer.

4. Adding a Layer to the Panel and Displaying

Just like other layers, you can add a timeline layer to a panel using the appendLayer method of a Panel object. The object is drawn according to the sequence of the redraw method, but if the source data has not been read completely, it takes time to show the object.

An example of displaying a timeline layer (see the sample code below). The source data is the list of typhoons in 2015, which is shown in "2. Source Data for a Timeline."

Sample code (click here for a running example):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
    var ht = new HuTime();
    var pnls = new HuTime.PanelCollection(200, 400);
    ht.appendPanelCollection(pnls, document.getElementById("timeline"));
    var pnl = new HuTime.TilePanel(200);
    pnls.appendPanel(pnl);

    var lyr = new HuTime.TLineLayer(
        new HuTime.CalendarTLineRecordset("Typhoon2015.csv", "From", "To", "Name"));
    pnl.appendLayer(lyr);

    ht.redraw(HuTime.timeToJd(2015, 1, 1), HuTime.timeToJd(2016, 1, 1));
</script>
</body>
</html>

5. Formatting

In a timeline, you can format the band for duration, and labels. A timeline can be formatted on a record-set basis. When a format value is passed to the constructor of a record set as an argument, it will be the default format of that record set. The following figure shows an example with some format set to the sample code in "4. Adding a Layer to the Panel and Displaying."

An example of formatting the timeline layer (see the sample code below). In the example above, the timeline of the sample code in "4. Adding a Layer to the Panel and Displaying” is formatted by passing arguments to the constructor of HuTime.CalendarTLineRecordset.

Sample code (click here for a running example). The null value is specified for the calendarId argument of the HuTime.CalendarTLineRecordset's constructor. A calendar scale layer (variable: scl) is also added.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
    var ht = new HuTime();
    var pnls = new HuTime.PanelCollection(200, 400);
    ht.appendPanelCollection(pnls, document.getElementById("timeline"));
    var pnl = new HuTime.TilePanel(200);
    pnls.appendPanel(pnl);

    var lyr = new HuTime.TLineLayer(
        new HuTime.CalendarTLineRecordset("Typhoon2015.csv", "From", "To", "Name", null,
            new HuTime.FigureStyle("lime"), new HuTime.StringStyle(20, "red")));
    pnl.appendLayer(lyr);

    var scl = new HuTime.CalendarScaleLayer(50, null, 0);
    pnl.appendLayer(scl);

    ht.redraw(HuTime.timeToJd(2015, 1, 1), HuTime.timeToJd(2016, 1, 1));
</script>
</body>
</html>

6. Displaying Multiple Data Sets

You can add multiple record sets to a timeline layer by using the appendRecordset property. When different record sets have different formats, a timeline can show the differences of record sets.

appendRecordset(recordset)

Adds the record set to a timeline layer.

recordset: Type: HuTime.TLineRecordset; The record set to be added.

An example of the timeline layer with multiple record sets added to it (see the sample code below). The Hurricane2015.csv file (the list of hurricanes in 2015) is added as new source data using the appendRecordset method, and the band for duration is formatted in light blue and the label in red.

Sample code (click here for a running example):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code (TLine Layer Style Setting)</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
    var ht = new HuTime();
    var pnls = new HuTime.PanelCollection(200, 400);
    ht.appendPanelCollection(pnls, document.getElementById("timeline"));
    var pnl = new HuTime.TilePanel(200);
    pnls.appendPanel(pnl);

    var lyr = new HuTime.TLineLayer(
        new HuTime.CalendarTLineRecordset("Typhoon2015.csv", "From", "To", "Name"));
    pnl.appendLayer(lyr);

    lyr.appendRecordset(
        new HuTime.CalendarTLineRecordset("Hurricane2015.csv", "From", "To", "Name", null,
            new HuTime.FigureStyle("cyan"), new HuTime.StringStyle(14, "red")));

    var scl = new HuTime.CalendarScaleLayer(50, null, 0);
    pnl.appendLayer(scl);

    ht.redraw(HuTime.timeToJd(2015, 1, 1), HuTime.timeToJd(2016, 1, 1));
</script>
</body>
</html>

7. Formatting Individual Records

To color-code data in a timeline based on a particular item in the same record set, set a color-coding function for the rangeStyle property of the record set object. A HuTime.TLineRecord object is passed to the set function as an argument, and return a HuTime.FigureStyle object based on its contents.

In the figure and sample code below, if the data item Category in the source data has a value of 4 or more, the record is displayed in yellow, and it has a value of 3 or less, the record is displayed in light blue. First, two formats (styleStrong and styleWeak) are defined. Next, a record set object is created additionally, and the settings for reading the data item Category are added to that record set. Finally, a processing for outputting the formats to the rangeStyle property of the created record set is described.

An example of formatting individual record (see the sample code below). Typhoons in category 4 or higher are displayed in yellow, and those in category 3 or lower in light blue.

Sample code (click here for a running example):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
    var ht = new HuTime();
    var pnls = new HuTime.PanelCollection(200, 400);
    ht.appendPanelCollection(pnls, document.getElementById("timeline"));
    var pnl = new HuTime.TilePanel(200);
    pnls.appendPanel(pnl);

    var styleStrong = new HuTime.FigureStyle("yellow");
    var styleWeak = new HuTime.FigureStyle("cyan");
    var recordset = new HuTime.CalendarTLineRecordset("Typhoon2015.csv", "From", "To", "Name");
    recordset.recordSettings.appendDataSetting(new HuTime.RecordDataSetting("Category"));
    recordset.rangeStyle = function(record) {
        if (!record.data["Category"])
            return defaultRecordStyle;
        if (record.data["Category"].text >= 4)
            return styleStrong;
        else
            return styleWeak;
    };

    var lyr = new HuTime.TLineLayer(recordset);
    pnl.appendLayer(lyr);

    var scl = new HuTime.CalendarScaleLayer(50, null, 0);
    pnl.appendLayer(scl);

    ht.redraw(HuTime.timeToJd(2015, 1, 1), HuTime.timeToJd(2016, 1, 1));
</script>
</body>
</html>

8. Events Handling for Records

The actions listed below on records on a timeline can be supplemented as an event on a timeline layer. The clicked record is stored in records of the event object as an array. When multiple overlapped records are displayed, the corresponding records are all stored in records. An event handler is added using addEventListener, just like other events.

Action	Event Type
Click	plotclick
Double-click	plotdblclick

In the example below, the recordClick function is added to the timeline layer as plotclick event handling. The recordClick function concatenates the labels of clicked records and displays the combined label in the pop-up window.

Sample code (click here for a running example):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code (TLine Layer Style Setting)</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
    var ht = new HuTime();
    var pnls = new HuTime.PanelCollection(200, 400);
    ht.appendPanelCollection(pnls, document.getElementById("timeline"));
    var pnl = new HuTime.TilePanel(200);
    pnls.appendPanel(pnl);

    var lyr = new HuTime.TLineLayer(
        new HuTime.CalendarTLineRecordset("Typhoon2015.csv", "From", "To", "Name"));
    lyr.addEventListener("plotclick", recordClick);
    pnl.appendLayer(lyr);

    var scl = new HuTime.CalendarScaleLayer(50, null, 0);
    pnl.appendLayer(scl);

    ht.redraw(HuTime.timeToJd(2015, 1, 1), HuTime.timeToJd(2016, 1, 1));

    function recordClick(ev) {
        var text = "";
        for (var i = 0; i < ev.records.length; ++i) {
            text += ev.records[i].record.data["Name"].text + " ";
        }
        alert(text);
    }
</script>
</body>
</html>

Back to the Contents of this Manual