jrtechs
/
jrtechs-vis
mirror of https://github.com/jrtechs/vis.git

<html>
<head>  <title>vis.js | timeline documentation</title>
  <link href='css/prettify.css' type='text/css' rel='stylesheet'>  <link href='css/style.css' type='text/css' rel='stylesheet'>
  <script type="text/javascript" src="lib/prettify/prettify.js"></script></head>
<body onload="prettyPrint();"><div id="container">
<h1>Timeline documentation</h1>
<h2 id="Overview">Overview</h2><p>  The Timeline is an interactive visualization chart to visualize data in time.  The data items can take place on a single date, or have a start and end date (a range).  You can freely move and zoom in the timeline by dragging and scrolling in the  Timeline. Items can be created, edited, and deleted in the timeline.  The time scale on the axis is adjusted automatically, and supports scales ranging  from milliseconds to years.</p><p>  Timeline uses regular HTML DOM to render the timeline and items put on the  timeline. This allows for flexible customization using css styling.</p>
<h2 id="Contents">Contents</h2><ul>  <li><a href="#Overview">Overview</a></li>  <li><a href="#Example">Example</a></li>  <li><a href="#Loading">Loading</a></li>  <li><a href="#Data_Format">Data Format</a>    <ul>      <li><a href="#items">Items</a></li>      <li><a href="#groups">Groups</a></li>    </ul>  </li>  <li><a href="#Configuration_Options">Configuration Options</a></li>  <li><a href="#Methods">Methods</a></li>  <li><a href="#Events">Events</a></li>  <li><a href="#Editing_Items">Editing Items</a></li>  <li><a href="#Templates">Templates</a></li>  <li><a href="#Localization">Localization</a></li>  <li><a href="#Styles">Styles</a></li>  <li><a href="#Data_Policy">Data Policy</a></li></ul>
<h2 id="Example">Example</h2><p>  The following code shows how to create a Timeline and provide it with data.  More examples can be found in the <a href="../examples">examples</a> directory.</p>
<pre class="prettyprint lang-html">&lt;!DOCTYPE HTML&gt;&lt;html&gt;&lt;head&gt;  &lt;title&gt;Timeline | Basic demo&lt;/title&gt;
  &lt;style type="text/css"&gt;    body, html {      font-family: sans-serif;    }  &lt;/style&gt;
  &lt;script src="../../dist/vis.js"&gt;&lt;/script&gt;  &lt;link href="../../dist/vis.css" rel="stylesheet" type="text/css" /&gt;&lt;/head&gt;&lt;body&gt;&lt;div id="visualization"&gt;&lt;/div&gt;
&lt;script type="text/javascript"&gt;  // DOM element where the Timeline will be attached  var container = document.getElementById('visualization');
  // Create a DataSet (allows two way data-binding)  var items = new vis.DataSet([    {id: 1, content: 'item 1', start: '2013-04-20'},    {id: 2, content: 'item 2', start: '2013-04-14'},    {id: 3, content: 'item 3', start: '2013-04-18'},    {id: 4, content: 'item 4', start: '2013-04-16', end: '2013-04-19'},    {id: 5, content: 'item 5', start: '2013-04-25'},    {id: 6, content: 'item 6', start: '2013-04-27'}  ]);
  // Configuration for the Timeline  var options = {};
  // Create a Timeline  var timeline = new vis.Timeline(container, items, options);&lt;/script&gt;&lt;/body&gt;&lt;/html&gt;</pre>

