Class links.Timeline

Defined in: timeline.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	links.Timeline(container)

Method Summary
Method Attributes	Method Name and Description
<static>	links.Timeline.addEventListener(element, action, listener, useCapture) Add and event listener.
	addGroup(groupName) Add a group.
	addItem(itemData) Add a new item.
	addItems(items) Add new items.
	applyRange(start, end, zoomAroundDate) Apply a visible range.
	cancelAdd() Cancel creation of a new item This method can be called insed an event listener which catches the "new" event.
	cancelChange() Cancel a change item This method can be called insed an event listener which catches the "change" event.
	cancelDelete() Cancel deletion of an item This method can be called insed an event listener which catches the "delete" event.
	changeItem(index, itemData) Edit an item
	checkResize() Check if the timeline is resized, and if so, redraw the timeline.
	collision(item1, item2, margin) Test if the two provided items collide The items must have parameters left, right, top, and bottom.
	confirmDeleteItem(index) Delete an item after a confirmation.
	createEventBox(content) Create an event in the timeline, with (optional) formatting: inside a box with rounded corners, and a vertical line+dot to the axis.
	createEventDot(content) Create an event in the timeline: a dot, followed by the content.
	createEventRange(content) Create an event range as a beam in the timeline.
	createItem(itemData) Create an item object, containing all needed parameters
	deleteAllItems() Delete all items
	deleteGroups() Delete all groups
	deleteItem(index) Delete an item
	draw(data, options) Main drawing logic.
<static>	links.Timeline.filterImageUrls(elem, urls) Recursively retrieve all image urls from the images located inside a given HTML element
	findGroup(group) Find a group by its name.
<static>	links.Timeline.getAbsoluteLeft(elem) Retrieve the absolute left value of a DOM element
<static>	links.Timeline.getAbsoluteTop(elem) Retrieve the absolute top value of a DOM element
	getCurrentTime() Get current time.
	getCustomTime() Retrieve the current custom time.
	getData() Return the original data table.
	getGroupFromHeight(height, ) Find the group from a given height in the timeline
	getItem(index) Retrieve the properties of an item.
	getItemIndex(element) Find the item index from a given HTML element If no item index is found, undefined is returned
	getSelection() Retrieve the currently selected event
<static>	links.Timeline.getTarget(event) Get HTML element which is the target of the event
	getVisibleChartRange() Retrieve the current visible range in the timeline.
<static>	links.Timeline.isArray(obj) Check if given object is a Javascript Array
	isSelected(index) Check if an item is currently selected
	move(moveFactor) Move the timeline the given movefactor to the left or right.
	onDblClick(event) Double click event occurred for an item
	onMouseDown(event) Start a moving operation inside the provided parent element
	onMouseMove(event) Perform moving operating.
	onMouseUp(event) Stop moving operating.
	onMouseWheel(event) Event handler for mouse wheel event, used to zoom the timeline Code from http://adomas.org/javascript-mouse-wheel/
	onTouchEnd(event) Event handler for touchend event on mobile devices
	onTouchMove(event) Event handler for touchmove event on mobile devices
	onTouchStart(event) Event handler for touchstart event on mobile devices
<static>	links.Timeline.preventDefault(event) Cancels the event if it is cancelable, without stopping further propagation of the event.
	recalcConversion() Calculate the factor and offset to convert a position on screen to the corresponding date and vice versa.
	recalcSize() Recalculate the sizes of all frames, groups, items, axis After recalcSize() is executed, the Timeline should be redrawn normally
	redraw() Redraw the timeline Reloads the (linked) data table and redraws the timeline when resized.
	redrawAxis() Redraw the timeline axis with minor and major labels
	redrawAxisCharacters() Create characters used to determine the size of text on the axis
	redrawAxisEndOverwriting() End of overwriting HTML DOM elements of the axis.
	redrawAxisHorizontal() Redraw the horizontal line and background of the axis
	redrawAxisMajorLine(x) Create a Major line for the axis at position x
	redrawAxisMajorText(x, text) Create a Major label for the axis at position x
	redrawAxisMinorLine(x) Create a minor line for the axis at position x
	redrawAxisMinorText(x, text) Create a minor label for the axis at position x
	redrawAxisStartOverwriting() Initialize redraw of the axis.
	redrawContent() Redraw the content of the timeline: the axis and the items
	redrawCurrentTime() Redraw the current time bar
	redrawCustomTime() Redraw the custom time bar
	redrawDeleteButton() Redraw the delete button, on the top right of the currently selected item if there is no item selected, the button is hidden.
	redrawDragAreas() Redraw the drag areas.
	redrawFrame() Redraw the timeline.
	redrawGroups() Redraw the group labels
	redrawItems() Redraw all items
	redrawNavigation() Create the navigation buttons for zooming and moving
