Deprecated option `showCustomTime`. Use method `addCustomTime()` instead.

9 years ago · 2929fafa20
--- a/HISTORY.md
+++ b/HISTORY.md
@ -21,6 +21,7 @@ http://visjs.org
  See example 18_range_overflow.html.
 - Fixed invalid css names for time axis grid, renamed hours class names from
  `4-8h` to `h4-h8`.
 - Deprecated option `showCustomTime`. Use method `addCustomTime()` instead.

 ### Network

--- a/docs/timeline.html
+++ b/docs/timeline.html
@ -720,13 +720,6 @@ var options = {
    <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>
@ -864,12 +857,13 @@ var options = {
  </tr>

  <tr>
    <td>addCustomTime(time[, id])</td>
    <td>addCustomTime([time] [, id])</td>
    <td>Number | String</td>
    <td>
      Only applicable when the option showCustomTime is true.<br>
      Add new vertical bar representing custom time that can be dragged by the user. Parameter <code>time</code> can be a Date, Number, or String. Parameter <code>id</code> can be Number or String. If <code>id</code> is provided, it will be used as ID for the new vertical bar, otherwise the ID will be auto generated.<br>
      Returns ID of the newly created bar.
      Add new vertical bar representing a custom time that can be dragged by the user.
      Parameter <code>time</code> can be a Date, Number, or String, and is <code>new Date()</code> by default.
      Parameter <code>id</code> can be Number or String and is <code>undefined</code> by default.<br>
      Returns id of the created bar.
    </td>
  </tr>

@ -911,7 +905,7 @@ var options = {
  <tr>
    <td>getCustomTime([id])</td>
    <td>Date</td>
    <td>Retrieve the custom time. Only applicable when the option <code>showCustomTime</code> is true. If parameter <code>id</code> is provided, time of the custom time bar under that ID is returned.
    <td>Retrieve the custom time from the custom time bar with given id. Id is <code>undefined</code> by default.
    </td>
  </tr>

@ -1003,7 +997,9 @@ var options = {
  <tr>
    <td>setCustomTime(time [, id])</td>
    <td>none</td>
    <td>Adjust the custom time bar. Only applicable when the option <code>showCustomTime</code> is true. Parameter <code>time</code> can be a Date object, numeric timestamp, or ISO date string. Parameter <code>id</code> represents ID of the custom time bar, provided by <code>addCustomTime</code> method and can be a Number or String.
    <td>Adjust the time of a custom time bar.
      Parameter <code>time</code> can be a Date object, numeric timestamp, or ISO date string.
      Parameter <code>id</code> is the idof the custom time bar, and is <code>undefined</code> by default.
    </td>
  </tr>

@ -1197,8 +1193,8 @@ timeline.off('select', onSelect);
    </td>
    <td>
      <ul>
        <li><code>id</code> (Number | String): Vertical bar ID.</li>
        <li><code>time</code> (Date): the current time.</li>
        <li><code>id</code> (Number | String): custom time bar id.</li>
        <li><code>time</code> (Date): the custom time.</li>
      </ul>
    </td>
  </tr>
@ -1210,8 +1206,8 @@ timeline.off('select', onSelect);
    </td>
    <td>
      <ul>
        <li><code>id</code> (Number | String): Vertical bar ID.</li>
        <li><code>time</code> (Date): the current time.</li>
        <li><code>id</code> (Number | String): custom time bar id.</li>
        <li><code>time</code> (Date): the custom time.</li>
      </ul>
    </td>
  </tr>
--- a/examples/timeline/07_custom_time_bar.html
+++ b/examples/timeline/07_custom_time_bar.html
@ -1,65 +0,0 @@
 <!DOCTYPE HTML>
 <html>
 <head>
  <title>Timeline | Show current and custom time bars</title>

  <style type="text/css">
    body, html {
      font-family: sans-serif;
      font-size: 11pt;
    }
  </style>

  <script src="../../dist/vis.js"></script>
  <link href="../../dist/vis.css" rel="stylesheet" type="text/css" />
 <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>
 <body>

 <p>
  <input type="text" id="setTime" value="2014-02-07" />
  <input type="button" id="set" value="Set custom time" />
 </p>
 <p>
  <input type="button" id="get" value="Get custom time" />
  <span id="getTime"></span>
 </p>
 <p>
  <code>timechange</code> event: <span id="timechangeEvent"></span>
 </p>
 <p>
  <code>timechanged</code> event: <span id="timechangedEvent"></span>
 </p>

 <div id="visualization"></div>

 <script type="text/javascript">
  var container = document.getElementById('visualization');
  var items = new vis.DataSet();
  var options = {
    showCurrentTime: true,
    showCustomTime: true,
    start: new Date(Date.now() - 1000 * 60 * 60 * 24),
    end: new Date(Date.now() + 1000 * 60 * 60 * 24 * 6)
  };
  var timeline = new vis.Timeline(container, items, options);

  document.getElementById('set').onclick = function () {
    var time = document.getElementById('setTime').value;
    timeline.setCustomTime(time);
  };
  document.getElementById('setTime').value = new Date().toISOString().substring(0, 10);

  document.getElementById('get').onclick = function () {
    document.getElementById('getTime').innerHTML = timeline.getCustomTime();
  };

  timeline.on('timechange', function (properties) {
    document.getElementById('timechangeEvent').innerHTML = properties.time;
  });
  timeline.on('timechanged', function (properties) {
    document.getElementById('timechangedEvent').innerHTML = properties.time;
  });

 </script>
 </body>
 </html>
--- a/examples/timeline/34_add_custom_timebar.html
+++ b/examples/timeline/34_add_custom_timebar.html
@ -38,7 +38,6 @@
  var customDate = new Date();
  var options = {
    showCurrentTime: true,
    showCustomTime: true,
    start: new Date(Date.now() - 1000 * 60 * 60 * 24),
    end: new Date(Date.now() + 1000 * 60 * 60 * 24 * 6)
  };
@ -46,7 +45,7 @@

  // Set first time bar
  customDate = new Date(customDate.getFullYear(), customDate.getMonth(), customDate.getDate() + 1);
  timeline.addCustomTime(customDate, 1);
  timeline.addCustomTime(customDate, '1');

  document.getElementById('add').onclick = function () {
    customDate = new Date(customDate.getFullYear(), customDate.getMonth(), customDate.getDate() + 1);
@ -56,8 +55,14 @@
  };

  document.getElementById('remove').onclick = function () {
    timeline.removeCustomTime(document.getElementById('barIndex').value);
    document.getElementById('barIndex').value = '';
    try {
      timeline.removeCustomTime(document.getElementById('barIndex').value);
      document.getElementById('barIndex').value = '';
    }
    catch (err) {
      console.log(err);
      alert(err);
    }
  };

  timeline.on('timechange', function (properties) {
--- a/examples/timeline/13_past_and_future.html
+++ b/examples/timeline/13_past_and_future.html
@ -44,14 +44,15 @@

  // specify options
  var options = {
    showCurrentTime: true,
    showCustomTime: true
    showCurrentTime: true
  };

  // create a timeline
  var container = document.getElementById('mytimeline');
  timeline = new vis.Timeline(container, data, options);

  timeline.addCustomTime(new Date());

  // add event listener
  timeline.on('timechange', function (event) {
    document.getElementById("customTime").innerHTML = "Custom Time: " + event.time;
--- a/examples/timeline/19_localization.html
+++ b/examples/timeline/19_localization.html
@ -43,12 +43,12 @@

  // Configuration for the Timeline
  var options = {
    showCurrentTime: true,
    showCustomTime: true
    showCurrentTime: true
  };

  // Create a Timeline
  var timeline = new vis.Timeline(container, items, options);
  timeline.addCustomTime(new Date());

  timeline.setCustomTime(new Date(new Date().valueOf() + DAY));

--- a/examples/timeline/29_hiding_times.html
+++ b/examples/timeline/29_hiding_times.html
@ -38,13 +38,12 @@
        start: '2014-04-17',
        end: '2014-05-01',
        height: '200px',
        editable: true,
        showCustomTime: true
        editable: true
    };

    // Create a Timeline
    var timeline = new vis.Timeline(container, items, options);
    timeline.setCustomTime("2014-04-18 13:00:00");
    timeline.addCustomTime("2014-04-18 13:00:00");
 </script>
 </body>
 </html>
--- a/examples/timeline/index.html
+++ b/examples/timeline/index.html
@ -18,7 +18,7 @@
  <p><a href="04_html_data.html">04_html_data.html</a></p>
  <p><a href="05_groups.html">05_groups.html</a></p>
  <p><a href="06_event_listeners.html">06_event_listeners.html</a></p>
  <p><a href="07_custom_time_bar.html">07_custom_time_bar.html</a></p>
  <p><a href="07_custom_time_bars.html">07_custom_time_bars.html</a></p>
  <p><a href="08_edit_items.html">08_edit_items.html</a></p>
  <p><a href="09_order_groups.html">09_order_groups.html</a></p>
  <p><a href="10_limit_move_and_zoom.html">10_limit_range_and_zoom.html</a></p>
@ -44,7 +44,6 @@
  <p><a href="31_background_areas_with_groups.html">31_background_areas_with_groups.html</a></p>
  <p><a href="32_grid_styling.html">32_grid_styling.html</a></p>
  <p><a href="33_custom_snapping.html">33_custom_snapping.html</a></p>
  <p><a href="34_add_custom_timebar.html">34_add_custom_timebar.html</a></p>
  <p><a href="35_item_ordering.html">35_item_ordering.html</a></p>
  <p><a href="requirejs/requirejs_example.html">requirejs_example.html</a></p>

--- a/lib/timeline/Core.js
+++ b/lib/timeline/Core.js
@ -173,6 +173,8 @@ Core.prototype._create = function (container) {
    scrollTopMin: 0
  };

  this.customTimes = [];

  // store state information needed for touch events
  this.touch = {};

@ -263,6 +265,10 @@ Core.prototype.setOptions = function (options) {
      }
    }

    if ('showCustomTime' in options) {
      throw new Error('Option `showCustomTime` is deprecated. Create a custom time bar via timeline.addCustomTime(time [, id])');
    }

    // enable/disable autoResize
    this._initAutoResize();
  }
@ -327,102 +333,70 @@ Core.prototype.destroy = function () {
 /**
 * Set a custom time bar
 * @param {Date} time
 * @param {int} id
 * @param {number} [id=undefined] Optional id of the custom time bar to be adjusted.
 */
 Core.prototype.setCustomTime = function (time, id) {
  if (!this.customTime) {
    throw new Error('Cannot get custom time: Custom time bar is not enabled');
  }
  var customTimes = this.customTimes.filter(function (component) {
    return id === component.options.id;
  });

  var barId = id || 0;
  if (customTimes.length === 0) {
    throw new Error('No custom time bar found with id ' + JSON.stringify(id))
  }

  this.components.forEach(function (element, index, components) {
    if (element instanceof CustomTime && element.options.id === barId) {
      element.setCustomTime(time);
    }
  });
  if (customTimes.length > 0) {
    customTimes[0].setCustomTime(time);
  }
 };

 /**
 * Retrieve the current custom time.
 * @return {Date} customTime
 * @param {int} id
 * @param {number} [id=undefined]    Id of the custom time bar.
 * @return {Date | undefined} customTime
 */
 Core.prototype.getCustomTime = function(id) {
  if (!this.customTime) {
    throw new Error('Cannot get custom time: Custom time bar is not enabled');
  }

  var barId = id || 0,
      customTime = this.customTime.getCustomTime();

  this.components.forEach(function (element, index, components) {
    if (element instanceof CustomTime && element.options.id === barId) {
      customTime = element.getCustomTime();
    }
  var customTimes = this.customTimes.filter(function (component) {
    return component.options.id === id;
  });

  return customTime;
  if (customTimes.length === 0) {
    throw new Error('No custom time bar found with id ' + JSON.stringify(id))
  }
  return customTimes[0].getCustomTime();
 };

 /**
 * Add custom vertical bar
 * @param {Date | String | Number} time  A Date, unix timestamp, or
 *                                      ISO date string. Time point where the new bar should be placed
 * @param {Number | String} ID of the new bar
 * @return {Number | String} ID of the new bar
 * @param {Date | String | Number} [time]  A Date, unix timestamp, or
 *                                         ISO date string. Time point where
 *                                         the new bar should be placed.
 *                                         If not provided, `new Date()` will
 *                                         be used.
 * @param {Number | String} [id=undefined] Id of the new bar. Optional
 * @return {Number | String}               Returns the id of the new bar
 */
 Core.prototype.addCustomTime = function (time, id) {
  if (!this.currentTime) {
    throw new Error('Option showCurrentTime must be true');
  }
  var timestamp = time !== undefined
      ? util.convert(time, 'Date').valueOf()
      : new Date();

  if (time === undefined) {
    throw new Error('Time parameter for the custom bar must be provided');
  }

  var ts = util.convert(time, 'Date').valueOf(),
      numIds, customTime, customBarId;

  // All bar IDs are kept in 1 array, mixed types
  // Bar with ID 0 is the default bar.
  if (!this.customBarIds || this.customBarIds.constructor !== Array) {
    this.customBarIds = [0];
  }

  // If the ID is not provided, generate one, otherwise just use it
  if (id === undefined) {

    numIds = this.customBarIds.filter(function (element) {
      return util.isNumber(element);
    });

    customBarId = numIds.length > 0 ? Math.max.apply(null, numIds) + 1 : 1;

  } else {
    
    // Check for duplicates
    this.customBarIds.forEach(function (element) {
      if (element === id) {
        throw new Error('Custom time ID already exists');
      }
    });

    customBarId = id;
  var exists = this.customTimes.some(function (customTime) {
    return customTime.options.id === id;
  });
  if (exists) {
    throw new Error('A custom time with id ' + JSON.stringify(id) + ' already exists');
  }

  this.customBarIds.push(customBarId);

  customTime = new CustomTime(this.body, {
    showCustomTime : true,
    time : ts,
    id : customBarId
  var customTime = new CustomTime(this.body, {
    time : timestamp,
    id : id
  });

  this.customTimes.push(customTime);
  this.components.push(customTime);
  this.redraw();

  return customBarId;
  return id;
 };

 /**
@ -431,19 +405,19 @@ Core.prototype.addCustomTime = function (time, id) {
 * @return {boolean} True if the bar exists and is removed, false otherwise
 */
 Core.prototype.removeCustomTime = function (id) {
  var customTimes = this.customTimes.filter(function (bar) {
    return (bar.options.id === id);
  });

  var me = this;
  if (customTimes.length === 0) {
    throw new Error('No custom time bar found with id ' + JSON.stringify(id))
  }

  this.components.forEach(function (bar, index, components) {
    if (bar instanceof CustomTime && bar.options.id === id) {
      // Only the lines added by the user will be removed
      if (bar.options.id !== 0) {
        me.customBarIds.splice(me.customBarIds.indexOf(id), 1);
        components.splice(index, 1);
        bar.destroy();
      }
    }
  });
  customTimes.forEach(function (customTime) {
    this.customTimes.splice(this.customTimes.indexOf(customTime), 1);
    this.components.splice(this.components.indexOf(customTime), 1);
    customTime.destroy();
  }.bind(this))
 };


--- a/lib/timeline/Graph2d.js
+++ b/lib/timeline/Graph2d.js
@ -78,11 +78,6 @@ function Graph2d (container, items, groups, options) {
  this.currentTime = new CurrentTime(this.body);
  this.components.push(this.currentTime);

  // custom time bar
  // Note: time bar will be attached in this.setOptions when selected
  this.customTime = new CustomTime(this.body);
  this.components.push(this.customTime);

  // item set
  this.linegraph = new LineGraph(this.body);
  this.components.push(this.linegraph);
@ -270,7 +265,7 @@ Graph2d.prototype.getEventProperties = function (event) {
  else if (util.hasParent(element, this.linegraph.yAxisRight.dom.frame))  {what = 'data-axis';}
  else if (util.hasParent(element, this.linegraph.legendLeft.dom.frame))  {what = 'legend';}
  else if (util.hasParent(element, this.linegraph.legendRight.dom.frame)) {what = 'legend';}
  else if (util.hasParent(element, this.customTime.bar))                  {what = 'custom-time';} // TODO: fix for multiple custom time bars
  else if (CustomTime.customTimeFromTarget(event) != null)                {what = 'custom-time';}
  else if (util.hasParent(element, this.currentTime.bar))                 {what = 'current-time';}
  else if (util.hasParent(element, this.dom.center))                      {what = 'background';}

--- a/lib/timeline/Timeline.js
+++ b/lib/timeline/Timeline.js
@ -90,11 +90,6 @@ function Timeline (container, items, groups, options) {
  this.currentTime = new CurrentTime(this.body);
  this.components.push(this.currentTime);

  // custom time bar
  // Note: time bar will be attached in this.setOptions when selected
  this.customTime = new CustomTime(this.body);
  this.components.push(this.customTime);

  // item set
  this.itemSet = new ItemSet(this.body);
  this.components.push(this.itemSet);
@ -362,7 +357,7 @@ Timeline.prototype.getEventProperties = function (event) {
  else if (util.hasParent(element, this.timeAxis.dom.foreground))      {what = 'axis';}
  else if (this.timeAxis2 && util.hasParent(element, this.timeAxis2.dom.foreground)) {what = 'axis';}
  else if (util.hasParent(element, this.itemSet.dom.labelSet))         {what = 'group-label';}
  else if (util.hasParent(element, this.customTime.bar))               {what = 'custom-time';} // TODO: fix for multiple custom time bars
  else if (CustomTime.customTimeFromTarget(event) != null)             {what = 'custom-time';}
  else if (util.hasParent(element, this.currentTime.bar))              {what = 'current-time';}
  else if (util.hasParent(element, this.dom.center))                   {what = 'background';}

--- a/lib/timeline/component/CustomTime.js
+++ b/lib/timeline/component/CustomTime.js
@ -8,7 +8,9 @@ var locales = require('../locales');
 * A custom time bar
 * @param {{range: Range, dom: Object}} body
 * @param {Object} [options]        Available parameters:
 *                                  {Boolean} [showCustomTime]
 *                                  {number | string} id
 *                                  {string} locales
 *                                  {string} locale
 * @constructor CustomTime
 * @extends Component
 */
@ -18,10 +20,9 @@ function CustomTime (body, options) {

  // default options
  this.defaultOptions = {
    showCustomTime: false,
    locales: locales,
    locale: 'en',
    id: 0
    id: undefined
  };
  this.options = util.extend({}, this.defaultOptions);

@ -44,17 +45,14 @@ CustomTime.prototype = new Component();
 /**
 * Set options for the component. Options will be merged in current options.
 * @param {Object} options  Available parameters:
 *                          {boolean} [showCustomTime]
 *                                  {number | string} id
 *                                  {string} locales
 *                                  {string} locale
 */
 CustomTime.prototype.setOptions = function(options) {
  if (options) {
    // copy all options that we know
    util.selectiveExtend(['showCustomTime', 'locale', 'locales', 'id'], this.options, options);

    // Triggered by addCustomTimeBar, redraw to add new bar
    if (this.options.id) {
      this.redraw();
    }
    util.selectiveExtend(['locale', 'locales', 'id'], this.options, options);
  }
 };

@ -64,6 +62,7 @@ CustomTime.prototype.setOptions = function(options) {
 */
 CustomTime.prototype._create = function() {
  var bar = document.createElement('div');
  bar['custom-time'] = this;
  bar.className = 'vis-custom-time';
  bar.style.position = 'absolute';
  bar.style.top = '0px';
@ -93,10 +92,9 @@ CustomTime.prototype._create = function() {
 * Destroy the CustomTime bar
 */
 CustomTime.prototype.destroy = function () {
  this.options.showCustomTime = false;
  this.redraw(); // will remove the bar from the DOM
  this.hide();

  this.hammer.enable(false);
  this.hammer.destroy();
  this.hammer = null;

  this.body = null;
@ -107,42 +105,44 @@ CustomTime.prototype.destroy = function () {
 * @return {boolean} Returns true if the component is resized
 */
 CustomTime.prototype.redraw = function () {
  if (this.options.showCustomTime) {
    var parent = this.body.dom.backgroundVertical;
    if (this.bar.parentNode != parent) {
      // attach to the dom
      if (this.bar.parentNode) {
        this.bar.parentNode.removeChild(this.bar);
      }
      parent.appendChild(this.bar);
  var parent = this.body.dom.backgroundVertical;
  if (this.bar.parentNode != parent) {
    // attach to the dom
    if (this.bar.parentNode) {
      this.bar.parentNode.removeChild(this.bar);
    }
    parent.appendChild(this.bar);
  }

    var x = this.body.util.toScreen(this.customTime);

    var locale = this.options.locales[this.options.locale];
    if (!locale) {
      if (!this.warned) {
        console.log('WARNING: options.locales[\'' + this.options.locale + '\'] not found. See http://visjs.org/docs/timeline.html#Localization');
        this.warned = true;
      }
      locale = this.options.locales['en']; // fall back on english when not available
    }
    var title = locale.time + ': ' + moment(this.customTime).format('dddd, MMMM Do YYYY, H:mm:ss');
    title = title.charAt(0).toUpperCase() + title.substring(1);
  var x = this.body.util.toScreen(this.customTime);

    this.bar.style.left = x + 'px';
    this.bar.title = title;
  }
  else {
    // remove the line from the DOM
    if (this.bar.parentNode) {
      this.bar.parentNode.removeChild(this.bar);
  var locale = this.options.locales[this.options.locale];
  if (!locale) {
    if (!this.warned) {
      console.log('WARNING: options.locales[\'' + this.options.locale + '\'] not found. See http://visjs.org/docs/timeline.html#Localization');
      this.warned = true;
    }
    locale = this.options.locales['en']; // fall back on english when not available
  }
  var title = locale.time + ': ' + moment(this.customTime).format('dddd, MMMM Do YYYY, H:mm:ss');
  title = title.charAt(0).toUpperCase() + title.substring(1);

  this.bar.style.left = x + 'px';
  this.bar.title = title;

  return false;
 };

 /**
 * Remove the CustomTime from the DOM
 */
 CustomTime.prototype.hide = function () {
  // remove the line from the DOM
  if (this.bar.parentNode) {
    this.bar.parentNode.removeChild(this.bar);
  }
 };

 /**
 * Set custom time.
 * @param {Date | number | string} time
@ -211,4 +211,22 @@ CustomTime.prototype._onDragEnd = function (event) {
  event.stopPropagation();
 };

 /**
 * Find a custom time from an event target:
 * searches for the attribute 'custom-time' in the event target's element tree
 * @param {Event} event
 * @return {CustomTime | null} customTime
 */
 CustomTime.customTimeFromTarget = function(event) {
  var target = event.target;
  while (target) {
    if (target.hasOwnProperty('custom-time')) {
      return target['custom-time'];
    }
    target = target.parentNode;
  }

  return null;
 };

 module.exports = CustomTime;
--- a/lib/timeline/locales.js
+++ b/lib/timeline/locales.js
@ -8,7 +8,7 @@ exports['en_US'] = exports['en'];

 // Dutch
 exports['nl'] = {
  current: 'aangepaste',
  current: 'huidige',
  time: 'tijd'
 };
 exports['nl_NL'] = exports['nl'];
--- a/test/timeline.html
+++ b/test/timeline.html
@ -150,7 +150,6 @@
    //maxHeight: 200,
    //height: 200,
    showCurrentTime: true,
    showCustomTime: true,
    format: {
      minorLabels: {
        'weekday':    'dddd D',
@ -178,6 +177,8 @@
  var timeline = new vis.Timeline(container, items, options);
  console.timeEnd('create timeline');

  timeline.addCustomTime(moment().add(1, 'day'));

  timeline.on('select', function (selection) {
    console.log('select', selection);
  });