vis.js is a dynamic, browser-based visualization library
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

765 lines
20 KiB

  1. <html>
  2. <head>
  3. <title>vis.js | timeline documentation</title>
  4. <link href='css/prettify.css' type='text/css' rel='stylesheet'>
  5. <link href='css/style.css' type='text/css' rel='stylesheet'>
  6. <script type="text/javascript" src="lib/prettify/prettify.js"></script>
  7. </head>
  8. <body onload="prettyPrint();">
  9. <div id="container">
  10. <h1>Timeline documentation</h1>
  11. <h2 id="Overview">Overview</h2>
  12. <p>
  13. The Timeline is an interactive visualization chart to visualize data in time.
  14. The data items can take place on a single date, or have a start and end date (a range).
  15. You can freely move and zoom in the timeline by dragging and scrolling in the
  16. Timeline. Items can be created, edited, and deleted in the timeline.
  17. The time scale on the axis is adjusted automatically, and supports scales ranging
  18. from milliseconds to years.
  19. </p>
  20. <h2 id="Contents">Contents</h2>
  21. <ul>
  22. <li><a href="#Overview">Overview</a></li>
  23. <li><a href="#Example">Example</a></li>
  24. <li><a href="#Loading">Loading</a></li>
  25. <li><a href="#Data_Format">Data Format</a>
  26. <ul>
  27. <li><a href="#items">Items</a></li>
  28. <li><a href="#groups">Groups</a></li>
  29. </ul>
  30. </li>
  31. <li><a href="#Configuration_Options">Configuration Options</a></li>
  32. <li><a href="#Methods">Methods</a></li>
  33. <li><a href="#Events">Events</a></li>
  34. <li><a href="#Styles">Styles</a></li>
  35. <li><a href="#Data_Policy">Data Policy</a></li>
  36. </ul>
  37. <h2 id="Example">Example</h2>
  38. <p>
  39. The following code shows how to create a Timeline and provide it with data.
  40. More examples can be found in the <a href="../examples">examples</a> directory.
  41. </p>
  42. <pre class="prettyprint lang-html">&lt;!DOCTYPE HTML&gt;
  43. &lt;html&gt;
  44. &lt;head&gt;
  45. &lt;title&gt;Timeline | Basic demo&lt;/title&gt;
  46. &lt;style type="text/css"&gt;
  47. body, html {
  48. font-family: sans-serif;
  49. }
  50. &lt;/style&gt;
  51. &lt;script src="../../dist/vis.js"&gt;&lt;/script&gt;
  52. &lt;link href="../../dist/vis.css" rel="stylesheet" type="text/css" /&gt;
  53. &lt;/head&gt;
  54. &lt;body&gt;
  55. &lt;div id="visualization"&gt;&lt;/div&gt;
  56. &lt;script type="text/javascript"&gt;
  57. var container = document.getElementById('visualization');
  58. var items = [
  59. {id: 1, content: 'item 1', start: '2013-04-20'},
  60. {id: 2, content: 'item 2', start: '2013-04-14'},
  61. {id: 3, content: 'item 3', start: '2013-04-18'},
  62. {id: 4, content: 'item 4', start: '2013-04-16', end: '2013-04-19'},
  63. {id: 5, content: 'item 5', start: '2013-04-25'},
  64. {id: 6, content: 'item 6', start: '2013-04-27'}
  65. ];
  66. var options = {};
  67. var timeline = new vis.Timeline(container, items, options);
  68. &lt;/script&gt;
  69. &lt;/body&gt;
  70. &lt;/html&gt;
  71. </pre>
  72. <h2 id="Loading">Loading</h2>
  73. <p>
  74. Install or download the <a href="http://visjs.org" target="_blank">vis.js</a> library.
  75. in a subfolder of your project. Include the libraries script and css files in the
  76. head of your html code:
  77. </p>
  78. <pre class="prettyprint lang-html">
  79. &lt;script src="vis/dist/vis.js"&gt;&lt;/script&gt;
  80. &lt;link href="vis/dist/vis.css" rel="stylesheet" type="text/css" /&gt;
  81. </pre>
  82. The constructor of the Timeline is <code>vis.Timeline</code>
  83. <pre class="prettyprint lang-js">var timeline = new vis.Timeline(container, items, options);</pre>
  84. The constructor accepts three parameters:
  85. <ul>
  86. <li>
  87. <code>container</code> is the DOM element in which to create the graph.
  88. </li>
  89. <li>
  90. <code>items</code> is an Array containing items. The properties of an
  91. item are described in section <a href="#Data_Format">Data Format</a>.
  92. </li>
  93. <li>
  94. <code>options</code> is an optional Object containing a name-value map
  95. with options. Options can also be set using the method
  96. <code>setOptions</code>.
  97. </li>
  98. </ul>
  99. <h2 id="Data_Format">Data Format</h2>
  100. <p>
  101. The timeline can be provided with two types of data:
  102. </p>
  103. <ul>
  104. <li><a href="#items">Items</a> containing a set of items to be displayed in time.</li>
  105. <li><a href="#groups">Groups</a> containing a set of groups used to group items
  106. together.</li>
  107. </ul>
  108. <h3 id="items">Items</h3>
  109. <p>
  110. The Timeline uses regular Arrays and Objects as data format.
  111. Data items can contain the properties <code>start</code>,
  112. <code>end</code> (optional), <code>content</code>,
  113. <code>group</code> (optional), and <code>className</code> (optional).
  114. </p>
  115. <p>
  116. A table is constructed as:
  117. </p>
  118. <pre class="prettyprint lang-js">
  119. var items = [
  120. {
  121. start: new Date(2010, 7, 15),
  122. end: new Date(2010, 8, 2), // end is optional
  123. content: 'Trajectory A'
  124. // Optional: fields 'id', 'type', 'group', 'className'
  125. }
  126. // more items...
  127. ]);
  128. </pre>
  129. <p>
  130. The item properties are defined as:
  131. </p>
  132. <table>
  133. <tr>
  134. <th>Name</th>
  135. <th>Type</th>
  136. <th>Required</th>
  137. <th>Description</th>
  138. </tr>
  139. <tr>
  140. <td>id</td>
  141. <td>String | Number</td>
  142. <td>no</td>
  143. <td>An id for the item. Using an id is not required but highly
  144. recommended. An id is needed when dynamically adding, updating,
  145. and removing items in a DataSet.</td>
  146. </tr>
  147. <tr>
  148. <td>start</td>
  149. <td>Date</td>
  150. <td>yes</td>
  151. <td>The start date of the item, for example <code>new Date(2010,09,23)</code>.</td>
  152. </tr>
  153. <tr>
  154. <td>end</td>
  155. <td>Date</td>
  156. <td>no</td>
  157. <td>The end date of the item. The end date is optional, and can be left <code>null</code>.
  158. If end date is provided, the item is displayed as a range.
  159. If not, the item is displayed as a box.</td>
  160. </tr>
  161. <tr>
  162. <td>content</td>
  163. <td>String</td>
  164. <td>yes</td>
  165. <td>The contents of the item. This can be plain text or html code.</td>
  166. </tr>
  167. <tr>
  168. <td>type</td>
  169. <td>String</td>
  170. <td>'box'</td>
  171. <td>The type of the item. Can be 'box' (default), 'range', or 'point'.
  172. <!-- TODO: describe rangeoverflow -->
  173. </td>
  174. </tr>
  175. <tr>
  176. <td>group</td>
  177. <td>any type</td>
  178. <td>no</td>
  179. <td>This field is optional. When the group column is provided,
  180. all items with the same group are placed on one line.
  181. A vertical axis is displayed showing the groups.
  182. Grouping items can be useful for example when showing availability of multiple
  183. people, rooms, or other resources next to each other.<br>
  184. </td>
  185. </tr>
  186. <tr>
  187. <td>className</td>
  188. <td>String</td>
  189. <td>no</td>
  190. <td>This field is optional. A className can be used to give items
  191. an individual css style. For example, when an item has className
  192. 'red', one can define a css style
  193. <code>
  194. .red {
  195. background-color: red;
  196. border-color: dark-red;
  197. }
  198. </code>.
  199. More details on how to style items can be found in the section
  200. <a href="#Styles">Styles</a>.
  201. </td>
  202. </tr>
  203. </table>
  204. <h3 id="groups">Groups</h3>
  205. <p>
  206. Like the items, groups are regular JavaScript Arrays and Objects.
  207. Using groups, items can be grouped together.
  208. Items are filtered per group, and displayed as
  209. Group items can contain the properties <code>id</code>,
  210. <code>content</code>, and <code>className</code> (optional).
  211. </p>
  212. <p>
  213. Groups can be applied to a timeline using the method <code>setGroups</code>.
  214. A table with groups can be created like:
  215. </p>
  216. <pre class="prettyprint lang-js">
  217. var groups = [
  218. {
  219. id: 1,
  220. content: 'Group 1'
  221. // Optional: a field 'className'
  222. }
  223. // more groups...
  224. ]);
  225. </pre>
  226. <p>
  227. Groups can have the following properties:
  228. </p>
  229. <table>
  230. <tr>
  231. <th>Name</th>
  232. <th>Type</th>
  233. <th>Required</th>
  234. <th>Description</th>
  235. </tr>
  236. <tr>
  237. <td>id</td>
  238. <td>String | Number</td>
  239. <td>yes</td>
  240. <td>An id for the group. The group will display all items having a
  241. property <code>group</code> which matches the <code>id</code>
  242. of the group.</td>
  243. </tr>
  244. <tr>
  245. <td>content</td>
  246. <td>String</td>
  247. <td>yes</td>
  248. <td>The contents of the group. This can be plain text or html code.</td>
  249. </tr>
  250. <tr>
  251. <td>className</td>
  252. <td>String</td>
  253. <td>no</td>
  254. <td>This field is optional. A className can be used to give groups
  255. an individual css style. For example, when a group has className
  256. 'red', one can define a css style
  257. <code>
  258. .red {
  259. color: red;
  260. }
  261. </code>.
  262. More details on how to style groups can be found in the section
  263. <a href="#Styles">Styles</a>.
  264. </td>
  265. </tr>
  266. </table>
  267. <h2 id="Configuration_Options">Configuration Options</h2>
  268. <p>
  269. Options can be used to customize the timeline.
  270. Options are defined as a JSON object. All options are optional.
  271. </p>
  272. <pre class="prettyprint lang-js">
  273. var options = {
  274. width: '100%',
  275. height: '30px'
  276. };
  277. </pre>
  278. <p>
  279. The following options are available.
  280. </p>
  281. <table>
  282. <tr>
  283. <th>Name</th>
  284. <th>Type</th>
  285. <th>Default</th>
  286. <th>Description</th>
  287. </tr>
  288. <tr>
  289. <td>align</td>
  290. <td>String</td>
  291. <td>"center"</td>
  292. <td>Alignment of items with type 'box'. Available values are
  293. 'center' (default), 'left', or 'right').</td>
  294. </tr>
  295. <tr>
  296. <td>autoResize</td>
  297. <td>boolean</td>
  298. <td>true</td>
  299. <td>If true, the Timeline will automatically detect when its
  300. container is resized, and redraw itself accordingly.</td>
  301. </tr>
  302. <tr>
  303. <td>editable</td>
  304. <td>Boolean</td>
  305. <td>true</td>
  306. <td>If true, the items on the timeline can be dragged.</td>
  307. <!-- TODO: update documentation as soon as items can be deleted, created, changed -->
  308. </tr>
  309. <tr>
  310. <td>end</td>
  311. <td>Date | Number | String</td>
  312. <td>none</td>
  313. <td>The initial end date for the axis of the timeline.
  314. If not provided, the latest date present in the items set is taken as
  315. end date.</td>
  316. </tr>
  317. <tr>
  318. <td>groupOrder</td>
  319. <td>String | Function</td>
  320. <td>none</td>
  321. <td>Order the groups by a field name or custom sort function.
  322. By default, groups are not ordered.
  323. </td>
  324. </tr>
  325. <tr>
  326. <td>height</td>
  327. <td>String</td>
  328. <td>none</td>
  329. <td>The height of the timeline in pixels or as a percentage.
  330. When height is undefined or null, the height of the timeline is automatically
  331. adjusted to fit the contents.
  332. It is possible to set a maximum height using option <code>maxHeight</code>
  333. to prevent the timeline from getting too high in case of automatically
  334. calculated height.
  335. </td>
  336. </tr>
  337. <tr>
  338. <td>margin.axis</td>
  339. <td>Number</td>
  340. <td>20</td>
  341. <td>The minimal margin in pixels between items and the time axis.</td>
  342. </tr>
  343. <tr>
  344. <td>margin.item</td>
  345. <td>Number</td>
  346. <td>10</td>
  347. <td>The minimal margin in pixels between items.</td>
  348. </tr>
  349. <tr>
  350. <td>max</td>
  351. <td>Date | Number | String</td>
  352. <td>none</td>
  353. <td>Set a maximum Date for the visible range.
  354. It will not be possible to move beyond this maximum.
  355. </td>
  356. </tr>
  357. <tr>
  358. <td>maxHeight</td>
  359. <td>Number</td>
  360. <td>none</td>
  361. <td>Specifies a maximum height for the Timeline in pixels.
  362. </td>
  363. </tr>
  364. <tr>
  365. <td>min</td>
  366. <td>Date | Number | String</td>
  367. <td>none</td>
  368. <td>Set a minimum Date for the visible range.
  369. It will not be possible to move beyond this minimum.
  370. </td>
  371. </tr>
  372. <tr>
  373. <td>order</td>
  374. <td>Function</td>
  375. <td>none</td>
  376. <td>Provide a custom sort function to order the items. The order of the
  377. items is determining the way they are stacked. The function
  378. order is called with two parameters, both of type
  379. `vis.components.items.Item`.
  380. </td>
  381. </tr>
  382. <tr>
  383. <td>orientation</td>
  384. <td>String</td>
  385. <td>'bottom'</td>
  386. <td>Orientation of the timeline: 'top' or 'bottom' (default).
  387. If orientation is 'bottom', the time axis is drawn at the bottom,
  388. and if 'top', the axis is drawn on top.</td>
  389. </tr>
  390. <tr>
  391. <td>padding</td>
  392. <td>Number</td>
  393. <td>5</td>
  394. <td>The padding of items, needed to correctly calculate the size
  395. of item ranges. Must correspond with the css of item ranges.</td>
  396. </tr>
  397. <tr>
  398. <td>selectable</td>
  399. <td>Boolean</td>
  400. <td>true</td>
  401. <td>If true, the items on the timeline can be selected.</td>
  402. </tr>
  403. <tr>
  404. <td>showCurrentTime</td>
  405. <td>boolean</td>
  406. <td>false</td>
  407. <td>Show a vertical bar at the current time.</td>
  408. </tr>
  409. <tr>
  410. <td>showCustomTime</td>
  411. <td>boolean</td>
  412. <td>false</td>
  413. <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>
  414. </tr>
  415. <tr>
  416. <tr>
  417. <td>showMajorLabels</td>
  418. <td>boolean</td>
  419. <td>true</td>
  420. <td>By default, the timeline shows both minor and major date labels on the
  421. time axis.
  422. For example the minor labels show minutes and the major labels show hours.
  423. When <code>showMajorLabels</code> is <code>false</code>, no major labels
  424. are shown.</td>
  425. </tr>
  426. <tr>
  427. <td>showMinorLabels</td>
  428. <td>boolean</td>
  429. <td>true</td>
  430. <td>By default, the timeline shows both minor and major date labels on the
  431. time axis.
  432. For example the minor labels show minutes and the major labels show hours.
  433. When <code>showMinorLabels</code> is <code>false</code>, no minor labels
  434. are shown. When both <code>showMajorLabels</code> and
  435. <code>showMinorLabels</code> are false, no horizontal axis will be
  436. visible.</td>
  437. </tr>
  438. <tr>
  439. <td>start</td>
  440. <td>Date | Number | String</td>
  441. <td>none</td>
  442. <td>The initial start date for the axis of the timeline.
  443. If not provided, the earliest date present in the events is taken as start date.</td>
  444. </tr>
  445. <tr>
  446. <td>type</td>
  447. <td>String</td>
  448. <td>'box'</td>
  449. <td>Specifies the type for the timeline items. Choose from 'dot' or 'point'.
  450. Note that individual items can override this global type.
  451. </td>
  452. </tr>
  453. <tr>
  454. <td>width</td>
  455. <td>String</td>
  456. <td>'100%'</td>
  457. <td>The width of the timeline in pixels or as a percentage.</td>
  458. </tr>
  459. <tr>
  460. <td>zoomMax</td>
  461. <td>Number</td>
  462. <td>315360000000000</td>
  463. <td>Set a maximum zoom interval for the visible range in milliseconds.
  464. It will not be possible to zoom out further than this maximum.
  465. Default value equals about 10000 years.
  466. </td>
  467. </tr>
  468. <tr>
  469. <td>zoomMin</td>
  470. <td>Number</td>
  471. <td>10</td>
  472. <td>Set a minimum zoom interval for the visible range in milliseconds.
  473. It will not be possible to zoom in further than this minimum.
  474. </td>
  475. </tr>
  476. </table>
  477. <h2 id="Methods">Methods</h2>
  478. <p>
  479. The Timeline supports the following methods.
  480. </p>
  481. <table>
  482. <tr>
  483. <th>Method</th>
  484. <th>Return Type</th>
  485. <th>Description</th>
  486. </tr>
  487. <tr>
  488. <td>getCustomTime()</td>
  489. <td>Date</td>
  490. <td>Retrieve the custom time. Only applicable when the option <code>showCustomTime</code> is true.
  491. </td>
  492. </tr>
  493. <tr>
  494. <td>setCustomTime(time)</td>
  495. <td>none</td>
  496. <td>Adjust the custom time bar. Only applicable when the option <code>showCustomTime</code> is true. <code>time</code> is a Date object.
  497. </td>
  498. </tr>
  499. <tr>
  500. <td>getSelection()</td>
  501. <td>ids</td>
  502. <td>Get an array with the ids of the currently selected items.</td>
  503. </tr>
  504. <tr>
  505. <td>on(event, callback)</td>
  506. <td>none</td>
  507. <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>
  508. </tr>
  509. <tr>
  510. <td>off(event, callback)</td>
  511. <td>none</td>
  512. <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>
  513. </tr>
  514. <tr>
  515. <td>setGroups(groups)</td>
  516. <td>none</td>
  517. <td>Set a data set with groups for the Timeline.
  518. <code>groups</code> can be an Array with Objects,
  519. a DataSet, or a DataView. For each of the groups, the items of the
  520. timeline are filtered on the property <code>group</code>, which
  521. must correspond with the id of the group.
  522. </td>
  523. </tr>
  524. <tr>
  525. <td>setItems(items)</td>
  526. <td>none</td>
  527. <td>Set a data set with items for the Timeline.
  528. <code>items</code> can be an Array with Objects,
  529. a DataSet, or a DataView.
  530. </td>
  531. </tr>
  532. <tr>
  533. <td>setOptions(options)</td>
  534. <td>none</td>
  535. <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.
  536. </td>
  537. </tr>
  538. <tr>
  539. <td>setSelection([ids])</td>
  540. <td>none</td>
  541. <td>Select or deselect items. Currently selected items will be unselected.
  542. </td>
  543. </tr>
  544. </table>
  545. <h2 id="Events">Events</h2>
  546. <p>
  547. Timeline fires events when changing the visible window by dragging, when
  548. selecting items, and when dragging the custom time bar.
  549. </p>
  550. <p>
  551. Here an example on how to listen for a <code>select</code> event.
  552. </p>
  553. <pre class="prettyprint lang-js">
  554. timeline.on('select', function (properties) {
  555. alert('selected items: ' + properties.nodes);
  556. });
  557. </pre>
  558. <p>
  559. A listener can be removed via the function <code>off</code>:
  560. </p>
  561. <pre class="prettyprint lang-js">
  562. function onSelect (properties) {
  563. alert('selected items: ' + properties.nodes);
  564. }
  565. // add event listener
  566. timeline.on('select', onSelect);
  567. // do stuff...
  568. // remove event listener
  569. timeline.off('select', onSelect);
  570. </pre>
  571. <p>
  572. The following events are available.
  573. </p>
  574. <table>
  575. <colgroup>
  576. <col style="width: 20%;">
  577. <col style="width: 40%;">
  578. <col style="width: 40%;">
  579. </colgroup>
  580. <tr>
  581. <th>name</th>
  582. <th>Description</th>
  583. <th>Properties</th>
  584. </tr>
  585. <tr>
  586. <td>rangechange</td>
  587. <td>Fired repeatedly when the user is dragging the timeline window.
  588. </td>
  589. <td>
  590. <ul>
  591. <li><code>start</code> (Number): timestamp of the current start of the window.</li>
  592. <li><code>end</code> (Number): timestamp of the current end of the window.</li>
  593. </ul>
  594. </td>
  595. </tr>
  596. <tr>
  597. <td>rangechanged</td>
  598. <td>Fired once after the user has dragged the timeline window.
  599. </td>
  600. <td>
  601. <ul>
  602. <li><code>start</code> (Number): timestamp of the current start of the window.</li>
  603. <li><code>end</code> (Number): timestamp of the current end of the window.</li>
  604. </ul>
  605. </td>
  606. </tr>
  607. <tr>
  608. <td>select</td>
  609. <td>Fired after the user selects or deselects items by tapping or holding them.
  610. Not fired when the method <code>setSelection</code>is executed.
  611. </td>
  612. <td>
  613. <ul>
  614. <li><code>items</code>: an array with the ids of the selected items</li>
  615. </ul>
  616. </td>
  617. </tr>
  618. <tr>
  619. <td>timechange</td>
  620. <td>Fired repeatedly when the user is dragging the custom time bar.
  621. Only available when the custom time bar is enabled.
  622. </td>
  623. <td>
  624. <ul>
  625. <li><code>time</code> (Date): the current time.</li>
  626. </ul>
  627. </td>
  628. </tr>
  629. <tr>
  630. <td>timechanged</td>
  631. <td>Fired once after the user has dragged the custom time bar.
  632. Only available when the custom time bar is enabled.
  633. </td>
  634. <td>
  635. <ul>
  636. <li><code>time</code> (Date): the current time.</li>
  637. </ul>
  638. </td>
  639. </tr>
  640. </table>
  641. <h2 id="Styles">Styles</h2>
  642. <p>
  643. All parts of the Timeline have a class name and a default css style.
  644. The styles can be overwritten, which enables full customization of the layout
  645. of the Timeline.
  646. </p>
  647. <p>For example, to change the border and background color of all items, include the
  648. following code inside the head of your html code or in a separate stylesheet.</p>
  649. <pre class="prettyprint lang-html">&lt;style&gt;
  650. .graph .item {
  651. border-color: orange;
  652. background-color: yellow;
  653. }
  654. &lt;/style&gt;
  655. </pre>
  656. <h2 id="Data_Policy">Data Policy</h2>
  657. <p>
  658. All code and data is processed and rendered in the browser.
  659. No data is sent to any server.
  660. </p>
  661. </div>
  662. </body>
  663. </html>