Renamed DataSet functions `subscribe` and `unsubscribe` to `on` and `off`

HISTORY.md

@@ -6,9 +6,13 @@ http://visjs.org
 
 ### Timeline
 
-- items can be dragged and removed.
+- Items can be dragged and removed.
 - Implemented options `selectable`, `editable`.
-- added events when dragging the custom time bar.
+- Added events when dragging the custom time bar.
+
+### DataSet
+
+- Renamed functions `subscribe` and `unsubscribe` to `on` and `off` respectively.
 
 
 ## 2014-01-31, version 0.4.0

docs/dataset.html

@@ -62,8 +62,8 @@ data.add([
 ]);
 
 // subscribe to any change in the DataSet
-data.subscribe('*', function (event, params, senderId) {
-  console.log('event', event, params);
+data.on('*', function (event, properties, senderId) {
+  console.log('event', event, properties);
 });
 
 // update an existing item
@@ -545,8 +545,8 @@ var items = data.get({
 
 <p>
   One can subscribe on changes in a DataSet.
-  A subscription can be created using the method <code>subscribe</code>,
-  and removed with <code>unsubscribe</code>.
+  A subscription can be created using the method <code>on</code>,
+  and removed with <code>off</code>.
 </p>
 
 <pre class="prettyprint lang-js">
@@ -554,8 +554,8 @@ var items = data.get({
 var data = new vis.DataSet();
 
 // subscribe to any change in the DataSet
-data.subscribe('*', function (event, params, senderId) {
-  console.log('event:', event, 'params:', params, 'senderId:', senderId);
+data.on('*', function (event, properties, senderId) {
+  console.log('event:', event, 'properties:', properties, 'senderId:', senderId);
 });
 
 // add an item
@@ -565,14 +565,14 @@ data.remove(1);                                 // triggers an 'remove' event
 </pre>
 
 
-<h3 id="Subscribe">Subscribe</h3>
+<h3 id="On">On</h3>
 
 <p>
   Subscribe to an event.
 </p>
 
 Syntax:
-<pre class="prettyprint lang-js">DataSet.subscribe(event, callback)</pre>
+<pre class="prettyprint lang-js">DataSet.on(event, callback)</pre>
 
 Where:
 <ul>
@@ -587,17 +587,17 @@ Where:
   </li>
 </ul>
 
-<h3 id="Unsubscribe">Unsubscribe</h3>
+<h3 id="Off">Off</h3>
 
 <p>
   Unsubscribe from an event.
 </p>
 
 Syntax:
-<pre class="prettyprint lang-js">DataSet.unsubscribe(event, callback)</pre>
+<pre class="prettyprint lang-js">DataSet.off(event, callback)</pre>
 
 Where <code>event</code> and <code>callback</code> correspond with the
-parameters used to <a href="#Subscribe">subscribe</a> to the event.
+parameters used to <a href="#On">subscribe</a> to the event.
 
 <h3 id="Events">Events</h3>
 
@@ -650,7 +650,7 @@ parameters used to subscribe to the event.
 </p>
 
     <pre class="prettyprint lang-js">
-function (event, params, senderId) {
+function (event, properties, senderId) {
   // handle the event
 });
 </pre>
@@ -674,13 +674,13 @@ function (event, params, senderId) {
     </td>
   </tr>
   <tr>
-    <td>params</td>
+    <td>properties</td>
     <td>Object&nbsp;|&nbsp;null</td>
     <td>
-      Optional parameters providing more information on the event.
+      Optional properties providing more information on the event.
       In case of the events <code>add</code>,
       <code>update</code>, and <code>remove</code>,
-      <code>params</code> is always an object containing a property
+      <code>properties</code> is always an object containing a property
       items, which contains an array with the ids of the affected
       items.
     </td>

docs/dataview.html

@@ -63,8 +63,8 @@ var view = new vis.DataView(data, {
 });
 
 // subscribe to any change in the DataView
-view.subscribe('*', function (event, params, senderId) {
-  console.log('event', event, params);
+view.on('*', function (event, properties, senderId) {
+  console.log('event', event, properties);
 });
 
 // update an item in the data set
@@ -201,8 +201,8 @@ var view = new vis.DataView({
 });
 
 // subscribe to any change in the DataView
-view.subscribe('*', function (event, params, senderId) {
-  console.log('event:', event, 'params:', params, 'senderId:', senderId);
+view.on('*', function (event, properties, senderId) {
+  console.log('event:', event, 'properties:', properties, 'senderId:', senderId);
 });
 
 // add, update, and remove data in the DataSet...

examples/timeline/06_event_listeners.html

@@ -18,15 +18,22 @@
   <div id="log"></div>
 
   <script type="text/javascript">
-    var container = document.getElementById('visualization');
-    var items = [
+    var items = new vis.DataSet({
+      convert: {
+        start: 'Date',
+        end: 'Date'
+      }
+    });
+    items.add([
       {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'}
-    ];
+    ]);
+
+    var container = document.getElementById('visualization');
     var options = {};
     var timeline = new vis.Timeline(container, items, options);
 
@@ -40,6 +47,10 @@
       logEvent('select', properties);
     });
 
+    items.on('*', function (event, properties) {
+      logEvent(event, properties);
+    });
+
     function logEvent(event, properties) {
       var log = document.getElementById('log');
       var msg = document.createElement('div');

src/DataSet.js

@@ -73,7 +73,7 @@ function DataSet (options) {
  *                                  {Object | null} params
  *                                  {String | Number} senderId
  */
-DataSet.prototype.subscribe = function (event, callback) {
+DataSet.prototype.on = function on (event, callback) {
   var subscribers = this.subscribers[event];
   if (!subscribers) {
     subscribers = [];
@@ -85,12 +85,15 @@ DataSet.prototype.subscribe = function (event, callback) {
   });
 };
 
+// TODO: make this function deprecated (replaced with `on` since version 0.5)
+DataSet.prototype.subscribe = DataSet.prototype.on;
+
 /**
  * Unsubscribe from an event, remove an event listener
  * @param {String} event
  * @param {function} callback
  */
-DataSet.prototype.unsubscribe = function (event, callback) {
+DataSet.prototype.off = function off(event, callback) {
   var subscribers = this.subscribers[event];
   if (subscribers) {
     this.subscribers[event] = subscribers.filter(function (listener) {
@@ -99,6 +102,9 @@ DataSet.prototype.unsubscribe = function (event, callback) {
   }
 };
 
+// TODO: make this function deprecated (replaced with `on` since version 0.5)
+DataSet.prototype.unsubscribe = DataSet.prototype.off;
+
 /**
  * Trigger an event
  * @param {String} event

src/DataView.js

@@ -69,8 +69,8 @@ DataView.prototype.setData = function (data) {
     this._trigger('add', {items: ids});
 
     // subscribe to new dataset
-    if (this.data.subscribe) {
-      this.data.subscribe('*', this.listener);
+    if (this.data.on) {
+      this.data.on('*', this.listener);
     }
   }
 };
@@ -276,6 +276,10 @@ DataView.prototype._onEvent = function (event, params, senderId) {
 };
 
 // copy subscription functionality from DataSet
-DataView.prototype.subscribe = DataSet.prototype.subscribe;
-DataView.prototype.unsubscribe = DataSet.prototype.unsubscribe;
+DataView.prototype.on = DataSet.prototype.on;
+DataView.prototype.off = DataSet.prototype.off;
 DataView.prototype._trigger = DataSet.prototype._trigger;
+
+// TODO: make these functions deprecated (replaced with `on` and `off` since version 0.5)
+DataView.prototype.subscribe = DataView.prototype.on;
+DataView.prototype.unsubscribe = DataView.prototype.off;

src/graph/Graph.js

@@ -1149,7 +1149,7 @@ Graph.prototype._setNodes = function(nodes) {
     // subscribe to new dataset
     var me = this;
     util.forEach(this.nodesListeners, function (callback, event) {
-      me.nodesData.subscribe(event, callback);
+      me.nodesData.on(event, callback);
     });
 
     // draw all new nodes
@@ -1276,7 +1276,7 @@ Graph.prototype._setEdges = function(edges) {
     // subscribe to new dataset
     var me = this;
     util.forEach(this.edgesListeners, function (callback, event) {
-      me.edgesData.subscribe(event, callback);
+      me.edgesData.on(event, callback);
     });
 
     // draw all new nodes

src/timeline/component/GroupSet.js

@@ -132,7 +132,7 @@ GroupSet.prototype.setGroups = function setGroups(groups) {
     // subscribe to new dataset
     var id = this.id;
     util.forEach(this.listeners, function (callback, event) {
-      me.groupsData.subscribe(event, callback, id);
+      me.groupsData.on(event, callback, id);
     });
 
     // draw all new groups

src/timeline/component/ItemSet.js

@@ -558,7 +558,7 @@ ItemSet.prototype.setItems = function setItems(items) {
     // subscribe to new dataset
     var id = this.id;
     util.forEach(this.listeners, function (callback, event) {
-      me.itemsData.subscribe(event, callback, id);
+      me.itemsData.on(event, callback, id);
     });
 
     // draw all new items

test/dataset.js

@@ -163,3 +163,4 @@ assert.deepEqual(data.isInternalId(data.get()[0].id), true);
 assert.deepEqual((data.get({"showInternalIds": false})[0].id == undefined),true);
 
 // TODO: extensively test DataSet
+// TODO: test subscribing to events

test/dataview.js

@@ -39,11 +39,11 @@ assert.deepEqual(group2.get({
 
 // test event subscription
 var groupsTriggerCount = 0;
-groups.subscribe('*', function () {
+groups.on('*', function () {
   groupsTriggerCount++;
 });
 var group2TriggerCount = 0;
-group2.subscribe('*', function () {
+group2.on('*', function () {
   group2TriggerCount++;
 });
 

test/eventbus.js

@@ -1,38 +0,0 @@
-// test vis.EventBus
-
-var assert = require('assert'),
-    vis = require('../dist/vis');
-
-var bus = new vis.EventBus();
-
-var received = [];
-
-var id1 = '1';
-bus.on('message', function (event, data, source) {
-  received.push({
-    event: event,
-    data: data,
-    source: source
-  });
-}, id1);
-
-var id2 = '2';
-bus.emit('message', {text: 'hello world'}, id2);
-bus.on('chat:*', function (event, data, source) {
-  received.push({
-    event: event,
-    data: data,
-    source: source
-  });
-});
-
-bus.emit('chat:1', null, id2);
-bus.emit('chat:2', {text: 'hello world'}, id1);
-
-// verify if the messages are received
-assert.deepEqual(received, [
-  {event: 'message', data: {text: 'hello world'}, source: id2},
-  {event: 'chat:1', data: null, source: id2},
-  {event: 'chat:2', data: {text: 'hello world'}, source: id1}
-]);
-