Options are defined as a JSON object. All options are optional.
</p>
<preclass="prettyprint lang-js">
var options = {
width: '100%',
height: '30px',
margin: {
item: 20
}
};
</pre>
<p>
The following options are available.
</p>
<tableclass="options"id="optionTable">
<tr>
<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td>align</td>
<td>String</td>
<td><code>'center'</code></td>
<td>Alignment of items with type 'box', 'range', and 'background'. Available values are 'auto' (default), 'center', 'left', or 'right'. For 'box' items, the 'auto' alignment is 'center'. For 'range' items, the auto alignment is dynamic: positioned left and shifted such that the contents is always visible on screen.</td>
</tr>
<tr>
<td>autoResize</td>
<td>boolean</td>
<td><code>true</code></td>
<td>If true, the Timeline will automatically detect when its container is resized, and redraw itself accordingly. If false, the Timeline can be forced to repaint after its container has been resized using the function <code>redraw()</code>.</td>
</tr>
<tr>
<td>clickToUse</td>
<td>boolean</td>
<td><code>false</code></td>
<td>When a Timeline is configured to be <code>clickToUse</code>, it will react to mouse and touch events only when active.
When active, a blue shadow border is displayed around the Timeline. The Timeline is set active by clicking on it, and is changed to inactive again by clicking outside the Timeline or by pressing the ESC key.</td>
</tr>
<tr>
<td>configure</td>
<td>boolean or function</td>
<td><code>false</code></td>
<td>When true, a configurator is loaded where all configuration options of the Timeline can be changed live.
The displayed options can be filtered by providing a filter function. This function is invoked with two arguments: the current <code>option</code> and the <code>path</code> (an Array) of the option within the options object. The option will be displayed when the filter function returns true. For example to only display format options:
<td>An array of fields optionally defined on the timeline items that will be appended as <code>data-</code> attributes to the DOM element of the items.<br>
If value is <code>'all'</code> then each field defined on the timeline item will become a <code>data-</code> attribute.</td>
<td>If true, the items in the timeline can be manipulated. Only applicable when option <code>selectable</code> is <code><code>true</code></code>. See also the callbacks <code>onAdd</code>, <code>onUpdate</code>, <code>onMove</code>, and <code>onRemove</code>. When <code>editable</code> is an object, one can enable or disable individual manipulation actions.
See section <ahref="#Editing_Items">Editing Items</a> for a detailed explanation.
</td>
</tr>
<trparent="editable"class="hidden">
<tdclass="indent">editable.add</td>
<td>boolean</td>
<td><code>false</code></td>
<td>If true, new items can be created by double tapping an empty space in the Timeline. See section <ahref="#Editing_Items">Editing Items</a> for a detailed explanation.</td>
</tr>
<trparent="editable"class="hidden">
<tdclass="indent">editable.remove</td>
<td>boolean</td>
<td><code>false</code></td>
<td>If true, items can be deleted by first selecting them, and then clicking the delete button on the top right of the item. See section <ahref="#Editing_Items">Editing Items</a> for a detailed explanation.</td>
</tr>
<trparent="editable"class="hidden">
<tdclass="indent">editable.updateGroup</td>
<td>boolean</td>
<td><code>false</code></td>
<td>If true, items can be dragged from one group to another. Only applicable when the Timeline has groups. See section <ahref="#Editing_Items">Editing Items</a> for a detailed explanation.</td>
</tr>
<trparent="editable"class="hidden">
<tdclass="indent">editable.updateTime</td>
<td>boolean</td>
<td><code>false</code></td>
<td>If true, items can be dragged to another moment in time. See section <ahref="#Editing_Items">Editing Items</a> for a detailed explanation.</td>
</tr>
<tr>
<td>end</td>
<td>Date or Number or String or Moment</td>
<td>none</td>
<td>The initial end date for the axis of the timeline.
If not provided, the latest date present in the items set is taken as
end date.</td>
</tr>
<tr>
<td>format</td>
<td>Object</td>
<td>none</td>
<td>
Apply custom date formatting of the labels on the time axis. The default value of <code>format</code> is:
<preclass="prettyprint lang-js">{
minorLabels: {
millisecond:'SSS',
second: 's',
minute: 'HH:mm',
hour: 'HH:mm',
weekday: 'ddd D',
day: 'D',
month: 'MMM',
year: 'YYYY'
},
majorLabels: {
millisecond:'HH:mm:ss',
second: 'D MMMM HH:mm',
minute: 'ddd D MMMM',
hour: 'ddd D MMMM',
weekday: 'MMMM YYYY',
day: 'MMMM YYYY',
month: 'YYYY',
year: ''
}
}</pre>
For values which not provided in the customized <code>options.format</code>, the default values will be used.
All available formatting syntax is described in the <ahref="http://momentjs.com/docs/#/displaying/format/">docs of moment.js</a>.
<td>If true, the groups in the timeline can be manipulated. See also the callbacks <code>onAddGroup</code>, <code>onMoveGroup</code>, and <code>onRemoveGroup</code>. When <code>groupEditable</code> is an object, one can enable or disable individual manipulation actions.
The editing of groups follows the same principles as for items, see section <ahref="#Editing_Items">Editing Items</a> for a detailed explanation.
</td>
</tr>
<trparent="groupEditable"class="hidden">
<tdclass="indent">groupEditable.add</td>
<td>boolean</td>
<td><code>false</code></td>
<td>If true, new groups can be created in the Timeline. For now adding new groups is done by the user.</td>
</tr>
<trparent="groupEditable"class="hidden">
<tdclass="indent">groupEditable.remove</td>
<td>boolean</td>
<td><code>false</code></td>
<td>If true, groups can be deleted. For now removing groups is done by the user.</td>
</tr>
<trparent="groupEditable"class="hidden">
<tdclass="indent">groupEditable.order</td>
<td>boolean</td>
<td><code>false</code></td>
<td>If true, groups can be dragged to change their order. Only applicable when the Timeline has groups. For this option to work properly the groupOrder and groupOrderSwap options have to be set as well.</td>
By default, groups are ordered by a property <code>order</code> (if set).
If no <code>order</code> properties are provided, the order will be undetermined.
</td>
</tr>
<tr>
<td>groupOrderSwap</td>
<td>Function</td>
<td>none</td>
<td>Swaps the positions of two groups. If groups have a custom order (via <code>groupOrder</code>) and groups are configured to be reorderable (via <code>groupEditable.order</code>), the user has to provide a function that swaps the positions of two given groups.
If this option is not set, the default implementation assumes that groups hold an attribute <code>order</code> which values are changed. The signature of the <code>groupOrderWap</code> function is:
<td>A template function used to generate the contents of the groups. The function is called by the Timeline with a groups data as argument, and must return HTML code as result. When the option groupTemplate is specified, the groups do not need to have a field <code>content</code>. See section <ahref="#Templates">Templates</a> for a detailed explanation.</td>
</tr>
<tr>
<td>height</td>
<td>number or String</td>
<td>none</td>
<td>The height of the timeline in pixels or as a percentage.
When height is undefined or null, the height of the timeline is automatically
adjusted to fit the contents.
It is possible to set a maximum height using option <code>maxHeight</code>
to prevent the timeline from getting too high in case of automatically
calculated height.
</td>
</tr>
<tr>
<td>hiddenDates</td>
<td>Object</td>
<td>none</td>
<td>This option allows you to hide specific timespans from the time axis. The dates can be supplied as an object:
<code>{start: '2014-03-21 00:00:00', end: '2014-03-28 00:00:00', [repeat:'daily']}</code> or as an Array of these objects. The repeat argument is optional.
The possible values are (case-sensitive): <code>daily, weekly, monthly, yearly</code>. To hide a weekend, pick any Saturday as start and the following Monday as end
<td>A constructor for creating a moment.js Date. Allows for applying a custom time zone. See section <ahref="#Time_zone">Time zone</a> for more information.</td>
<td>Callback function triggered when an item is about to be added: when the user double taps an empty space in the Timeline. See section <ahref="#Editing_Items">Editing Items</a> for more information. Only applicable when both options <code>selectable</code> and <code>editable.add</code> are set <code><code>true</code></code>.
<td>Callback function triggered when an item is about to be updated, when the user double taps an item in the Timeline. See section <ahref="#Editing_Items">Editing Items</a> for more information. Only applicable when both options <code>selectable</code> and <code>editable.updateTime</code> or <code>editable.updateGroup</code> are set <code><code>true</code></code>.
</td>
</tr>
<tr>
<td>onMove</td>
<td>function</td>
<td>none</td>
<td>Callback function triggered when an item has been moved: after the user has dragged the item to an other position. See section <ahref="#Editing_Items">Editing Items</a> for more information. Only applicable when both options <code>selectable</code> and <code>editable.updateTime</code> or <code>editable.updateGroup</code> are set <code><code>true</code></code>.
<td>Callback function triggered when a group has been moved: after the user has dragged the group to an other position. The signature and semantics are the same as for <code>onMove</code>.
<td>Callback function triggered repeatedly when an item is being moved. See section <ahref="#Editing_Items">Editing Items</a> for more information. Only applicable when both options <code>selectable</code> and <code>editable.updateTime</code> or <code>editable.updateGroup</code> are set <code><code>true</code></code>.
</td>
</tr>
<tr>
<td>onRemove</td>
<td>function</td>
<td>none</td>
<td>Callback function triggered when an item is about to be removed: when the user tapped the delete button on the top right of a selected item. See section <ahref="#Editing_Items">Editing Items</a> for more information. Only applicable when both options <code>selectable</code> and <code>editable.remove</code> are set <code><code>true</code></code>.
<p>Provide a custom sort function to order the items. The order of the
items is determining the way they are stacked. The function
order is called with two arguments containing the data of two items to be
compared.
</p>
<pstyle="font-style: italic">WARNING: Use with caution. Custom ordering is not suitable for large amounts of items. On load, the Timeline will render all items once to determine their width and height. Keep the number of items in this configuration limited to a maximum of a few hundred items.</p>
<td>Orientation of the timelines axis and items. When orientation is a string, the value is applied to both items and axis. Can be 'top', 'bottom' (default), 'both', or 'none'.</td>
</tr>
<trparent="orientation"class="hidden">
<tdclass="indent">orientation.axis</td>
<td>String</td>
<td><code>'bottom'</code></td>
<td>Orientation of the timeline axis: 'top', 'bottom' (default), 'both', or 'none'. If orientation is 'bottom', the time axis is drawn at the bottom. When 'top', the axis is drawn on top. When 'both', two axes are drawn, both on top and at the bottom. In case of 'none', no axis is drawn at all.</td>
</tr>
<trparent="orientation"class="hidden">
<tdclass="indent">orientation.item</td>
<td>String</td>
<td><code>'bottom'</code></td>
<td>Orientation of the timeline items: 'top' or 'bottom' (default). Determines whether items are aligned to the top or bottom of the Timeline.</td>
</tr>
<tr>
<td>selectable</td>
<td>boolean</td>
<td><code>true</code></td>
<td>If true, the items on the timeline can be selected. Multiple items can be selected by long pressing them, or by using ctrl+click or shift+click. The event <code>select</code> is fired each time the selection has changed (see section <ahref="#Events">Events</a>).</td>
</tr>
<tr>
<td>showCurrentTime</td>
<td>boolean</td>
<td><code>true</code></td>
<td>Show a vertical bar at the current time.</td>
</tr>
<tr>
<tr>
<td>showMajorLabels</td>
<td>boolean</td>
<td><code>true</code></td>
<td>By default, the timeline shows both minor and major date labels on the
time axis.
For example the minor labels show minutes and the major labels show hours.
When <code>showMajorLabels</code> is <code><code>false</code></code>, no major labels
are shown.</td>
</tr>
<tr>
<td>showMinorLabels</td>
<td>boolean</td>
<td><code>true</code></td>
<td>By default, the timeline shows both minor and major date labels on the
time axis.
For example the minor labels show minutes and the major labels show hours.
When <code>showMinorLabels</code> is <code><code>false</code></code>, no minor labels
are shown. When both <code>showMajorLabels</code> and
<code>showMinorLabels</code> are false, no horizontal axis will be
visible.</td>
</tr>
<tr>
<td>stack</td>
<td>boolean</td>
<td><code>true</code></td>
<td>If true (default), items will be stacked on top of each other such that they do not overlap.</td>
</tr>
<tr>
<td>snap</td>
<td>function or null</td>
<td>function</td>
<td>When moving items on the Timeline, they will be snapped to nice dates like full hours or days, depending on the current scale. The <code>snap</code> function can be replaced with a custom function, or can be set to <code>null</code> to disable snapping. The signature of the snap function is:
<preclass="prettyprint lang-js">function snap(date: Date, scale: string, step: number) : Date or number</pre>
The parameter <code>scale</code> can be can be 'millisecond', 'second', 'minute', 'hour', 'weekday, 'day, 'month, or 'year'. The parameter <code>step</code> is a number like 1, 2, 4, 5.
</td>
</tr>
<tr>
<td>start</td>
<td>Date or Number or String or Moment</td>
<td>none</td>
<td>The initial start date for the axis of the timeline.
If not provided, the earliest date present in the events is taken as start date.</td>
</tr>
<tr>
<td>template</td>
<td>function</td>
<td>none</td>
<td>A template function used to generate the contents of the items. The function is called by the Timeline with an items data as argument, and must return HTML code as result. When the option template is specified, the items do not need to have a field <code>content</code>. See section <ahref="#Templates">Templates</a> for a detailed explanation.</td>
<td>Limit the maximum number of redraws to once every x milliseconds. For example setting throttleRedraw to `100` milliseconds will limit the number of redraws to 10 times per second.</td>
<td>Specify a fixed scale and step size for the time axis.</td>
</tr>
<trparent="timeAxis"class="hidden">
<tdclass="indent">timeAxis.scale</td>
<td>String</td>
<td>none</td>
<td>Set a fixed scale for the time axis of the Timeline. Choose from <code>'millisecond'</code>, <code>'second'</code>, <code>'minute'</code>, <code>'hour'</code>, <code>'weekday'</code>, <code>'day'</code>, <code>'month'</code>, <code>'year'</code>. Example usage:
Set a fixed step size for the time axis. Only applicable when used together with <code>timeAxis.scale</code>.
Choose for example 1, 2, 5, or 10.</td>
</tr>
<tr>
<td>type</td>
<td>String</td>
<td>none</td>
<td>Specifies the default type for the timeline items. Choose from 'box', 'point', 'range', and 'background'. Note that individual items can override this default type. If undefined, the Timeline will auto detect the type from the items data: if a start and end date is available, a 'range' will be created, and else, a 'box' is created. Items of type 'background' are not editable.
</td>
</tr>
<tr>
<td>width</td>
<td>String or Number</td>
<td><code>'100%'</code></td>
<td>The width of the timeline in pixels or as a percentage.</td>
</tr>
<tr>
<td>zoomable</td>
<td>boolean</td>
<td><code>true</code></td>
<td>
Specifies whether the Timeline can be zoomed by pinching or scrolling in the window.
Only applicable when option <code>moveable</code> is set <code><code>true</code></code>.
</td>
</tr>
<tr>
<td>zoomKey</td>
<td>String</td>
<td><code>''</code></td>
<td>Specifies whether the Timeline is only zoomed when an additional key is down.
Available values are '' (does not apply), 'altKey', 'ctrlKey', or 'metaKey'.
Only applicable when option <code>moveable</code> is set <code><code>true</code></code>.
</td>
</tr>
<tr>
<td>zoomMax</td>
<td>number</td>
<td><code>315360000000000</code></td>
<td>Set a maximum zoom interval for the visible range in milliseconds.
It will not be possible to zoom out further than this maximum.
Default value equals about 10000 years.
</td>
</tr>
<tr>
<td>zoomMin</td>
<td>number</td>
<td><code>10</code></td>
<td>Set a minimum zoom interval for the visible range in milliseconds.
It will not be possible to zoom in further than this minimum.
</td>
</tr>
</table>
<h2id="Methods">Methods</h2>
<p>
The Timeline supports the following methods.
</p>
<tableclass="methods">
<tr>
<th>Method</th>
<th>Return Type</th>
<th>Description</th>
</tr>
<tr>
<td>addCustomTime([time] [, id])</td>
<td>number or String</td>
<td>
Add new vertical bar representing a custom time that can be dragged by the user.
Parameter <code>time</code> can be a Date, Number, or String, and is <code>new Date()</code> by default.
Parameter <code>id</code> can be Number or String and is <code>undefined</code> by default.
The <code>id</code>code> is added as CSS class name of the custom time bar, allowing to style multiple time bars differently.
The method returns id of the created bar.
</td>
</tr>
<tr>
<td>destroy()</td>
<td>none</td>
<td>Destroy the Timeline. The timeline is removed from memory. all DOM elements and event listeners are cleaned up.
</td>
</tr>
<tr>
<td>fit([options])</td>
<td>none</td>
<td>Adjust the visible window such that it fits all items. See also function <code>focus(id)</code>.
Available options:
<ul>
<li><code>animation: boolean or {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.
</li>
</ul>
</td>
</tr>
<tr>
<td>focus(id or ids [, options])</td>
<td>none</td>
<td>Adjust the visible window such that the selected item (or multiple items) are centered on screen. See also function <code>fit()</code>. Available options:
<ul>
<li><code>animation: boolean or {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.</li>
</ul>
</td>
</tr>
<tr>
<td>getCurrentTime()</td>
<td>Date</td>
<td>Get the current time. Only applicable when option <code>showCurrentTime</code> is true.
</td>
</tr>
<tr>
<td>getCustomTime([id])</td>
<td>Date</td>
<td>Retrieve the custom time from the custom time bar with given id. Id is <code>undefined</code> by default.
</td>
</tr>
<trid="getEventProperties">
<td>getEventProperties(event)</td>
<td>Object</td>
<td>
Returns an Object with relevant properties from an event:
<ul>
<li><code>group</code> (Number or null): the id of the clicked group.</li>
<li><code>item</code> (Number or null): the id of the clicked item.</li>
<li><code>pageX</code> (Number): absolute horizontal position of the click event.</li>
<li><code>pageY</code> (Number): absolute vertical position of the click event.</li>
<li><code>x</code> (Number): relative horizontal position of the click event.</li>
<li><code>y</code> (Number): relative vertical position of the click event.</li>
<li><code>time</code> (Date): Date of the clicked event.</li>
<li><code>snappedTime</code> (Date): Date of the clicked event, snapped to a nice value.</li>
<li><code>what</code> (String or null): name of the clicked thing: <code>item</code>, <code>background</code>, <code>axis</code>, <code>group-label</code>, <code>custom-time</code>, or <code>current-time</code>.</li>
<li><code>event</code> (Object): the original click event.</li>
</ul>
Example usage:
<preclass="prettyprint lang-js">
document.getElementById('myTimeline').onclick = function (event) {
<td>Get an array with the ids of the currently selected items.</td>
</tr>
<tr>
<td>getVisibleItems()</td>
<td>number[]</td>
<td>Get an array with the ids of the currently visible items.</td>
</tr>
<tr>
<td>getWindow()</td>
<td>Object</td>
<td>Get the current visible window. Returns an object with properties <code>start: Date</code> and <code>end: Date</code>.</td>
</tr>
<tr>
<td>moveTo(time [, options])</td>
<td>none</td>
<td>Move the window such that given time is centered on screen. Parameter <code>time</code> can be a <code>Date</code>, <code>Number</code>, or <code>String</code>. Available options:
<ul>
<li><code>animation: boolean or {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.</li>
</ul>
</td>
</tr>
<tr>
<td>on(event, callback)</td>
<td>none</td>
<td>Create an event listener. The callback function is invoked every time the event is triggered. Avialable events: <code>rangechange</code>, <code>rangechanged</code>, <code>select</code>. The callback function is invoked as <code>callback(properties)</code>, where <code>properties</code> is an object containing event specific properties. See section <ahref="#Events">Events for more information</a>.</td>
</tr>
<tr>
<td>off(event, callback)</td>
<td>none</td>
<td>Remove an event listener created before via function <code>on(event, callback)</code>. See section <ahref="#Events">Events for more information</a>.</td>
</tr>
<tr>
<td>redraw()</td>
<td>none</td>
<td>Force a redraw of the Timeline. The size of all items will be recalculated.
Can be useful to manually redraw when option <code>autoResize=false</code> and the window
has been resized, or when the items CSS has been changed.
</td>
</tr>
<tr>
<td>removeCustomTime(id)</td>
<td>none</td>
<td>
Remove vertical bars previously added to the timeline via <code>addCustomTime</code> method. Parameter <code>id</code> is the ID of the custom vertical bar returned by <code>addCustomTime</code> method.
</td>
</tr>
<tr>
<td>setCurrentTime(time)</td>
<td>none</td>
<td>Set a current time. This can be used for example to ensure that a client's time is synchronized with a shared server time.
<code>time</code> can be a Date object, numeric timestamp, or ISO date string.
Only applicable when option <code>showCurrentTime</code> is true.</td>
</tr>
<tr>
<td>setCustomTime(time [, id])</td>
<td>none</td>
<td>Adjust the time of a custom time bar.
Parameter <code>time</code> can be a Date object, numeric timestamp, or ISO date string.
Parameter <code>id</code> is the idof the custom time bar, and is <code>undefined</code> by default.
<td>Set both groups and items at once. Both properties are optional. This is a convenience method for individually calling both <code>setItems(items)</code> and <code>setGroups(groups)</code>.
Both <code>items</code> and <code>groups</code> can be an Array with Objects,
<td>Set or update options. It is possible to change any option of the timeline at any time. You can for example switch orientation on the fly.
</td>
</tr>
<tr>
<td>setSelection(id or ids [, options])</td>
<td>none</td>
<td>Select one or multiple items by their id. The currently selected items will be unselected. To unselect all selected items, call `setSelection([])`. Available options:
<ul>
<li><code>focus: boolean</code><br>If true, focus will be set to the selected item(s)</li>
<li><code>animation: boolean or {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Only applicable when option focus is true. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.</li>
</ul>
</td>
</tr>
<tr>
<td>setWindow(start, end [, options])</td>
<td>none</td>
<td>Set the current visible window. The parameters <code>start</code> and <code>end</code> can be a <code>Date</code>, <code>Number</code>, or <code>String</code>. If the parameter value of <code>start</code> or <code>end</code> is null, the parameter will be left unchanged. Available options:
<ul>
<li><code>animation: boolean or {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.</li>
</ul>
</td>
</tr>
</table>
<h2id="Events">Events</h2>
<p>
Timeline fires events when changing the visible window by dragging, when
selecting items, and when dragging the custom time bar.
</p>
<p>
Here an example on how to listen for a <code>select</code> event.
</p>
<preclass="prettyprint lang-js">
timeline.on('select', function (properties) {
alert('selected items: ' + properties.nodes);
});
</pre>
<p>
A listener can be removed via the function <code>off</code>:
Passes a properties object as returned by the method <ahref="#getEventProperties"><code>Timeline.getEventProperties(event)</code></a>.
</td>
<td>Fired when clicked inside the Timeline.
</td>
</tr>
<tr>
<td>contextmenu</td>
<td>
Passes a properties object as returned by the method <ahref="#getEventProperties"><code>Timeline.getEventProperties(event)</code></a>.
</td>
<td>Fired when right-clicked inside the Timeline. Note that in order to prevent the context menu from showing up, default behavior of the event must be stopped:
<preclass="prettyprint lang-js">timeline.on('contextmenu', function (props) {
alert('Right click!');
props.event.preventDefault();
});
</pre>
</td>
</tr>
<tr>
<td>doubleClick</td>
<td>
Passes a properties object as returned by the method <ahref="#getEventProperties"><code>Timeline.getEventProperties(event)</code></a>.
</td>
<td>Fired when double clicked inside the Timeline.
<li><code>start</code> (Number): timestamp of the current start of the window.</li>
<li><code>end</code> (Number): timestamp of the current end of the window.</li>
<li><code>byUser</code> (Boolean): change happened because of user drag/zoom.</li>
</ul>
</td>
<td>Fired repeatedly when the timeline window is being changed.
</td>
</tr>
<tr>
<td>rangechanged</td>
<td>
<ul>
<li><code>start</code> (Number): timestamp of the current start of the window.</li>
<li><code>end</code> (Number): timestamp of the current end of the window.</li>
<li><code>byUser</code> (Boolean): change happened because of user drag/zoom.</li>
</ul>
</td>
<td>Fired once after the timeline window has been changed.
</td>
</tr>
<tr>
<td>select</td>
<td>
<ul>
<li><code>items</code>: an array with the ids of the selected items</li>
<li><code>event</code>: the original click event</li>
</ul>
</td>
<td>Fired after the user selects or deselects items by tapping or holding them.
When a use taps an already selected item, the select event is fired again.
Not fired when the method <code>setSelection</code>is executed.
</td>
</tr>
<tr>
<td>timechange</td>
<td>
<ul>
<li><code>id</code> (Number or String): custom time bar id.</li>
<li><code>time</code> (Date): the custom time.</li>
</ul>
</td>
<td>Fired repeatedly when the user is dragging the custom time bar.
Only available when the custom time bar is enabled.
</td>
</tr>
<tr>
<td>timechanged</td>
<td>
<ul>
<li><code>id</code> (Number or String): custom time bar id.</li>
<li><code>time</code> (Date): the custom time.</li>
</ul>
</td>
<td>Fired once after the user has dragged the custom time bar.
Only available when the custom time bar is enabled.
</td>
</tr>
</table>
<h2id="Editing_Items">Editing Items</h2>
<p>
When the Timeline is configured to be editable (both options <code>selectable</code> and <code>editable</code> are <code><code>true</code></code>), the user can:
</p>
<ul>
<li>Select an item by clicking it, and use ctrl+click to or shift+click to select multiple items (when <code>multiselect: true</code>).</li>
<li>Move selected items by dragging them.</li>
<li>Create a new item by double tapping on an empty space.</li>
<li>Create a new range item by dragging on an empty space with the ctrl key down.</li>
<li>Update an item by double tapping it.</li>
<li>Delete a selected item by clicking the delete button on the top right.</li>
</ul>
<p>Option <code>editable</code> accepts a boolean or an object. When <code>editable</code> is a boolean, all manipulation actions will be either enabled or disabled. When <code>editable</code> is an object, one can enable individual manipulation actions:</p>
<preclass="prettyprint lang-js">// enable or disable all manipulation actions
var options = {
editable: true // true or false
};
// enable or disable individual manipulation actions
var options = {
editable: {
add: true, // add new items by double tapping
updateTime: true, // drag items horizontally
updateGroup: true, // drag items from one group to another
remove: true // delete an item by tapping the delete button top right
}
};</pre>
<p>
Editing can be enabled/disabled for specific items. Setting the property <code>editable</code> to <code>true</code> or <code>false</code> on a data item will override the timeline option.
One can specify callback functions to validate changes made by the user. There are a number of callback functions for this purpose:
</p>
<ul>
<li><code>onAdd(item, callback)</code> Fired when a new item is about to be added. If not implemented, the item will be added with default text contents.</li>
<li><code>onUpdate(item, callback)</code> Fired when an item is about to be updated. This function typically has to show a dialog where the user change the item. If not implemented, nothing happens.</li>
<li><code>onMove(item, callback)</code> Fired when an item has been moved. If not implemented, the move action will be accepted.</li>
<li><code>onMoving(item, callback)</code> Fired repeatedly while an item is being moved (dragged). Can be used to adjust the items start, end, and/or group to allowed regions.</li>
<li><code>onRemove(item, callback)</code> Fired when an item is about to be deleted. If not implemented, the item will be always removed.</li>
</ul>
<p>
Each of the callbacks is invoked with two arguments:
</p>
<ul>
<li><code>item</code>: the item being manipulated</li>
<li><code>callback</code>: a callback function which must be invoked to report back. The callback must be invoked as <code>callback(item or null)</code>. Here, <code>item</code> can contain changes to the passed item. Parameter `item` typically contains fields `content`, `start`, and optionally `end`. The type of `start` and `end` is determined by the DataSet type configuration and is `Date` by default. When invoked as <code>callback(null)</code>, the action will be cancelled.</li>
Timeline supports templates to format item contents. Any template engine (such as <ahref="http://handlebarsjs.com/">handlebars</a> or <ahref="http://mustache.github.io/">mustache</a>) can be used, and one can also manually build HTML. In the options, one can provide a template handler. This handler is a function accepting an items data as argument, and outputs formatted HTML:
</p>
<preclass="prettyprint lang-js">var options = {
template: function (item) {
var html = ... // generate HTML markup for this item
var source = document.getElementById('item-template').innerHTML;
var template = Handlebars.compile(source);
</pre>
And then specify the template in the Timeline options
<preclass="prettyprint lang-js">var options = {
template: template
};
</pre>
<h3>Multiple templates</h3>
In order to support multiple templates, the template handler can be extended to switch between different templates, depending on a specific item property:
<preclass="prettyprint lang-js">
var templates = {
template1: Handlebars.compile(...),
template2: Handlebars.compile(...),
template2: Handlebars.compile(...),
...
};
var options = {
template: function (item) {
var template = templates[item.template]; // choose the right template
return template(item); // execute the template
}
};
</pre>
Now the items can be extended with a property <code>template</code>, specifying which template to use for the item.
<h2id="Localization">Localization</h2>
<p>
Timeline can be localized. For localization, Timeline depends largely on the localization of <ahref="http://momentjs.com">moment.js</a>. Locales are not included in vis.js by default. To enable localization, moment.js must be loaded with locales. Moment.js offers a bundle named "moment-with-locales.min.js" for this and there are various alternative ways to load locales.
</p>
<p>
To set a locale for the Timeline, specify the option <code>locale</code>:
</p>
<preclass="prettyprint lang-js">var options = {
locale: 'nl'
};
</pre>
<h3>Create a new locale</h3>
To load a locale into the Timeline not supported by default, one can add a new locale to the option <code>locales</code>:
<preclass="prettyprint lang-js">var options = {
locales: {
// create a new locale (text strings should be replaced with localized strings)
mylocale: {
current: 'current',
time: 'time',
}
},
// use the new locale
locale: 'mylocale'
};
</pre>
<h3id="available-locales">Available locales</h3>
<p>
Timeline comes with support for the following locales:
By default, the Timeline displays time in local time. To display a Timeline in an other time zone or in UTC, the date constructor can be overloaded via the configuration option <code>moment</code>, which by default is the constructor function of moment.js. More information about UTC with moment.js can be found in the docs: <ahref="http://momentjs.com/docs/#/parsing/utc/">http://momentjs.com/docs/#/parsing/utc/</a>.
