Vaadin Timeline

Figure 20.7. Timeline Event Markers

(On left) Marker with a customizable marker sign, for example, letter 'E'. The marker displays a caption which appears when the user hovers the pointer over the event.

(On right) Marker with button-like appearance with a marker sign and a caption.

Efficiency

Vaadin Timeline reduces the traffic between the server and the client by using two methods.

First of all, all the data that is presented in the component is dynamically fetched from the server as needed. This means that when the user scrolls the timeline view, the component continuously fetches data from the server. Also, only data that is visible to the user is transferred to the client. For example, if the timeline has data that has been measured once a second for an entire year, not all the data will be sent to the client. Only the data which can be rendered on the screen without overlapping is sent. This ensures that, even for large data sets, the loading time is small and only the necessary data is actually transferred over the network.

Second, Vaadin Timeline caches the data received from the server in the browser, so that the data is transferred over the network only once, if possible. This speeds up the time-range browsing when data can be fetched from the cache instead of reloading it over the network.

20.2. Using Timeline

20.2.1. Data Source Requirements

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 clientside 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.

Efficiency

439

Vaadin Timeline

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

440	Data Source Requirements

Vaadin Timeline

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.

20.2.2. Events and Listeners

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.

20.2.3. Configurability

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:

•Chart modes

•Textual date select

•Browser area (bottom part of the Timeline)

•Legend

•Zoom levels

•Caption

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:

•Graph outline color

•Graph outline width

•Graph caps (in line graphs only)

•Graph fill color

•Graph visibility

•Graph shadows

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

Events and Listeners

441