Timeline

The Timeline widget displays time-based information (events, activities, etc.) for one or more entity instances along a timeline.

The Timeline widget is based on the KronoGraph library and accepts many of the same props. See the Timeline API and KronoGraph documentation for details.

Timeline MarkLogic setup

To display time-based information from /v1/search results in the Timeline widget, the content must be extracted and included in the search results. To do this, put an extract-document-data property in the query options of the application. In the example, the document content is shown under an extracted property. See Include document extracts in search results for details.

Timeline concepts

The Timeline widget displays event markers along a timeline based on the marker's datetime values. Each event is associated with an entity instance. Multiple events for an instance are placed along the same row in the timeline. A label for each entity is shown on the left-side of the timeline.

The set of events to include in the timeline is specified from the data source. The Timeline widget automatically sizes itself to display all the events on load. Labels are displayed for the different entity instances that have events currently shown. 

Example rendering

To change the timeline's range, click and drag along the timeline. Tablet or trackpad users can also use the spread and pinch gestures or commands.

Show time-based events from search results

The Timeline widget can map event information from a /v1/search response onto a timeline. The events for each result in the search response are displayed in a timeline row.

Example response

This example shows a /v1/search response payload. Each result in the response has an array of event information in an activities property. These events can be displayed on a timeline and associated with their entity instance (which in this case is a person).

{
    "snippet-format": "snippet",
    "total": 3,
    "start": 1,
    "page-length": 10,
    "selected": "include",
    "results": [
        {
            "index": 1,
            "uri": "/person/1001.json",
            "path": "fn:doc(\"/person/1001.json\")",
            "href": "/v1/documents?uri=%2Fperson%2F1001.json",
            "extracted": {
                "kind": "array",
                "content": [
                    {
                        "envelope": {
                            "entityType": "person",
                            "id": 1001,
                            "firstName": "Nerta",
                            "lastName": "Hallwood",
                            "title": "Marketing Manager",
                            "status": "active",
                            "activities": [
                                {
                                    "description": "Started at Fadeo",
                                    "ts": "2013-06-22"
                                },
                                {
                                    "description": "Promoted",
                                    "ts": "2019-08-15"
                                }
                            ]
                        }
                    }
                ]
            }
        },
        // more results...
    ],
    // more metadata...
}

Example React application

This React application includes the Timeline widget configured to display the example payload:

import { useContext } from "react";
import './App.css';
import { MarkLogicContext, SearchBox, Timeline } from "ml-fasttrack";
  
function App() {
  
  const context = useContext(MarkLogicContext);
 
  const TimelineConfig = {
    entityTypeConfig: {
      path: "extracted.content[0].envelope.entityType"
    },
    entities: [
      {
          entityType: 'person',
          path: 'extracted.content[0].envelope',
          label: 'lastName',
          eventPath: 'activities',
          items: [
              {
                  label: 'description',
                  timePath: 'ts'
              },           
          ],
          detailConfig: [
              {
                  label: 'First Name',
                  path: 'firstName'
              },
              {
                label: 'Last Name',
                path: 'lastName'
              },
          ]
      }
    ]
  }
 
  const TimelineSettings = {
    entityTypes: {
        default: {
            labelColor: 'white'
        },
        person: {
            labelColor: 'tomato'
        },
        organization: {
            labelColor: '#D4886A'
        }
    },
    eventTypes: {
            default: {
                showArrows: true,
            },
            "2013-06-22": {
                color: 'fuchsia'
            }
        }
    }
  
  const handleSearch = (params) => {
    context.setQtext(params?.q);
  }
  
  return (
    <div className="App">
      <div>
        <SearchBox onSearch={handleSearch}/>
      </div>
      <div>
          <div style={{height: '400px'}}>
          <Timeline
            data={context?.searchResponse?.results}
            config={TimelineConfig}
            theme={'light'}
            onTimelineClick={(event) => console.log('Timeline!', event)}
            TimelineProps={TimelineSettings}
          />
          </div>
      </div>
    </div>
  );
}
  
export default App;

Code explanation

In the example:

• A user executes a search using a FastTrack SearchBox widget and the search response is stored in the application context. Results from the search response are assigned to the Timeline widget's data prop. 

• The event data from the data prop is mapped using the config prop.

• The entityTypeConfig property in config specifies the path to the entity type in each result. In this example, "person" is the only entity type in the results.

• The entities array in config maps the timeline information from the data prop using one or more configuration objects. One object is used for each entity type. For details about the configuration objects, see the API.

• The TimelineProps prop can be used to specify styles for the entity and event information in the timeline. For details, see Styling Entities and Events, the Timeline API, and the KronoGraph documentation.

The Timeline widget supports event handlers corresponding to user interactions on the timeline. In the example, the onTimelineClick event handler responds to clicks on timeline events. For details about supported event handlers, see API.

Timeline example rendering

The Example React application renders this:

Showing time-based events from a document

Time-based information can be mapped from a /v1/documents result and displayed by the Timeline widget. The result shows events stored as an array of objects in an activities property. These events can be displayed on a timeline for that person.

Example response

This is an example response for a person document:

{
  "entityType": "person",
  "id": 1001,
  "firstName": "Nerta",
  "lastName": "Hallwood",
  "title": "Marketing Manager",
  "status": "active",
  "activities": [
    {
        "description": "Started at Katz",
        "ts": "2013-06-22T04:21:37Z"
    },
    {
        "description": "Transferred to Yodel",
        "ts": "2019-08-15T14:47:28Z"
    }
  ]
}

React application code

This is a React application with the Timeline widget configured to display the data from the response:

import { useContext, useEffect } from "react";
import './App.css';
import { MarkLogicContext, Timeline } from "ml-fasttrack";
  
function App() {
  
  const context = useContext(MarkLogicContext);
 
  useEffect(() => {
    context.getDocument('/person/1001.json');
  }, []);
 
  const TimelineConfig = {
      entityTypeConfig: {
        path: "data.entityType"
      },
      entities: [
        {
            entityType: 'person',
            path: 'data',
            label: 'firstName',
            eventPath: 'activities',
            items: [
                {
                    label: 'description',
                    timePath: 'ts'
                },           
            ]
        }
      ]
  }
  
  return (
    <div className="App">
      <div>
          <div style={{height: '240px'}}>
          <Timeline
            data={context?.documentResponse}
            config={TimelineConfig}
          />
          </div>
      </div>
    </div>
  );
}
  
export default App;

Code explanation

In the example  application:

• A useEffect React hook loads a document using the getDocument method in the application content (which makes a call to the /v1/documents endpoint). The document response is stored in the application context.

• The document response is assigned to the Timeline widget's data prop. The event data from the data prop is mapped using the config prop. 

• The entityTypeConfig property in config specifies the path to the entity type in the document response.

• The entities array in config allows the timeline information from the data prop to be mapped using a configuration object for the document. For details about the configuration object, see API.

• The TimelineProps prop specifies styles for the entity and event information in the timeline. For details, see Styling Entities and Events, the Timeline API, and the KronoGraph documentation.

Timeline example rendering

The Timeline widget configured with the example code renders this:

A row represents the events in the document.

Styling entities and events

Style entities and events in the timeline by adding a Timeline TimelineProps prop. The TimelineProps prop can be used to:

• change the color of the entity labels.

• change the color and width of the entity line.

• change the colors of the event markers.

• use icons with events.

Styling entities and events example code

The TimelineProps prop accepts an entityTypes property for specifying entity styles and an eventTypes property for specifying event styles. This code defines a TimelineSettings variable to use for the TimelineProps prop:

const TimelineSettings = {
    entityTypes: {
        Persons: {
          labelColor: "darkslategray",
          color: "purple",
          lineWidth: 6
        }
    },
    eventTypes: {
        default: {
            fontIcon: {
              fontFamily: "Font Awesome 5 Free",
              fontWeight: 900,
              text: "\uf101"
            }
        },
        "Started at Fadeo": {
            color: "orange"
        },
        Promoted: {
            color: "fuchsia"
 
        }
    }
}

React application code

This is sample React application code when the TimelineProps prop is added to the Timeline widget:

import '@fortawesome/fontawesome-free/css/fontawesome.css';
import '@fortawesome/fontawesome-free/css/all.css';
 
<Timeline
  data={context?.documentResponse}
  config={TimelineConfig}
  TimelineProps={TimelineSettings}
/>

Styling entities and events example rendering

Styling the entities and events using the TimelineProps prop described in Styling Entities and Events renders this:

For more information, see the KronoGraph documentation.

Configuring event popups

A popup window can be configured to open when an event in the timeline is clicked. The content that appears in the window is defined by adding a detailConfig array to the entity configuration object. 

Example popup code

This example shows a detailConfig array. The array defines a popup window that displays the first and last name of the person entity instance associated with the event:

const TimelineConfig = {
    entityTypeConfig: {
      path: "data.envelope.entityType"
    },
    entities: [
      {
          entityType: 'person',
          path: 'data.envelope',
          label: 'firstName',
          eventPath: 'activities',
          items: [
              {
                  label: 'description',
                  timePath: 'ts'
              },           
          ],
          detailConfig: [
              {
                  label: "First Name",
                  path: "firstName"
              },
              {
                  label: "Last Name",
                  path: "lastName"
              }
          ]
      }
    ]
}

Code explanation

For each detailConfig array element, the window displays a label followed by the value determined by a path configuration (which is relative to the parent path value). 

The popup window is based on the Kendo Window component. 

Style the window

The window can be styled by passing a WindowProps prop into the Timeline widget. This configuration object sets the window title, window height and width, and also makes the window draggable:

onst WindowConfig = {
  title: "Event Info",
  initialHeight: 150,
  initialWidth: 240,
  draggable: true
}

React application code

The React application code looks like this with the popup window configuration added to the WindowProps prop for the Timeline widget:

<Timeline
  data={context?.documentResponse}
  config={TimelineConfig}
  WindowProps={WindowConfig}
/>

Example rendering

Adding the popup window configuration information results in this window appearing when an event is clicked:

Timeline API

config API

TimelineProps API