<static>	links.Timeline.removeEventListener(element, action, listener, useCapture) Remove an event listener from an element
	repositionItem(item, left, right) Reposition given item
	screenToTime(x) Convert a position on screen (pixels) to a datetime Before this method can be used, the method calcConversionFactor must be executed once.
	selectItem(index) Select an item by its index
	setAutoScale(enable) Enable or disable autoscaling
	setCurrentTime(time) Set current time.
	setCustomTime(time) Set custom time.
	setData(data) Set data for the timeline
	setGroups(data) Set the groups available in the given dataset
	setOptions(options) Set options for the timeline.
	setScale(scale, step) Set a custom scale.
	setSelection(selection) Select an event.
	setSize(width, height) Set a new size for the timeline
	setVisibleChartRange(start, end, redraw) Set a new value for the visible range int the timeline.
	setVisibleChartRangeAuto() Change the visible chart range such that all items become visible
	setVisibleChartRangeNow() Adjust the visible range such that the current time is located in the center of the timeline
	stackCalculateFinal(items) Adjust vertical positions of the events such that they don't overlap each other.
	stackEvents(animate) Stack the items such that they don't overlap.
	stackEventsCheckOverlap(items, itemIndex, itemStart, itemEnd) Check if the destiny position of given item overlaps with any of the other items from index itemStart to itemEnd.
	stackMoveOneStep(currentItems, finalItems) Move the events one step in the direction of their final positions
	stackMoveToFinal(currentItems, finalItems) Move the events from their current position to the final position
	stackOrder(items) Order the items in the array this.items.
<static>	links.Timeline.stopPropagation(event) Stop event propagation
	timeToScreen(time) Convert a datetime (Date object) into a position on the screen Before this method can be used, the method calcConversionFactor must be executed once.
	trigger(event) fire an event
	unselectItem() Unselect the currently selected event (if any)
	updateData(index, values) Update the original data with changed start, end or group.
	zoom(zoomFactor, zoomAroundDate) Zoom the timeline the given zoomfactor in or out.

Class Detail

links.Timeline(container)

Parameters:
{Element} container: The DOM element in which the Timeline will be created. Normally a div element.

Method Detail

<static> links.Timeline.addEventListener(element, action, listener, useCapture)

Add and event listener. Works for all browsers

Parameters:
{Element} element: An html element
{string} action: The action, for example "click", without the prefix "on"
{function} listener: The callback function to be executed
{boolean} useCapture

{Object} addGroup(groupName)

Add a group. When the group already exists, no new group is created but the existing group is returned.

Parameters:
{String} groupName: the name of the group

Returns:: {Object} groupObject

addItem(itemData)

Add a new item.

Parameters:
{Object} itemData: Object containing item properties:
{Date} start (required), {Date} end (optional), {String} content (required), {String} group (optional)

addItems(items)

Add new items.

Parameters:
{Array} items: An array containing Objects. The objects must have the following parameters: {Date} start, {Date} end, {String} content with text or HTML code, {String} group

applyRange(start, end, zoomAroundDate)

Apply a visible range. The range is limited to feasible maximum and minimum range.

Parameters:
{Date} start
{Date} end
{Date} zoomAroundDate: Optional. Date around which will be zoomed.

cancelAdd()

Cancel creation of a new item This method can be called insed an event listener which catches the "new" event. Creation of the new the event will be undone.

cancelChange()

Cancel a change item This method can be called insed an event listener which catches the "change" event. The changed event position will be undone.

cancelDelete()

Cancel deletion of an item This method can be called insed an event listener which catches the "delete" event. Deletion of the event will be undone.

changeItem(index, itemData)

Edit an item

Parameters:
{Number} index
{Object} itemData: Object containing item properties:
{Date} start (required), {Date} end (optional), {String} content (required), {String} group (optional)

checkResize()

Check if the timeline is resized, and if so, redraw the timeline. Useful when the webpage is resized.

{boolean} collision(item1, item2, margin)

Test if the two provided items collide The items must have parameters left, right, top, and bottom.

Parameters:
{Element} item1: The first item
{Element} item2: The second item
{Number} margin: A minimum required margin. Optional. If margin is provided, the two items will be marked colliding when they overlap or when the margin between the two is smaller than the requested margin.

