17.2. Using Timeline

Vaadin Timeline uses Vaadin containers as data sources for both the graphs and the events. There are, however, some requirements for the containers to make them compatible with the Vaadin Timeline.

The containers have to implement Container.Indexed for the Vaadin Timeline to be able to use them. This is because the Vaadin Timeline dynamically fetches the data from the server when needed. This way large data sets can be used without having to load all data to the client-side at once and it brings a huge performance increase.

Another requirement is that the container has one property of type java.util.Date (or a class that can be cast to it), which contains the timestamp when a data point or event occurred. This property has to be set by using the setGraphTimestampPropertyId() in Timeline. The default property ID timeline.PropertyId.TIMESTAMP is used if no timestamp-property ID has been set.

A graph container also needs to have a value property that defines the value of the data point. This value can be any numerical value. The value property can be set with setGraphValuePropertyId() in Timeline. The default property ID Timeline.PropertyId.VALUE is used if no value property is given.

Below is an example of how a graph container could be constructed:

// Construct a container which implements Container.Indexed       
IndexedContainer container = new IndexedContainer();

// Add the Timestamp property to the container
Object timestampProperty = "Our timestamp property";
container.addContainerProperty(timestampProperty,
                               java.util.Date.class, null);

// Add the value property
Object valueProperty = "Our value property";
container.addContainerProperty(valueProperty, Float.class, null);

// Our timeline
Timeline timeline = new Timeline();

// Add the container as a graph container
timeline.addGraphDataSource(container, timestampProperty,
                                       valueProperty);

The event and marker containers are similar. They both need the timestamp property which should be of type java.util.Date and the caption property which should be a string. The marker container additionally needs a value property which is displayed in the marker popup.

Below is an example on how a marker or event container can be constructed:

// Create the container
IndexedContainer container = new IndexedContainer();
        
// Add the timestamp property
container.addContainerProperty(Timeline.PropertyId.TIMESTAMP,
                               Date.class, null);
        
// Add the caption property
container.addContainerProperty(Timeline.PropertyId.CAPTION,
                              String.class, "");

// Add the marker specific value property.
// Not needed for a event containers.
container.addContainerProperty(Timeline.PropertyId.VALUE,
                               String.class, "");

// Create the timeline with the container as both the marker
// and event data source
Timeline timeline = new Timeline();
timeline.setMarkerDataSource(container, 
	Timeline.PropertyId.TIMESTAMP,
	Timeline.PropertyId.CAPTION,
	Timeline.PropertyId.VALUE);

timeline.setEventDataSource(container,
	Timeline.PropertyId.TIMESTAMP,
	Timeline.PropertyId.CAPTION);

The above example uses the default property IDs. You can change them to suit your needs.

The Timeline listens for changes in the containers and updates the graph accordingly. When it updates the graph and items are added or removed from the container, the currently selected date range will remain selected. The selection bar in the browser area moves to keep the current selection selected. If you want the selection to change when the contents of the container changes and keep the selection area stationary, you can disable the selection lock by setting setBrowserSelectionLock() to false.

Two types of events are available when using the Vaadin Timeline.

When the user modifies the selected date range by moving the date range selector, dragging the timeline, or by manually entering new dates, an event will be sent to the server with the information of what the current displayed date range is. To listen to these events you can attach a DateRangeListener which will receive the start and end dates of the current selection.

If you are using events in your graph then you can attach an EventClickListener to listen for clicks on the events. The listener will receive a list of itemIds from the event data source which are related to the click event. Since the events can be gathered into a single event icon if space is not sufficient for displaying them all, many item ids can be returned.

The Vaadin Timeline is highly customizable and its outlook can be easily changed to suit your needs. The default view of the Timeline contains all the controls available but often all of them are not needed and can be hidden.

The following list contains the components that can be shown or hidden at your preference:

The outlook of the graphs themselves can also be changed for both the browser area and the main view. The following settings are available through the API:

Other changes to the outlook of the component can easily be done by CSS.

Zoom levels are also fully customizable. Zoom levels are defined as milliseconds and can be added by calling the addZoomLevel() method. A zoom level always has a caption, which is the visible part in the zoom panel, and a millisecond amount.

By default the grid divides the graph into five equally spaced parts with a gray color. However, you can fully customize how the grid is drawn by using setGridColor() and setVerticalGridLines().

By default the Vaadin Timeline uses English as its primary language for the captions and the default locale for the application to display the dates in the timeline.

You can change the different captions in the Timeline by using their corresponding setters:

Furthermore, you can also change the locale in which the Timeline shows the dates in the horizontal scale by specifying a valid locale using the setLocale() method of the timeline.

You can also configure in what format the dates appear in the horizontal scale or in the date select in the top-right corner by using the getDateFormats()-method which will return a DateFormatInfo object. By using its setters you can set specific formats for each date range in the scale. Please note that if you are using long date formats they might get clipped if the scale does not fit the whole formatted date.