Class Index | File Index

## Classes

- _global_
- Array
- links.Timeline
- links.Timeline.StepDate

# Class links.Timeline

Timeline The timeline is a visualization chart to visualize events in time. The timeline is developed in javascript as a Google Visualization Chart.
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.
| 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.
| 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(data) 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.
| 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
| 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
| setScale(newScale, newStep) Set a custom scale.
| setSelection(sel) 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:
{dom_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:
{DOM 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

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:
{htmlelement} item1
  The first item
{htmlelement} item2
  The second item
{int} 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:
{DataTable} data
  The data containing the events for the timeline. Object DataTable is defined in google.visualization.DataTable
{name/value map} options
  A name/value map containing settings for the timeline. Optional.

{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:
{DOM 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:
{DOM 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

getData(data)
Return the original data table.

Parameters:
{Google DataTable or Array} data

{String} getGroupFromHeight(height)
Find the group from a given height in the timeline

Parameters:
{Number} height
  Height in the timeline

Returns:
  {String} group The group name, 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:
{HTML DOM 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> {HTML DOM} links.Timeline.getTarget(event)
Get HTML element which is the target of the event

Parameters:
{MouseEvent} event

Returns:
  {HTML DOM} target element

{Object} getVisibleChartRange()
Retrieve the current visible range in the timeline.

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

{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:
{float} 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:
{DOM element} element
  An html dom element
{string} action
  The name of the event, for example "mousedown"
{function} listener
  The listener function
{boolean} useCapture

{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:
{DataTable or JSON array} data

setGroups(data)
Set the groups available in the given dataset

Parameters:
{DataTable or JSON array} data

setScale(newScale, newStep)
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:
{Step.SCALE} newScale
  A scale. Choose from SCALE.MILLISECOND, SCALE.SECOND, SCALE.MINUTE, SCALE.HOUR, SCALE.DAY, SCALE.MONTH, SCALE.YEAR.
{int} newStep
  A step size, by default 1. Choose for example 1, 2, 5, or 10.

{boolean} setSelection(sel)
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} sel
  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:
{float} zoomFactor
  Zooming amount. Positive value will zoom in, negative value will zoom out
{Date} zoomAroundDate
  Date around which will be zoomed. Optional

Documentation generated by JsDoc Toolkit 2.3.2 on Tue Nov 08 2011 14:35:00 GMT+0100 (CET)