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.

336 lines
9.0 KiB

  1. <!doctype html>
  2. <html>
  3. <head>
  4. <title>vis.js | DataView documentation</title>
  5. <link href="css/prettify.css" type="text/css" rel="stylesheet" />
  6. <link href='css/style.css' type='text/css' rel='stylesheet'>
  7. <script type="text/javascript" src="lib/prettify/prettify.js"></script>
  8. <script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,'script','//www.google-analytics.com/analytics.js','ga');ga('create', 'UA-61231638-1', 'auto');ga('send', 'pageview');</script></head>
  9. <body onload="prettyPrint();">
  10. <div id="container">
  11. <h1>DataView documentation</h1>
  12. <h2 id="Contents">Contents</h2>
  13. <ul>
  14. <li><a href="#Overview">Overview</a></li>
  15. <li><a href="#Example">Example</a></li>
  16. <li><a href="#Construction">Construction</a></li>
  17. <li><a href="#Methods">Methods</a></li>
  18. <li><a href="#Properties">Properties</a></li>
  19. <li><a href="#Getting_Data">Getting Data</a></li>
  20. <li><a href="#Subscriptions">Subscriptions</a></li>
  21. <li><a href="#Data_Policy">Data Policy</a></li>
  22. </ul>
  23. <h2 id="Overview">Overview</h2>
  24. <p>
  25. A DataView offers a filtered and/or formatted view on a
  26. <a href="dataset.html">DataSet</a>.
  27. One can subscribe on changes in a DataView, and easily get filtered or
  28. formatted data without having to specify filters and field types all
  29. the time.
  30. </p>
  31. <h2 id="Example">Example</h2>
  32. <p>
  33. The following example shows how to use a DataView.
  34. </p>
  35. <pre class="prettyprint lang-js">
  36. // create a DataSet
  37. var data = new vis.DataSet();
  38. data.add([
  39. {id: 1, text: 'item 1', date: new Date(2013, 6, 20), group: 1, first: true},
  40. {id: 2, text: 'item 2', date: '2013-06-23', group: 2},
  41. {id: 3, text: 'item 3', date: '2013-06-25', group: 2},
  42. {id: 4, text: 'item 4'}
  43. ]);
  44. // create a DataView
  45. // the view will only contain items having a property group with value 1,
  46. // and will only output fields id, text, and date.
  47. var view = new vis.DataView(data, {
  48. filter: function (item) {
  49. return (item.group == 1);
  50. },
  51. fields: ['id', 'text', 'date']
  52. });
  53. // subscribe to any change in the DataView
  54. view.on('*', function (event, properties, senderId) {
  55. console.log('event', event, properties);
  56. });
  57. // update an item in the data set
  58. data.update({id: 2, group: 1});
  59. // get all ids in the view
  60. var ids = view.getIds();
  61. console.log('ids', ids); // will output [1, 2]
  62. // get all items in the view
  63. var items = view.get();
  64. </pre>
  65. <h2 id="Construction">Construction</h2>
  66. <p>
  67. A DataView can be constructed as:
  68. </p>
  69. <pre class="prettyprint lang-js">
  70. var data = new vis.DataView(dataset, options)
  71. </pre>
  72. <p>
  73. where:
  74. </p>
  75. <ul>
  76. <li>
  77. <code>dataset</code> is a DataSet or DataView.
  78. </li>
  79. <li>
  80. <code>options</code> is an object which can
  81. contain the following properties. Note that these properties
  82. are exactly the same as the properties available in methods
  83. <code>DataSet.get</code> and <code>DataView.get</code>.
  84. <table>
  85. <tr>
  86. <th>Name</th>
  87. <th>Type</th>
  88. <th>Description</th>
  89. </tr>
  90. <tr>
  91. <td>convert</td>
  92. <td>Object.&lt;String,&nbsp;String&gt;</td>
  93. <td>
  94. An object containing field names as key, and data types as value.
  95. By default, the type of the properties of an item are left
  96. unchanged. When a field type is specified, this field in the
  97. items will be converted to the specified type. This can be used
  98. for example to convert ISO strings containing a date to a
  99. JavaScript Date object, or convert strings to numbers or vice
  100. versa. The available data types are listed in section
  101. <a href="dataset.html#Data_Types">Data Types</a>.
  102. </td>
  103. </tr>
  104. <tr>
  105. <td>fields</td>
  106. <td>String[&nbsp;]</td>
  107. <td>
  108. An array with field names.
  109. By default, all properties of the items are emitted.
  110. When <code>fields</code> is defined, only the properties
  111. whose name is specified in <code>fields</code> will be included
  112. in the returned items.
  113. </td>
  114. </tr>
  115. <tr>
  116. <td>filter</td>
  117. <td>function</td>
  118. <td>Items can be filtered on specific properties by providing a filter
  119. function. A filter function is executed for each of the items in the
  120. DataSet, and is called with the item as parameter. The function must
  121. return a boolean. All items for which the filter function returns
  122. true will be emitted.
  123. See also section <a href="dataset.html#Data_Filtering">Data Filtering</a>.</td>
  124. </tr>
  125. </table>
  126. </li>
  127. </ul>
  128. <h2 id="Methods">Methods</h2>
  129. <p>DataView contains the following methods.</p>
  130. <table>
  131. <colgroup>
  132. <col width="200">
  133. </colgroup>
  134. <tr>
  135. <th>Method</th>
  136. <th>Return Type</th>
  137. <th>Description</th>
  138. </tr>
  139. <tr>
  140. <td>
  141. get([options] [, data])<br>
  142. get(id [,options] [, data])<br>
  143. get(ids [, options] [, data])
  144. </td>
  145. <td>Object | Array | DataTable</td>
  146. <td>
  147. Get a single item, multiple items, or all items from the DataView.
  148. Usage examples can be found in section <a href="#Getting_Data">Getting Data</a>, and the available <code>options</code> are described in section <a href="#Data_Selection">Data Selection</a>. If parameter <code>data</code> is provided, items will be appended to this array or table, which is required in case of Google DataTable.
  149. </td>
  150. </tr>
  151. <tr>
  152. <td>
  153. getDataSet()
  154. </td>
  155. <td>DataSet</td>
  156. <td>
  157. Get the DataSet to which the DataView is connected.
  158. </td>
  159. </tr>
  160. <tr>
  161. <td>
  162. getIds([options])
  163. </td>
  164. <td>Number[]</td>
  165. <td>
  166. Get ids of all items or of a filtered set of items.
  167. Available <code>options</code> are described in section <a href="dataset.html#Data_Selection">Data Selection</a>, except that options <code>fields</code> and <code>type</code> are not applicable in case of <code>getIds</code>.
  168. </td>
  169. </tr>
  170. <tr>
  171. <td>off(event, callback)</td>
  172. <td>none</td>
  173. <td>
  174. Unsubscribe from an event, remove an event listener. See section <a href="#Subscriptions">Subscriptions</a>.
  175. </td>
  176. </tr>
  177. <tr>
  178. <td>on(event, callback)</td>
  179. <td>none</td>
  180. <td>
  181. Subscribe to an event, add an event listener. See section <a href="#Subscriptions">Subscriptions</a>.
  182. </td>
  183. </tr>
  184. <tr>
  185. <td>refresh()</td>
  186. <td>none</td>
  187. <td>
  188. Refresh the filter results of a DataView. Useful when the filter function contains dynamic properties, like:
  189. <pre class="prettyprint lang-js">var data = new vis.DataSet(...);
  190. var view = new vis.DataView(data, {
  191. filter: function (item) {
  192. return item.value > threshold;
  193. }
  194. });</pre>
  195. In this example, <code>threshold</code> is an external parameter. When the value of <code>threshold</code> changes, the DataView must be notified that the filter results may have changed by calling <code>DataView.refresh()</code>.
  196. </td>
  197. </tr>
  198. <tr>
  199. <td>
  200. setDataSet(data)
  201. </td>
  202. <td>none</td>
  203. <td>
  204. Replace the DataSet of the DataView. Parameter <code>data</code> can be a DataSet or a DataView.
  205. </td>
  206. </tr>
  207. </table>
  208. <h2 id="Properties">Properties</h2>
  209. <p>DataView contains the following properties.</p>
  210. <table>
  211. <colgroup>
  212. <col width="200">
  213. </colgroup>
  214. <tr>
  215. <th>Property</th>
  216. <th>Type</th>
  217. <th>Description</th>
  218. </tr>
  219. <tr>
  220. <td>length</td>
  221. <td>Number</td>
  222. <td>The number of items in the DataView.</td>
  223. </tr>
  224. </table>
  225. <h2 id="Getting_Data">Getting Data</h2>
  226. <p>
  227. Data of the DataView can be retrieved using the method <code>get</code>.
  228. </p>
  229. <pre class="prettyprint lang-js">
  230. var items = view.get();
  231. </pre>
  232. <p>
  233. Data of a DataView can be filtered and formatted again, in exactly the
  234. same way as in a DataSet. See sections
  235. <a href="dataset.html#Data_Manipulation">Data Manipulation</a> and
  236. <a href="dataset.html#Data_Selection">Data Selection</a> for more
  237. information.
  238. </p>
  239. <pre class="prettyprint lang-js">
  240. var items = view.get({
  241. fields: ['id', 'score'],
  242. filter: function (item) {
  243. return (item.score > 50);
  244. }
  245. });
  246. </pre>
  247. <h2 id="Subscriptions">Subscriptions</h2>
  248. <p>
  249. One can subscribe on changes in the DataView. Subscription works exactly
  250. the same as for DataSets. See the documentation on
  251. <a href="dataset.html#Subscriptions">subscriptions in a DataSet</a>
  252. for more information.
  253. </p>
  254. <pre class="prettyprint lang-js">
  255. // create a DataSet and a view on the data set
  256. var data = new vis.DataSet();
  257. var view = new vis.DataView({
  258. filter: function (item) {
  259. return (item.group == 2);
  260. }
  261. });
  262. // subscribe to any change in the DataView
  263. view.on('*', function (event, properties, senderId) {
  264. console.log('event:', event, 'properties:', properties, 'senderId:', senderId);
  265. });
  266. // add, update, and remove data in the DataSet...
  267. </pre>
  268. <h2 id="Data_Policy">Data Policy</h2>
  269. <p>
  270. All code and data is processed and rendered in the browser.
  271. No data is sent to any server.
  272. </p>
  273. </div>
  274. </body>
  275. </html>