Fixed #171: Implemented functions `setCurrentTime(date)` and `getCurrentTime()`

HISTORY.md

@@ -6,9 +6,6 @@ http://visjs.org
 
 ### Timeline
 
-- Fixed the `change` event sometimes being fired twice on IE10.
-- Fixed canceling moving an item to another group did not move the item
-  back to the original group.
 - Added localization support.
 - Implemented option `clickToUse`.
 - Implemented function `focus(id)` to center a specific item (or multiple items)
@@ -17,6 +14,10 @@ http://visjs.org
   focus selected nodes.
 - Implemented animated range change for functions `fit`, `focus`, `setSelection`,
   and `setWindow`.
+- Implemented functions `setCurrentTime(date)` and `getCurrentTime()`.
+- Fixed the `change` event sometimes being fired twice on IE10.
+- Fixed canceling moving an item to another group did not move the item
+  back to the original group.
 
 ### Network
 
@@ -34,6 +35,7 @@ http://visjs.org
 - Added 'customRange' for the Y axis and an example showing how it works.
 - Added localization support.
 - Implemented option `clickToUse`.
+- Implemented functions `setCurrentTime(date)` and `getCurrentTime()`.
 
 ## 2014-08-14, version 3.2.0
 

docs/timeline.html

@@ -757,6 +757,13 @@ timeline.clear({options: true}); // clear options only
     </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>
@@ -764,10 +771,18 @@ timeline.clear({options: true}); // clear options only
     </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> is a Date object.
+    <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>
 

lib/timeline/Core.js

@@ -550,6 +550,34 @@ Core.prototype.repaint = function () {
   throw new Error('Function repaint is deprecated. Use redraw instead.');
 };
 
+/**
+ * Set a current time. This can be used for example to ensure that a client's
+ * time is synchronized with a shared server time.
+ * Only applicable when option `showCurrentTime` is true.
+ * @param {Date | String | Number} time     A Date, unix timestamp, or
+ *                                          ISO date string.
+ */
+Core.prototype.setCurrentTime = function(time) {
+  if (!this.currentTime) {
+    throw new Error('Option showCurrentTime must be true');
+  }
+
+  this.currentTime.setCurrentTime(time);
+};
+
+/**
+ * Get the current time.
+ * Only applicable when option `showCurrentTime` is true.
+ * @return {Date} Returns the current time.
+ */
+Core.prototype.getCurrentTime = function() {
+  if (!this.currentTime) {
+    throw new Error('Option showCurrentTime must be true');
+  }
+
+  return this.currentTime.getCurrentTime();
+};
+
 /**
  * Convert a position on screen (pixels) to a datetime
  * @param {int}     x    Position on the screen in pixels

lib/timeline/component/CurrentTime.js

@@ -22,6 +22,7 @@ function CurrentTime (body, options) {
     locale: 'en'
   };
   this.options = util.extend({}, this.defaultOptions);
+  this.offset = 0;
 
   this._create();
 
@@ -83,7 +84,7 @@ CurrentTime.prototype.redraw = function() {
       this.start();
     }
 
-    var now = new Date();
+    var now = new Date(new Date().valueOf() + this.offset);
     var x = this.body.util.toScreen(now);
 
     var locale = this.options.locales[this.options.locale];
@@ -138,4 +139,25 @@ CurrentTime.prototype.stop = function() {
   }
 };
 
+/**
+ * Set a current time. This can be used for example to ensure that a client's
+ * time is synchronized with a shared server time.
+ * @param {Date | String | Number} time     A Date, unix timestamp, or
+ *                                          ISO date string.
+ */
+CurrentTime.prototype.setCurrentTime = function(time) {
+  var t = util.convert(time, 'Date').valueOf();
+  var now = new Date().valueOf();
+  this.offset = t - now;
+  this.redraw();
+};
+
+/**
+ * Get the current time.
+ * @return {Date} Returns the current time.
+ */
+CurrentTime.prototype.getCurrentTime = function() {
+  return new Date(new Date().valueOf() + this.offset);
+};
+
 module.exports = CurrentTime;

lib/timeline/component/CustomTime.js

@@ -125,10 +125,10 @@ CustomTime.prototype.redraw = function () {
 
 /**
  * Set custom time.
- * @param {Date} time
+ * @param {Date | number | string} time
  */
 CustomTime.prototype.setCustomTime = function(time) {
-  this.customTime = new Date(time.valueOf());
+  this.customTime = util.convert(time, 'Date');
   this.redraw();
 };