Implemented configuration option `order: function` to define a custom ordering for the items (see #538, #324).

HISTORY.md

@@ -22,6 +22,8 @@ http://visjs.org
   and bottom (#665).
 - Implemented creating new range items by dragging in an empty space with the
   ctrl key down.
+- Implemented configuration option `order: function` to define a custom ordering
+  for the items (see #538, #324).
 - Fixed not property initializing with a DataView for groups.
 - Merged add custom timebar functionality, thanks @aytech!
 - Fixed #664: end of item not restored when canceling a move event.

docs/timeline.html

@@ -664,18 +664,19 @@ var options = {
     </td>
 </tr>
 
-<!-- TODO: cleanup option order
 <tr>
   <td>order</td>
   <td>Function</td>
   <td>none</td>
-  <td>Provide a custom sort function to order the items. The order of the
+  <td>
+    <p>Provide a custom sort function to order the items. The order of the
     items is determining the way they are stacked. The function
-    order is called with two parameters, both of type
-    `vis.components.items.Item`.
+    order is called with two arguments containing the data of two items to be
+    compared.
+    </p>
+    <p style="font-style: italic">IMPORTANT: Custom ordering is not suitable for large amounts of items. Keep the number of items in this configuration limited to not more than a few hundred.</p>
   </td>
 </tr>
--->
 
 <tr>
     <td>orientation</td>

examples/timeline/35_item_ordering.html

@@ -48,7 +48,7 @@
       id:      i,
       content: 'Item ' + i,
       start:   date.clone(),
-      end:     date.clone().add(2 + Math.round(Math.random() * 2), 'hour')
+      end:     date.clone().add(4, 'hour')
     });
   }
 

lib/timeline/component/Group.js

@@ -148,8 +148,6 @@ Group.prototype.getLabelWidth = function() {
 Group.prototype.redraw = function(range, margin, restack) {
   var resized = false;
 
-  this.visibleItems = this._updateVisibleItems(this.orderedItems, this.visibleItems, range);
-
   // force recalculation of the height of the items when the marker height changed
   // (due to the Timeline being attached to the DOM or changed from display:none to visible)
   var markerHeight = this.dom.marker.clientHeight;
@@ -165,18 +163,41 @@ Group.prototype.redraw = function(range, margin, restack) {
   }
 
   // reposition visible items vertically
-  var customOrderedItems = null;
-  if (this.itemSet.options.stack) { // TODO: ugly way to access options...
-    if (typeof this.itemSet.options.order === 'function' || false) {
-      customOrderedItems = this._getCustomOrderedItems();
-      stack.stack(customOrderedItems, margin, true);
+  if (typeof this.itemSet.options.order === 'function') {
+    // a custom order function
+
+    if (restack) {
+      // brute force restack of all items
+
+      // show all items
+      var me = this;
+      util.forEach(this.items, function (item) {
+        if (!item.displayed) {
+          item.redraw();
+          me.visibleItems.push(item);
+        }
+        item.repositionX();
+      });
+
+      // order all items and force a restacking
+      var customOrderedItems = this.orderedItems.byStart.slice().sort(function (a, b) {
+        return me.itemSet.options.order(a.data, b.data);
+      });
+      stack.stack(customOrderedItems, margin, true /* restack=true */);
     }
-    else {
+
+    this.visibleItems = this._updateVisibleItems(this.orderedItems, this.visibleItems, range);
+  }
+  else {
+    // no custom order function, lazy stacking
+    this.visibleItems = this._updateVisibleItems(this.orderedItems, this.visibleItems, range);
+
+    if (this.itemSet.options.stack) { // TODO: ugly way to access options...
       stack.stack(this.visibleItems, margin, restack);
     }
-  }
-  else { // no stacking
-    stack.nostack(this.visibleItems, margin, this.subgroups);
+    else { // no stacking
+      stack.nostack(this.visibleItems, margin, this.subgroups);
+    }
   }
 
   // recalculate the height of the group
@@ -490,23 +511,6 @@ Group.prototype._updateVisibleItems = function(orderedItems, oldVisibleItems, ra
   return visibleItems;
 };
 
-Group.prototype._getCustomOrderedItems = function () {
-  var customOrderedItems = this.orderedItems.byStart.filter(function (item) {
-    return item.height !== 0 || item.width !== 0;
-  });
-  var me = this;
-
-  customOrderedItems.sort(function (a, b) {
-    return me.itemSet.options.order(a.data, b.data);
-  });
-
-  customOrderedItems.forEach(function (item) {
-    item.repositionX();
-  });
-
-  return customOrderedItems;
-};
-
 Group.prototype._traceVisible = function (initialPos, items, visibleItems, visibleItemsLookup, breakCondition) {
   var item;
   var i;

lib/timeline/component/item/BoxItem.js

@@ -151,9 +151,6 @@ BoxItem.prototype.hide = function() {
     if (dom.line.parentNode)  dom.line.parentNode.removeChild(dom.line);
     if (dom.dot.parentNode)   dom.dot.parentNode.removeChild(dom.dot);
 
-    this.top = null;
-    this.left = null;
-
     this.displayed = false;
   }
 };

lib/timeline/component/item/PointItem.js

@@ -144,9 +144,6 @@ PointItem.prototype.hide = function() {
       this.dom.point.parentNode.removeChild(this.dom.point);
     }
 
-    this.top = null;
-    this.left = null;
-
     this.displayed = false;
   }
 };

lib/timeline/component/item/RangeItem.js

@@ -140,9 +140,6 @@ RangeItem.prototype.hide = function() {
       box.parentNode.removeChild(box);
     }
 
-    this.top = null;
-    this.left = null;
-
     this.displayed = false;
   }
 };