Returns:: {boolean} true if item1 and item2 collide, else false

confirmDeleteItem(index)

Delete an item after a confirmation. The deletion can be cancelled by executing .cancelDelete() during the triggered event 'delete'.

Parameters:
{int} index: Index of the item to be deleted

createEventBox(content)

Create an event in the timeline, with (optional) formatting: inside a box with rounded corners, and a vertical line+dot to the axis.

Parameters:
{string} content: The content for the event. This can be plain text or HTML code.

createEventDot(content)

Create an event in the timeline: a dot, followed by the content.

Parameters:
{string} content: The content for the event. This can be plain text or HTML code.

createEventRange(content)

Create an event range as a beam in the timeline.

Parameters:
{string} content: The content for the event. This can be plain text or HTML code.

{Object} createItem(itemData)

Create an item object, containing all needed parameters

Parameters:
{Object} itemData: Object containing parameters start, end content, group.

Returns:: {Object} item

deleteAllItems()

Delete all items

deleteGroups()

Delete all groups

deleteItem(index)

Delete an item

Parameters:
{int} index: Index of the item to be deleted

draw(data, options)

Main drawing logic. This is the function that needs to be called in the html page, to draw the timeline. A data table with the events must be provided, and an options table.

Parameters:
{google.visualization.DataTable} data: The data containing the events for the timeline. Object DataTable is defined in google.visualization.DataTable
{Object} options: A name/value map containing settings for the timeline. Optional.

<static> links.Timeline.filterImageUrls(elem, urls)

Recursively retrieve all image urls from the images located inside a given HTML element

Parameters:
{HTMLElement} elem
{String[]} urls: Urls will be added here (no duplicates)

{Object} findGroup(group)

Find a group by its name.

Parameters:
{String} group

Returns:: {Object} a group object or undefined when group is not found

<static> {number} links.Timeline.getAbsoluteLeft(elem)

Retrieve the absolute left value of a DOM element

Parameters:
{Element} elem: A dom element, for example a div

Returns:: {number} left The absolute left position of this element in the browser page.

<static> {number} links.Timeline.getAbsoluteTop(elem)

Retrieve the absolute top value of a DOM element

Parameters:
{Element} elem: A dom element, for example a div

Returns:: {number} top The absolute top position of this element in the browser page.

{Date} getCurrentTime()

Get current time. The time can have an offset from the real time, when the current time has been changed via the method setCurrentTime.

Returns:: {Date} time

{Date} getCustomTime()

Retrieve the current custom time.

Returns:: {Date} customTime

{google.visualization.DataTable | Array} getData()

Return the original data table.

Returns:: {google.visualization.DataTable | Array} data

{Object} getGroupFromHeight(height, )

Find the group from a given height in the timeline

Parameters:
{Number} height: Height in the timeline
{boolean}

Returns:: {Object} group The group object, or undefined if out of range

{Object} getItem(index)

Retrieve the properties of an item.

Parameters:
{Number} index

Returns:: {Object} properties Object containing item properties:
{Date} start (required), {Date} end (optional), {String} content (required), {String} group (optional)

{Number} getItemIndex(element)

Find the item index from a given HTML element If no item index is found, undefined is returned

Parameters:
{Element} element

Returns:: {Number} index

{Array} getSelection()

Retrieve the currently selected event

Returns:: {Array} sel An array with a column row, containing the row number of the selected event. If there is no selection, an empty array is returned.

<static> {Element} links.Timeline.getTarget(event)

Get HTML element which is the target of the event

Parameters:
{MouseEvent} event

Returns:: {Element} target element

{Object} getVisibleChartRange()

Retrieve the current visible range in the timeline.

Returns:: {Object} An object with start and end properties

<static> {Boolean} links.Timeline.isArray(obj)

Check if given object is a Javascript Array

Parameters:
{*} obj

Returns:: {Boolean} isArray true if the given object is an array

{boolean} isSelected(index)

Check if an item is currently selected

Parameters:
{Number} index

Returns:: {boolean} true if row is selected, else false

move(moveFactor)

Move the timeline the given movefactor to the left or right. Start and end date will be adjusted, and the timeline will be redrawn. For example, try moveFactor = 0.1 or -0.1

Parameters:
{Number} moveFactor: Moving amount. Positive value will move right, negative value will move left

onDblClick(event)

Double click event occurred for an item

Parameters:
{event} event

