diff --git a/demo/react-hooks.html b/demo/react-hooks.html index dbfb0a1cb..d56aedebd 100644 --- a/demo/react-hooks.html +++ b/demo/react-hooks.html @@ -71,7 +71,7 @@

Uncontrolled stack

grid.batchUpdate() grid.removeAll(false) items.forEach(({ id }) => grid.makeWidget(refs.current[id].current)) - grid.commit() + grid.batchUpdate(false) }, [items]) return ( diff --git a/doc/CHANGES.md b/doc/CHANGES.md index 8928e596b..9efa366de 100644 --- a/doc/CHANGES.md +++ b/doc/CHANGES.md @@ -5,6 +5,7 @@ Change log **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 +## 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 diff --git a/doc/README.md b/doc/README.md index 06fba7430..89418b9f5 100644 --- a/doc/README.md +++ b/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('
hello
', {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, diff --git a/spec/e2e/html/810-many-columns.html b/spec/e2e/html/810-many-columns.html index 1c1c89c18..b22acb152 100644 --- a/spec/e2e/html/810-many-columns.html +++ b/spec/e2e/html/810-many-columns.html @@ -38,7 +38,7 @@

Many Columns demo

for (; count <= COLUMNS;) { this.addNewWidget(); } - grid.commit(); + grid.batchUpdate(false); diff --git a/spec/gridstack-engine-spec.ts b/spec/gridstack-engine-spec.ts index 034489400..990cbcb43 100644 --- a/spec/gridstack-engine-spec.ts +++ b/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); }); diff --git a/spec/gridstack-spec.ts b/spec/gridstack-spec.ts index 7a5e761fe..89289795f 100644 --- a/spec/gridstack-spec.ts +++ b/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(); diff --git a/src/gridstack-engine.ts b/src/gridstack-engine.ts index fbe2c664b..6946871b2 100644 --- a/src/gridstack-engine.ts +++ b/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; } diff --git a/src/gridstack-h5.ts b/src/gridstack-h5.ts index bd67c4f8b..886dbed62 100644 --- a/src/gridstack-h5.ts +++ b/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'; diff --git a/src/gridstack-jq.ts b/src/gridstack-jq.ts index 7ea317a60..621a36a32 100644 --- a/src/gridstack-jq.ts +++ b/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 */ diff --git a/src/gridstack-static.ts b/src/gridstack-static.ts index f7f10d1e8..f7bbf0ba9 100644 --- a/src/gridstack-static.ts +++ b/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 */ diff --git a/src/gridstack.ts b/src/gridstack.ts index 8350b8911..281d0e98f 100644 --- a/src/gridstack.ts +++ b/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; } } diff --git a/src/utils.ts b/src/utils.ts index aaaa40dab..3e152b8e7 100644 --- a/src/utils.ts +++ b/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'); } }