<h2 id="Loading">Loading</h2><p>  Install or download the <a href="http://visjs.org" target="_blank">vis.js</a> library.  in a subfolder of your project. Include the libraries script and css files in the  head of your html code:</p>
<pre class="prettyprint lang-html">&lt;script src="vis/dist/vis.js"&gt;&lt;/script&gt;&lt;link href="vis/dist/vis.css" rel="stylesheet" type="text/css" /&gt;</pre>
The constructor of the Timeline is <code>vis.Timeline</code><pre class="prettyprint lang-js">var timeline = new vis.Timeline(container, items, options);</pre>or when using groups:<pre class="prettyprint lang-js">var timeline = new vis.Timeline(container, items, groups, options);</pre>
The constructor accepts four parameters:<ul>  <li>    <code>container</code> is the DOM element in which to create the timeline.  </li>  <li>    <code>items</code> is an Array containing items. The properties of an    item are described in section <a href="#Data_Format">Data Format, items</a>.  </li><li>        <code>groups</code> is an Array containing groups. The properties of a        group are described in section <a href="#groups">Data Format, groups</a>.    </li>  <li>    <code>options</code> is an optional Object containing a name-value map    with options. Options can also be set using the method    <code>setOptions</code>.  </li></ul>
<h2 id="Data_Format">Data Format</h2>
<p>  The timeline can be provided with two types of data:</p><ul>  <li><a href="#items">Items</a> containing a set of items to be displayed in time.</li>  <li><a href="#groups">Groups</a> containing a set of groups used to group items    together.</li></ul>
<h3 id="items">Items</h3><p>  The Timeline uses regular Arrays and Objects as data format.  Data items can contain the properties <code>start</code>,  <code>end</code> (optional), <code>content</code>,  <code>group</code> (optional), <code>className</code> (optional),  and <code>style</code> (optional).</p>
<p>  A table is constructed as:</p>
<pre class="prettyprint lang-js">var items = [  {    start: new Date(2010, 7, 15),    end: new Date(2010, 8, 2),  // end is optional    content: 'Trajectory A'    // Optional: fields 'id', 'type', 'group', 'className', 'style'  }  // more items...]);</pre>
<p>  The item properties are defined as:</p>
<table>  <tr>    <th>Name</th>    <th>Type</th>    <th>Required</th>    <th>Description</th>  </tr>  <tr>    <td>className</td>    <td>String</td>    <td>no</td>    <td>This field is optional. A className can be used to give items      an individual css style. For example, when an item has className      'red', one can define a css style like:      <pre class="prettyprint lang-css">.vis.timeline .red {  color: white;  background-color: red;  border-color: darkred;}</pre>      More details on how to style items can be found in the section      <a href="#Styles">Styles</a>.    </td>  </tr>  <tr>    <td>content</td>    <td>String</td>    <td>yes</td>    <td>The contents of the item. This can be plain text or html code.</td>  </tr>  <tr>    <td>end</td>    <td>Date</td>    <td>no</td>    <td>The end date of the item. The end date is optional, and can be left <code>null</code>.      If end date is provided, the item is displayed as a range.      If not, the item is displayed as a box.</td>  </tr>  <tr>    <td>group</td>    <td>any type</td>    <td>no</td>    <td>This field is optional. When the group column is provided,      all items with the same group are placed on one line.      A vertical axis is displayed showing the groups.      Grouping items can be useful for example when showing availability of multiple      people, rooms, or other resources next to each other.<br>    </td>  </tr>  <tr>    <td>id</td>    <td>String | Number</td>    <td>no</td>    <td>An id for the item. Using an id is not required but highly      recommended. An id is needed when dynamically adding, updating,      and removing items in a DataSet.</td>  </tr>  <tr>    <td>start</td>    <td>Date</td>    <td>yes</td>    <td>The start date of the item, for example <code>new Date(2010,9,23)</code>.</td>  </tr>  <tr>    <td>style</td>    <td>String</td>    <td>no</td>    <td>      A css text string to apply custom styling for an individual item, for      example <code>"color: red; background-color: pink;"</code>.    </td>  </tr>  <tr>    <td>subgroup</td>    <td>String | Number</td>    <td>none</td>    <td>The id of a subgroup.      Groups all items within a group per subgroup, and positions them on the      same height instead of staking them on top of each other. can be ordered      by specifying the option <code>subgroupOrder</code> of a group.    </td>  </tr>  <tr>    <td>title</td>    <td>String</td>    <td>none</td>    <td>Add a title for the item, displayed when holding the mouse on the item.      The title can only contain plain text.    </td>  </tr>  <tr>    <td>type</td>    <td>String</td>    <td>'box'</td>    <td>The type of the item. Can be 'box' (default), 'point', 'range', or 'background'.      Types 'box' and 'point' need a start date, the types 'range' and 'background' needs both a start and end date.    </td>  </tr></table>
<h3 id="groups">Groups</h3><p>  Like the items, groups are regular JavaScript Arrays and Objects.  Using groups, items can be grouped together.  Items are filtered per group, and displayed as
  Group items can contain the properties <code>id</code>,  <code>content</code>, and <code>className</code> (optional).</p><p>  Groups can be applied to a timeline using the method <code>setGroups</code> or supplied in the constructor.  A table with groups can be created like:</p>
<pre class="prettyprint lang-js">var groups = [  {    id: 1,    content: 'Group 1'    // Optional: a field 'className', 'style'  }  // more groups...]);</pre>

<p>  Groups can have the following properties:</p>
<table>  <tr>    <th>Name</th>    <th>Type</th>    <th>Required</th>    <th>Description</th>  </tr>  <tr>    <td>className</td>    <td>String</td>    <td>no</td>    <td>This field is optional. A className can be used to give groups      an individual css style. For example, when a group has className      'red', one can define a css style      <code>        .red {        color: red;        }      </code>.      More details on how to style groups can be found in the section      <a href="#Styles">Styles</a>.    </td>  </tr>  <tr>    <td>content</td>    <td>String</td>    <td>yes</td>    <td>The contents of the group. This can be plain text or html code.</td>  </tr>  <tr>    <td>id</td>    <td>String | Number</td>    <td>yes</td>    <td>An id for the group. The group will display all items having a      property <code>group</code> which matches the <code>id</code>      of the group.</td>  </tr>  <tr>    <td>style</td>    <td>String</td>    <td>no</td>    <td>      A css text string to apply custom styling for an individual group label, for      example <code>"color: red; background-color: pink;"</code>.    </td>  </tr>  <tr>    <td>subgroupOrder</td>    <td>String | Function</td>    <td>none</td>    <td>Order the subgroups by a field name or custom sort function.      By default, groups are ordered by first-come, first-show.    </td>  </tr>  <tr>    <td>title</td>    <td>String</td>    <td>none</td>    <td>A title for the group, displayed when holding the mouse on the groups label.      The title can only contain plain text.    </td>  </tr></table>


<h2 id="Configuration_Options">Configuration Options</h2>
<p>  Options can be used to customize the timeline.  Options are defined as a JSON object. All options are optional.</p>
<pre class="prettyprint lang-js">var options = {  width: '100%',  height: '30px',  margin: {    item: 20  }};</pre>
<p>  The following options are available.</p>
<table><tr>    <th>Name</th>    <th>Type</th>    <th>Default</th>    <th>Description</th></tr>
<tr>    <td>align</td>    <td>String</td>    <td>"center"</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>true</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>false</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>dataAttributes</td>  <td>Array[String] | 'all'</td>  <td>false</td>  <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></tr>

<tr>    <td>editable</td>    <td>Boolean | Object</td>    <td>false</td>    <td>If true, the items in the timeline can be manipulated. Only applicable when option <code>selectable</code> is <code>true</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 <a href="#Editing_Items">Editing Items</a> for a detailed explanation.    </td></tr>
<tr>    <td>editable.add</td>    <td>Boolean</td>    <td>false</td>    <td>If true, new items can be created by double tapping an empty space in the Timeline. See section <a href="#Editing_Items">Editing Items</a> for a detailed explanation.</td></tr>
<tr>    <td>editable.remove</td>    <td>Boolean</td>    <td>false</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 <a href="#Editing_Items">Editing Items</a> for a detailed explanation.</td></tr>
<tr>    <td>editable.updateGroup</td>    <td>Boolean</td>    <td>false</td>    <td>If true, items can be dragged from one group to another. Only applicable when the Timeline has groups. See section <a href="#Editing_Items">Editing Items</a> for a detailed explanation.</td></tr>
<tr>    <td>editable.updateTime</td>    <td>Boolean</td>    <td>false</td>    <td>If true, items can be dragged to another moment in time. See section <a href="#Editing_Items">Editing Items</a> for a detailed explanation.</td></tr>
<tr>    <td>end</td>    <td>Date | Number | String</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:      <pre class="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 <a href="http://momentjs.com/docs/#/displaying/format/">docs of moment.js</a>.    </td></tr>
<tr>    <td>groupOrder</td>    <td>String | Function</td>    <td>none</td>    <td>Order the groups by a field name or custom sort function.        By default, groups are not ordered.    </td></tr>
<tr>    <td>height</td>    <td>Number | 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        and set repeat to weekly.    </td></tr><tr>    <td>locale</td>    <td>String</td>    <td>none</td>    <td>Select a locale for the Timeline. See section <a href="#Localization">Localization</a> for more information.</td></tr>
<tr>    <td>locales</td>    <td>Object</td>    <td>none</td>    <td>A map with i18n locales. See section <a href="#Localization">Localization</a> for more information.</td></tr>
<tr>    <td>margin.axis</td>    <td>Number</td>    <td>20</td>    <td>The minimal margin in pixels between items and the time axis.</td></tr>
<tr>    <td>margin.item</td>    <td>Number</td>    <td>10</td>    <td>The minimal margin in pixels between items in both horizontal and vertical direction.</td></tr>
<tr>    <td>margin.item.horizontal</td>    <td>Number</td>    <td>10</td>    <td>The minimal horizontal margin in pixels between items.</td></tr>
<tr>    <td>margin.item.vertical</td>    <td>Number</td>    <td>10</td>    <td>The minimal vertical margin in pixels between items.</td></tr>
<tr>    <td>max</td>    <td>Date | Number | String</td>    <td>none</td>    <td>Set a maximum Date for the visible range.        It will not be possible to move beyond this maximum.    </td></tr>
<tr>    <td>maxHeight</td>    <td>Number | String</td>    <td>none</td>    <td>Specifies the maximum height for the Timeline. Can be a number in pixels or a string like "300px".</td></tr>
<tr>    <td>min</td>    <td>Date | Number | String</td>    <td>none</td>    <td>Set a minimum Date for the visible range.        It will not be possible to move beyond this minimum.    </td></tr>
<tr>    <td>minHeight</td>    <td>Number | String</td>    <td>none</td>    <td>Specifies the minimum height for the Timeline. Can be a number in pixels or a string like "300px".</td></tr>
<tr>    <td>moveable</td>    <td>Boolean</td>    <td>true</td>    <td>        Specifies whether the Timeline can be moved and zoomed by dragging the window.        See also option <code>zoomable</code>.    </td></tr>
<tr>    <td>onAdd</td>    <td>Function</td>    <td>none</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 <a href="#Editing_Items">Editing Items</a> for more information. Only applicable when both options <code>selectable</code> and <code>editable.add</code> are set <code>true</code>.    </td></tr>
<tr>    <td>onUpdate</td>    <td>Function</td>    <td>none</td>    <td>Callback function triggered when an item is about to be updated, when the user double taps an item in the Timeline. See section <a href="#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>true</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 <a href="#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>true</code>.    </td></tr>
<tr>    <td>onMoving</td>    <td>Function</td>    <td>none</td>    <td>Callback function triggered repeatedly when an item is being moved. See section <a href="#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>true</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 <a href="#Editing_Items">Editing Items</a> for more information. Only applicable when both options <code>selectable</code> and <code>editable.remove</code> are set <code>true</code>.    </td></tr>
<!-- TODO: cleanup option order
<tr>  <td>order</td>  <td>Function</td>  <td>none</td>  <td>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 parameters, both of type    `vis.components.items.Item`.  </td></tr>-->
<tr>    <td>orientation</td>    <td>String</td>    <td>'bottom'</td>    <td>Orientation of the timeline: 'top' or 'bottom' (default). If orientation is 'bottom', the time axis is drawn at the bottom, and if 'top', the axis is drawn on top.</td></tr>
<tr>    <td>padding</td>    <td>Number</td>    <td>5</td>    <td>The padding of items, needed to correctly calculate the size        of item ranges. Must correspond with the css of items, for example when setting <code>options.padding=10</code>, corresponding css is:  <pre class="prettyprint lang-css">.vis.timeline .item {  padding: 10px;}</pre>    </td></tr>
<tr>    <td>selectable</td>    <td>Boolean</td>    <td>true</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 <a href="#Events">Events</a>).</td></tr>
<tr>    <td>showCurrentTime</td>    <td>boolean</td>    <td>true</td>    <td>Show a vertical bar at the current time.</td></tr>
<tr>    <td>showCustomTime</td>    <td>boolean</td>    <td>false</td>    <td>Show a vertical bar displaying a custom time. This line can be dragged by the user. The custom time can be utilized to show a state in the past or in the future. When the custom time bar is dragged by the user, the event <code>timechange</code> is fired repeatedly. After the bar is dragged, the event <code>timechanged</code> is fired once.</td></tr>
<tr><tr>    <td>showMajorLabels</td>    <td>boolean</td>    <td>true</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>false</code>, no major labels        are shown.</td></tr>
<tr>    <td>showMinorLabels</td>    <td>boolean</td>    <td>true</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>false</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>true</td>    <td>If true (default), items will be stacked on top of each other such that they do not overlap.</td></tr>
<tr>    <td>start</td>    <td>Date | Number | String</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 <a href="#Templates">Templates</a> for a detailed explanation.</td></tr>
<tr>  <td>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:  <pre class="prettyprint lang-js">var options = {  timeAxis: {scale: 'minute', step: 5}}</pre>  </td></tr>
<tr>    <td>timeAxis.step</td>    <td>number</td>    <td>1</td>    <td>      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</td>    <td>'100%'</td>    <td>The width of the timeline in pixels or as a percentage.</td></tr>
<tr>    <td>zoomable</td>    <td>Boolean</td>    <td>true</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>true</code>.    </td></tr>
<tr>    <td>zoomMax</td>    <td>Number</td>    <td>315360000000000</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>10</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>
<h2 id="Methods">Methods</h2><p>  The Timeline supports the following methods.</p>
<table>  <tr>    <th>Method</th>    <th>Return Type</th>    <th>Description</th>  </tr>
  <tr>    <td>clear([what])</td>    <td>none</td>    <td>      Clear the Timeline. An object can be passed specifying which sections to clear: items, groups,      and/or options. By Default, items, groups and options are cleared, i.e. <code>what = {items: true, groups: true, options: true}</code>. Example usage:
<pre class="prettyprint lang-js">timeline.clear();                // clear items, groups, and optionstimeline.clear({options: true}); // clear options only</pre>    </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>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</li>      </ul>    </td>  </tr>
  <tr>    <td>focus(id | 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>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</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()</td>    <td>Date</td>    <td>Retrieve the custom time. Only applicable when the option <code>showCustomTime</code> is true.    </td>  </tr>
  <tr>    <td>getSelection()</td>    <td>Number[]</td>    <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>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</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 <a href="#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 <a href="#Events">Events for more information</a>.</td>  </tr>
  <tr>    <td>redraw()</td>    <td>none</td>    <td>Force a redraw of the Timeline. Can be useful to manually redraw when option autoResize=false.    </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)</td>    <td>none</td>    <td>Adjust the custom time bar. Only applicable when the option <code>showCustomTime</code> is true. <code>time</code> can be a Date object, numeric timestamp, or ISO date string.    </td>  </tr>
  <tr>    <td>setGroups(groups)</td>    <td>none</td>    <td>Set a data set with groups for the Timeline.      <code>groups</code> can be an Array with Objects,      a DataSet, or a DataView. For each of the groups, the items of the      timeline are filtered on the property <code>group</code>, which      must correspond with the id of the group.    </td>  </tr>
  <tr>    <td>setItems(items)</td>    <td>none</td>    <td>Set a data set with items for the Timeline.      <code>items</code> can be an Array with Objects,      a DataSet, or a DataView.    </td>  </tr>
  <tr>    <td>setOptions(options)</td>    <td>none</td>    <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 | 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>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms. Only applicable when option focus is true.</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>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</li>      </ul>    </td>  </tr>
</table>

<h2 id="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>
<pre class="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>:</p>
<pre class="prettyprint lang-js">function onSelect (properties) {  alert('selected items: ' + properties.nodes);}
// add event listenertimeline.on('select', onSelect);
// do stuff...
// remove event listenertimeline.off('select', onSelect);</pre>

<p>  The following events are available.</p>
<table>  <colgroup>    <col style="width: 20%;">    <col style="width: 40%;">    <col style="width: 40%;">  </colgroup>
  <tr>    <th>name</th>    <th>Description</th>    <th>Properties</th>  </tr>    <tr>        <td>finishedRedraw</td>        <td>Fired after a redraw is complete. When moving the timeline around, this could be fired frequently.        </td>        <td>            none.        </td>    </tr>
    <tr>    <td>rangechange</td>    <td>Fired repeatedly when the timeline window is being changed.    </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>  </tr>
  <tr>    <td>rangechanged</td>    <td>Fired once after the timeline window has been changed.    </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>  </tr>
  <tr>    <td>select</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>    <td>      <ul>        <li><code>items</code>: an array with the ids of the selected items</li>      </ul>    </td>  </tr>
  <tr>    <td>timechange</td>    <td>Fired repeatedly when the user is dragging the custom time bar.      Only available when the custom time bar is enabled.    </td>    <td>      <ul>        <li><code>time</code> (Date): the current time.</li>      </ul>    </td>  </tr>
  <tr>    <td>timechanged</td>    <td>Fired once after the user has dragged the custom time bar.      Only available when the custom time bar is enabled.    </td>    <td>      <ul>        <li><code>time</code> (Date): the current time.</li>      </ul>    </td>  </tr>
</table>
<h2 id="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>true</code>), the user can move items by dragging them, can create a new item by double tapping on an empty space, can update an item by double tapping it, and can delete a selected item by clicking the delete button on the top right.</p>
<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>
<pre class="prettyprint lang-js">// enable or disable all manipulation actionsvar options = {  editable: true       // true or false};
// enable or disable individual manipulation actionsvar 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>  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 | 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></ul>
<p>  Example code:</p>
<pre class="prettyprint lang-js">var options = {  onUpdate: function (item, callback) {    item.content = prompt('Edit items text:', item.content);    if (item.content != null) {      callback(item); // send back adjusted item    }    else {      callback(null); // cancel updating the item    }  }};</pre>
A full example is available here: <a href="../examples/timeline/08_edit_items.html">08_edit_items.html</a>.

<h2 id="Templates">Templates</h2>
<p>  Timeline supports templates to format item contents. Any template engine (such as <a href="http://handlebarsjs.com/">handlebars</a> or <a href="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>
<pre class="prettyprint lang-js">var options = {  template: function (item) {    var html = ... // generate HTML markup for this item    return html;  }};</pre>
<h3>Create HTML manually</h3>
The HTML for an item can be created manually:
<pre class="prettyprint lang-js">var options = {  template: function (item) {    return '&lt;h1&gt;' + item.header + '&lt;/h1&gt;&lt;p&gt;' + item.description + '&lt;/p&gt;';  }};</pre>
<h3>Using a template engine</h3>
Using <a href="http://handlebarsjs.com/">handlebars</a>, one can write the template in HTML:
<pre class="prettyprint lang-html">&lt;script id="item-template" type="text/x-handlebars-template"&gt;  &lt;h1&gt;{{header}}&lt;/h1&gt;  &lt;p&gt;{{description}}&lt;/p&gt;&lt;/script&gt;</pre>
Compile the template:
<pre class="prettyprint lang-js">var source = document.getElementById('item-template').innerHTML;var template = Handlebars.compile(source);</pre>
And then specify the template in the Timeline options
<pre class="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:
<pre class="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.

<h2 id="Localization">Localization</h2><p>  Timeline can be localized. For localization, Timeline depends largely on the localization of <a href="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>
<pre class="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>:
<pre class="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>
<h3 id="available-locales">Available locales</h3>
<p>  Timeline comes with support for the following locales:</p>
<table>  <tr><th>Language</th><th>Code</th></tr>  <tr>    <td>English</td>    <td>      <code>en</code><br>      <code>en_EN</code><br>      <code>en_US</code>    </td>  </tr>  <tr>    <td>Dutch</td>    <td>      <code>nl</code><br>      <code>nl_NL</code><br>      <code>nl_BE</code>    </td>  </tr></table>

<h2 id="Styles">Styles</h2><p>  All parts of the Timeline have a class name and a default css style.  The styles can be overwritten, which enables full customization of the layout  of the Timeline.</p>
<p>For example, to change the border and background color of all items, include the  following code inside the head of your html code or in a separate stylesheet.</p><pre class="prettyprint lang-html">&lt;style&gt;  .vis.timeline .item {    border-color: orange;    background-color: yellow;  }&lt;/style&gt;</pre>
<h3 id="Grid_Backgrounds">Grid Backgrounds</h3><p>  The background grid of the time axis can be styled, for example to highlight  weekends or to create grids with an alternating white/lightgray background.</p><p>  Depending on the zoom level, the grids get certain css classes attached.  The following classes are available:</p>
<table>  <tr>    <th>Description</th><th>values</th>  </tr>  <tr>    <td>Alternating columns</td><td><code>even</code>, <code>odd</code></td>  </tr>  <tr>    <td>Current date</td><td><code>today</code>, <code>tomorrow</code>, <code>yesterday</code>, <code>current-week</code>, <code>current-month</code>, <code>current-year</code></td>  </tr>  <tr>    <td>Hours</td><td><code>0h</code>, <code>1h</code>, ..., <code>23h</code></td>  </tr>  <tr>    <td>Grouped hours</td><td><code>0-4h</code> to <code>20-24h</code></td>  </tr>  <tr>    <td>Weekday</td><td><code>monday</code>, <code>tuesday</code>, <code>wednesday</code>, <code>thursday</code>, <code>friday</code>, <code>saturday</code>, <code>sunday</code></td>  </tr>  <tr>    <td>Days</td><td><code>date1</code>, <code>date2</code>, ..., <code>date31</code></td>  </tr>  <tr>    <td>Months</td><td><code>januari</code>, <code>februari</code>, <code>march</code>, <code>april</code>, <code>may</code>, <code>june</code>, <code>july</code>, <code>august</code>, <code>september</code>, <code>october</code>, <code>november</code>, <code>december</code></td>  </tr>  <tr>    <td>Years</td><td><code>year2014</code>, <code>year2015</code>, ...</td>  </tr></table>
<p>Examples:</p>
  <pre class="prettyprint lang-html">&lt;style&gt;  /* alternating column backgrounds */  .vis.timeline .timeaxis .grid.odd {    background: #f5f5f5;  }
  /* gray background in weekends, white text color */  .vis.timeline .timeaxis .grid.saturday,  .vis.timeline .timeaxis .grid.sunday {    background: gray;  }  .vis.timeline .timeaxis .text.saturday,  .vis.timeline .timeaxis .text.sunday {    color: white;  }&lt;/style&gt;</pre>

<h2 id="Data_Policy">Data Policy</h2><p>  All code and data is processed and rendered in the browser.  No data is sent to any server.</p>
</div></body></html>