onMouseDown(event)

Start a moving operation inside the provided parent element

Parameters:
{event} event: The event that occurred (required for retrieving the mouse position)

onMouseMove(event)

Perform moving operating. This function activated from within the funcion links.Timeline.onMouseDown().

Parameters:
{event} event: Well, eehh, the event

onMouseUp(event)

Stop moving operating. This function activated from within the funcion links.Timeline.onMouseDown().

Parameters:
{event} event: The event

onMouseWheel(event)

Event handler for mouse wheel event, used to zoom the timeline Code from http://adomas.org/javascript-mouse-wheel/

Parameters:
{event} event: The event

onTouchEnd(event)

Event handler for touchend event on mobile devices

Parameters:
event

onTouchMove(event)

Event handler for touchmove event on mobile devices

Parameters:
event

onTouchStart(event)

Event handler for touchstart event on mobile devices

Parameters:
event

<static> links.Timeline.preventDefault(event)

Cancels the event if it is cancelable, without stopping further propagation of the event.

Parameters:
event

recalcConversion()

Calculate the factor and offset to convert a position on screen to the corresponding date and vice versa. After the method calcConversionFactor is executed once, the methods screenToTime and timeToScreen can be used.

{boolean} recalcSize()

Recalculate the sizes of all frames, groups, items, axis After recalcSize() is executed, the Timeline should be redrawn normally

Returns:: {boolean} resized Returns true when the timeline has been resized

redraw()

Redraw the timeline Reloads the (linked) data table and redraws the timeline when resized. See also the method checkResize

redrawAxis()

Redraw the timeline axis with minor and major labels

redrawAxisCharacters()

Create characters used to determine the size of text on the axis

redrawAxisEndOverwriting()

End of overwriting HTML DOM elements of the axis. remaining elements will be removed

redrawAxisHorizontal()

Redraw the horizontal line and background of the axis

redrawAxisMajorLine(x)

Create a Major line for the axis at position x

Parameters:
{Number} x

redrawAxisMajorText(x, text)

Create a Major label for the axis at position x

Parameters:
{Number} x
{String} text

redrawAxisMinorLine(x)

Create a minor line for the axis at position x

Parameters:
{Number} x

redrawAxisMinorText(x, text)

Create a minor label for the axis at position x

Parameters:
{Number} x
{String} text

redrawAxisStartOverwriting()

Initialize redraw of the axis. All existing labels and lines will be overwritten and reused.

redrawContent()

Redraw the content of the timeline: the axis and the items

redrawCurrentTime()

Redraw the current time bar

redrawCustomTime()

Redraw the custom time bar

redrawDeleteButton()

Redraw the delete button, on the top right of the currently selected item if there is no item selected, the button is hidden.

redrawDragAreas()

Redraw the drag areas. When an item (ranges only) is selected, it gets a drag area on the left and right side, to change its width

redrawFrame()

Redraw the timeline. This needs to be executed after the start and/or end time are changed, or when data is added or removed dynamically.

redrawGroups()

Redraw the group labels

redrawItems()

Redraw all items

redrawNavigation()

Create the navigation buttons for zooming and moving

<static> links.Timeline.removeEventListener(element, action, listener, useCapture)

Remove an event listener from an element

Parameters:
{Element} element: An html dom element
{string} action: The name of the event, for example "mousedown"
{function} listener: The listener function
{boolean} useCapture

repositionItem(item, left, right)

Reposition given item

Parameters:
{Object} item
{Number} left
{Number} right

{Date} screenToTime(x)

Convert a position on screen (pixels) to a datetime Before this method can be used, the method calcConversionFactor must be executed once.

Parameters:
{int} x: Position on the screen in pixels

Returns:: {Date} time The datetime the corresponds with given position x

selectItem(index)

Select an item by its index

Parameters:
{Number} index

setAutoScale(enable)

Enable or disable autoscaling

Parameters:
{boolean} enable: If true or not defined, autoscaling is enabled. If false, autoscaling is disabled.

setCurrentTime(time)

Set current time. This function can be used to set the time in the client timeline equal with the time on a server.

Parameters:
{Date} time

setCustomTime(time)

Set custom time. The custom time bar can be used to display events in past or future.

Parameters:
{Date} time

setData(data)

Set data for the timeline

Parameters:
{google.visualization.DataTable | array} data

setGroups(data)

Set the groups available in the given dataset

Parameters:
{google.visualization.DataTable | array} data

setOptions(options)

Set options for the timeline. Timeline must be redrawn afterwards

