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:
setZoomLevelsCaption()
-- The caption appearing before the zoom levelssetChartModesCaption()
-- The caption appearing before the chart modes
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.