added batchUpdate(false) to replace commit()

demo/react-hooks.html

@@ -71,7 +71,7 @@ <h2>Uncontrolled stack</h2>
       grid.batchUpdate()
       grid.removeAll(false)
       items.forEach(({ id }) => grid.makeWidget(refs.current[id].current))
-      grid.commit()
+      grid.batchUpdate(false)
     }, [items])
 
     return (

doc/CHANGES.md

@@ -5,6 +5,7 @@ Change log
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*
 
+- [TBD](#tbd)
 - [5.1.1 (2022-06-16)](#511-2022-06-16)
 - [5.1.0 (2022-05-21)](#510-2022-05-21)
 - [5.0.0 (2022-01-10)](#500-2022-01-10)
@@ -68,6 +69,9 @@ Change log
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+## TBD
+* changed `commit()` to be `batchUpdate(false)` to make it easier to turn batch on/off. updated doc. old API remains for now
+
 ## 5.1.1 (2022-06-16)
 * fix v5.1.0 regression [#1973](https://github.com/gridstack/gridstack.js/issues/1973) DnD Snap to Animation
 

doc/README.md

@@ -30,11 +30,10 @@ gridstack.js API
   - [`GridStack.registerEngine(engineClass: typeof GridStackEngine)`](#gridstackregisterengineengineclass-typeof-gridstackengine)
 - [API](#api)
   - [`addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)`](#addwidgetel-gridstackwidget--gridstackelement-options-gridstackwidget)
-  - [`batchUpdate()`](#batchupdate)
+  - [`batchUpdate(flag = true)`](#batchupdateflag--true)
   - [`compact()`](#compact)
   - [`cellHeight(val: number, update = true)`](#cellheightval-number-update--true)
   - [`cellWidth()`](#cellwidth)
-  - [`commit()`](#commit)
   - [`column(column: number, layout: ColumnOptions = 'moveScale')`](#columncolumn-number-layout-columnoptions--movescale)
   - [`destroy([removeDOM])`](#destroyremovedom)
   - [`disable()`](#disable)
@@ -348,9 +347,9 @@ grid.addWidget({w: 3, content: 'hello'});
 grid.addWidget('<div class="grid-stack-item"><div class="grid-stack-item-content">hello</div></div>', {w: 3});
 ```
 
-### `batchUpdate()`
+### `batchUpdate(flag = true)`
 
-starts batch updates. You will see no changes until `commit()` method is called.
+use before calling a bunch of `addWidget()` to prevent un-necessary relayouts in between (more efficient) and get a single event callback. You will see no changes until `batchUpdate(false)` is called.
 
 ### `compact()`
 
@@ -368,10 +367,6 @@ grid.cellHeight(grid.cellWidth() * 1.2);
 
 Gets current cell width (grid width / # of columns).
 
-### `commit()`
-
-Ends batch updates. Updates DOM nodes. You must call it after `batchUpdate()`.
-
 ### `column(column: number, layout: ColumnOptions = 'moveScale')`
 
 set the number of columns in the grid. Will update existing widgets to conform to new number of columns,

spec/e2e/html/810-many-columns.html

@@ -38,7 +38,7 @@ <h1>Many Columns demo</h1>
     for (; count <= COLUMNS;) {
       this.addNewWidget(); 
     }
-    grid.commit();
+    grid.batchUpdate(false);
   </script>
 </body>
 </html>

spec/gridstack-engine-spec.ts

@@ -186,8 +186,8 @@ describe('gridstack engine', function() {
       engine.batchUpdate(); // double for code coverage
       expect(engine.batchMode).toBeTrue();
       expect(engine.float).toEqual(true);
-      engine.commit();
-      engine.commit();
+      engine.batchUpdate(false);
+      engine.batchUpdate(false);
       expect(engine.batchMode).not.toBeTrue();
       expect(engine.float).not.toBeTrue;
     });
@@ -197,7 +197,7 @@ describe('gridstack engine', function() {
       engine.batchUpdate();
       expect(engine.batchMode).toBeTrue();
       expect(engine.float).toEqual(true);
-      engine.commit();
+      engine.batchUpdate(false);
       expect(engine.batchMode).not.toBeTrue();
       expect(engine.float).toEqual(true);
     });
@@ -214,7 +214,7 @@ describe('gridstack engine', function() {
       engine.batchUpdate();
       expect(engine.batchMode).toBeTrue();
       expect(engine.float).toEqual(true);
-      engine.commit();
+      engine.batchUpdate(false);
       expect(engine.batchMode).not.toBeTrue();
       expect(engine.float).toEqual(true);
     });

spec/gridstack-spec.ts

@@ -433,8 +433,8 @@ describe('gridstack', function() {
       let el1 = grid.addWidget({w:1, h:1});
       let el2 = grid.addWidget({x:2, y:0, w:2, h:1});
       let el3 = grid.addWidget({x:1, y:0, w:1, h:2});
-      grid.commit();
-      grid.commit();
+      grid.batchUpdate(false);
+      grid.batchUpdate(false);
 
       // items are item1[1x1], item3[1x1], item2[2x1]
       expect(parseInt(el1.getAttribute('gs-x'))).toBe(0);
@@ -1848,6 +1848,15 @@ describe('gridstack', function() {
       expect((grid as any).willItFit(0, 0, 1, 3, false)).toBe(true);
       expect((grid as any).willItFit(0, 0, 1, 4, false)).toBe(false);
     });
+    it('warning if OLD commit() is called', function() {
+      let grid = GridStack.init();
+      grid.batchUpdate(true);
+      expect(grid.engine.batchMode).toBe(true);
+      grid.commit(); // old API
+      expect(grid.engine.batchMode).toBe(false);
+      // expect(console.warn).toHaveBeenCalledWith('gridstack.js: Function `setGridWidth` is deprecated in v0.5.3 and has been replaced with `column`. It will be **completely** removed in v1.0');
+    });
+
     /* saving as example
     it('warning if OLD setGridWidth is called', function() {
       let grid: any = GridStack.init();

src/gridstack-engine.ts

@@ -54,21 +54,19 @@ export class GridStackEngine {
     this.onChange = opts.onChange;
   }
 
-  public batchUpdate(): GridStackEngine {
-    if (this.batchMode) return this;
-    this.batchMode = true;
-    this._prevFloat = this._float;
-    this._float = true; // let things go anywhere for now... commit() will restore and possibly reposition
-    return this.saveInitial(); // since begin update (which is called multiple times) won't do this
-  }
-
-  public commit(): GridStackEngine {
-    if (!this.batchMode) return this;
-    this.batchMode = false;
-    this._float = this._prevFloat;
-    delete this._prevFloat;
-    return this._packNodes()
-      ._notify();
+  public batchUpdate(flag = true): GridStackEngine {
+    if (!!this.batchMode === flag) return this;
+    this.batchMode = flag;
+    if (flag) {
+      this._prevFloat = this._float;
+      this._float = true; // let things go anywhere for now... will restore and possibly reposition later
+      this.saveInitial(); // since begin update (which is called multiple times) won't do this
+    } else {
+      this._float = this._prevFloat;
+      delete this._prevFloat;
+      this._packNodes()._notify();
+    }
+    return this;
   }
 
   // use entire row for hitting area (will use bottom reverse sorted first) if we not actively moving DOWN and didn't already skip
@@ -252,7 +250,7 @@ export class GridStackEngine {
       this.addNode(node, false); // 'false' for add event trigger
       node._dirty = true; // will force attr update
     });
-    return this.commit();
+    return this.batchUpdate(false);
   }
 
   /** enable/disable floating widgets (default: `false`) See [example](http://gridstackjs.com/demo/float.html) */
@@ -829,7 +827,7 @@ export class GridStackEngine {
       this.addNode(node, false); // 'false' for add event trigger
       delete node._orig; // make sure the commit doesn't try to restore things back to original
     });
-    this.commit();
+    this.batchUpdate(false);
     delete this._inColumnResize;
     return this;
   }

src/gridstack-h5.ts

@@ -1,6 +1,6 @@
-/**
- * index-h5.ts 5.1.1 - everything you need for a Grid that uses HTML5 native drag&drop
- * Copyright (c) 2021 Alain Dumesny - see GridStack root license
+/*!
+ * gridstack-h5.ts 5.1.1 - everything you need for a Grid that uses HTML5 native drag&drop
+ * Copyright (c) 2021 Alain Dumesny - see root license https://github.com/gridstack/gridstack.js/tree/master/LICENSE
  */
 
 export * from './types';

src/gridstack-jq.ts

@@ -1,5 +1,5 @@
-/**
- * index-jq.ts 5.1.1 - everything you need for a Grid that uses Jquery-ui drag&drop (original, full feature)
+/*!
+ * gridstack-jq.ts 5.1.1 - everything you need for a Grid that uses Jquery-ui drag&drop (original, full feature)
  * Copyright (c) 2021 Alain Dumesny - see GridStack root license
  */
 

src/gridstack-static.ts

@@ -1,5 +1,5 @@
-/**
- * index-static.ts 5.1.1 - much smaller, everything you need for a static Grid (non draggable, API driven)
+/*!
+ * gridstack-static.ts 5.1.1 - much smaller, everything you need for a static Grid (non draggable, API driven)
  * Copyright (c) 2021 Alain Dumesny - see GridStack root license
  */
 

src/gridstack.ts

@@ -6,7 +6,7 @@
  * see root license https://github.com/gridstack/gridstack.js/tree/master/LICENSE
  */
 import { GridStackEngine } from './gridstack-engine';
-import { Utils, HeightData } from './utils';
+import { Utils, HeightData, obsolete } from './utils';
 import { ColumnOptions, GridItemHTMLElement, GridStackElement, GridStackEventHandlerCallback,
   GridStackNode, GridStackOptions, GridStackWidget, numberOrString, DDUIData, DDDragInOpt, GridStackPosition } from './types';
 import { GridStackDDI } from './gridstack-ddi';
@@ -373,7 +373,7 @@ export class GridStack {
         });
       });
       elements.sort((a, b) => a.i - b.i).forEach(e => this._prepareElement(e.el));
-      this.commit();
+      this.batchUpdate(false);
     }
 
     this.setAnimation(this.opts.animate);
@@ -594,7 +594,7 @@ export class GridStack {
     });
 
     this.engine.removedNodes = removed;
-    this.commit();
+    this.batchUpdate(false);
 
     // after commit, clear that flag
     delete this._ignoreLayoutsNodeChange;
@@ -603,10 +603,16 @@ export class GridStack {
   }
 
   /**
-   * Initializes batch updates. You will see no changes until `commit()` method is called.
+   * use before calling a bunch of `addWidget()` to prevent un-necessary relayouts in between (more efficient)
+   * and get a single event callback. You will see no changes until `batchUpdate(false)` is called.
    */
-  public batchUpdate(): GridStack {
-    this.engine.batchUpdate();
+  public batchUpdate(flag = true): GridStack {
+    this.engine.batchUpdate(flag);
+    if (!flag) {
+      this._triggerRemoveEvent();
+      this._triggerAddEvent();
+      this._triggerChangeEvent();
+    }
     return this;
   }
 
@@ -685,17 +691,6 @@ export class GridStack {
     return (this.el.clientWidth || this.el.parentElement.clientWidth || window.innerWidth);
   }
 
-  /**
-   * Finishes batch updates. Updates DOM nodes. You must call it after batchUpdate.
-   */
-  public commit(): GridStack {
-    this.engine.commit();
-    this._triggerRemoveEvent();
-    this._triggerAddEvent();
-    this._triggerChangeEvent();
-    return this;
-  }
-
   /** re-layout grid items to reclaim any empty space */
   public compact(): GridStack {
     this.engine.compact();
@@ -1585,4 +1580,6 @@ export class GridStack {
   public _dragOrResize(el: GridItemHTMLElement, event: Event, ui: DDUIData, node: GridStackNode, cellWidth: number, cellHeight: number): void { return }
   /** @internal called when a node leaves our area (mouse out or shape outside) **/
   public _leave(el: GridItemHTMLElement, helper?: GridItemHTMLElement): void { return }
+  // legacy method removed
+  public commit(): GridStack { obsolete(this, this.batchUpdate(false), 'commit', 'batchUpdate', '5.2'); return this; }
 }

src/utils.ts

@@ -15,7 +15,7 @@ export interface HeightData {
 export function obsolete(self, f, oldName: string, newName: string, rev: string): (...args: any[]) => any {
   let wrapper = (...args) => {
     console.warn('gridstack.js: Function `' + oldName + '` is deprecated in ' + rev + ' and has been replaced ' +
-    'with `' + newName + '`. It will be **completely** removed in v1.0');
+    'with `' + newName + '`. It will be **removed** in a future release');
     return f.apply(self, args);
   }
   wrapper.prototype = f.prototype;
@@ -27,7 +27,7 @@ export function obsoleteOpts(opts: GridStackOptions, oldName: string, newName: s
   if (opts[oldName] !== undefined) {
     opts[newName] = opts[oldName];
     console.warn('gridstack.js: Option `' + oldName + '` is deprecated in ' + rev + ' and has been replaced with `' +
-      newName + '`. It will be **completely** removed in v1.0');
+      newName + '`. It will be **removed** in a future release');
   }
 }
 
@@ -44,7 +44,7 @@ export function obsoleteAttr(el: HTMLElement, oldName: string, newName: string,
   if (oldAttr !== null) {
     el.setAttribute(newName, oldAttr);
     console.warn('gridstack.js: attribute `' + oldName + '`=' + oldAttr + ' is deprecated on this object in ' + rev + ' and has been replaced with `' +
-      newName + '`. It will be **completely** removed in v1.0');
+      newName + '`. It will be **removed** in a future release');
   }
 }