Parameters:
{Object} options: A name/value map containing settings for the timeline. Optional.

setScale(scale, step)

Set a custom scale. Autoscaling will be disabled. For example setScale(SCALE.MINUTES, 5) will result in minor steps of 5 minutes, and major steps of an hour.

Parameters:
{links.Timeline.StepDate.SCALE} scale: A scale. Choose from SCALE.MILLISECOND, SCALE.SECOND, SCALE.MINUTE, SCALE.HOUR, SCALE.DAY, SCALE.MONTH, SCALE.YEAR.
{int} step: A step size, by default 1. Choose for example 1, 2, 5, or 10.

{boolean} setSelection(selection)

Select an event. The visible chart range will be moved such that the selected event is placed in the middle. For example selection = [{row: 5}];

Parameters:
{Array} selection: An array with a column row, containing the row number (the id) of the event to be selected.

Returns:: {boolean} true if selection is succesfully set, else false.

setSize(width, height)

Set a new size for the timeline

Parameters:
{string} width: Width in pixels or percentage (for example "800px" or "50%")
{string} height: Height in pixels or percentage (for example "400px" or "30%")

setVisibleChartRange(start, end, redraw)

Set a new value for the visible range int the timeline. Set start to null to include everything from the earliest date to end. Set end to null to include everything from start to the last date. Example usage: myTimeline.setVisibleChartRange(new Date("2010-08-22"), new Date("2010-09-13"));

Parameters:
{Date} start: The start date for the timeline. optional
{Date} end: The end date for the timeline. optional
{boolean} redraw: Optional. If true (default) the Timeline is directly redrawn

setVisibleChartRangeAuto()

Change the visible chart range such that all items become visible

setVisibleChartRangeNow()

Adjust the visible range such that the current time is located in the center of the timeline

stackCalculateFinal(items)

Adjust vertical positions of the events such that they don't overlap each other.

Parameters:
items

stackEvents(animate)

Stack the items such that they don't overlap. The items will have a minimal distance equal to options.eventMargin.

Parameters:
{boolean} animate: if animate is true, the items are moved to their new position animated

{Object} stackEventsCheckOverlap(items, itemIndex, itemStart, itemEnd)

Check if the destiny position of given item overlaps with any of the other items from index itemStart to itemEnd.

Parameters:
{Array} items: Array with items
{int} itemIndex: Number of the item to be checked for overlap
{int} itemStart: First item to be checked.
{int} itemEnd: Last item to be checked.

Returns:: {Object} colliding item, or undefined when no collisions

{boolean} stackMoveOneStep(currentItems, finalItems)

Move the events one step in the direction of their final positions

Parameters:
{Array} currentItems: Array with the real items and their current positions
{Array} finalItems: Array with objects containing the final positions of the items

Returns:: {boolean} arrived True if all items have reached their final location, else false

stackMoveToFinal(currentItems, finalItems)

Move the events from their current position to the final position

Parameters:
{Array} currentItems: Array with the real items and their current positions
{Array} finalItems: Array with objects containing the final positions of the items

{Array} stackOrder(items)

Order the items in the array this.items. The order is determined via: - Ranges go before boxes and dots. - The item with the left most location goes first

Parameters:
{Array} items: Array with items

Returns:: {Array} sortedItems Array with sorted items

<static> links.Timeline.stopPropagation(event)

Stop event propagation

Parameters:
event

{int} timeToScreen(time)

Convert a datetime (Date object) into a position on the screen Before this method can be used, the method calcConversionFactor must be executed once.

Parameters:
{Date} time: A date

Returns:: {int} x The position on the screen in pixels which corresponds with the given date.

trigger(event)

fire an event

Parameters:
{String} event: The name of an event, for example "rangechange" or "edit"

unselectItem()

Unselect the currently selected event (if any)

updateData(index, values)

Update the original data with changed start, end or group.

Parameters:
{Number} index
{Object} values: An object containing some of the following parameters: {Date} start, {Date} end, {String} content, {String} group

zoom(zoomFactor, zoomAroundDate)

Zoom the timeline the given zoomfactor in or out. Start and end date will be adjusted, and the timeline will be redrawn. You can optionally give a date around which to zoom. For example, try zoomfactor = 0.1 or -0.1

Parameters:
{Number} zoomFactor: Zooming amount. Positive value will zoom in, negative value will zoom out
{Date} zoomAroundDate: Date around which will be zoomed. Optional

Classes

Class links.Timeline