TS: support callback for load()

* more fix for #1286
changed method to load() (rather than restore())
* added a callback function in additon to boolean which default to true (will add/remove widgets by default)

Author: adumesny

demo/serialization.html

@@ -42,7 +42,7 @@ <h1>Serialization demo</h1>
 
     // NEW 2.x method
     loadGrid = function() {
-      grid.restore(serializedData, true);
+      grid.load(serializedData, true);
     }
 
     // NEW 2.x method

doc/CHANGES.md

@@ -40,7 +40,7 @@ Change log
 - re-write to native Typescript, removing all JQuery from main code and API (drag&drop plugin still using for now which use latest v3.5.1)
 - add `getGridItems()` to return list of HTML grid items
 - add `{dragIn | dragInOptions}` grid attributes to handle external drag&drop items
-- add `save()` and `restore()` to serialize grids from JSON, saving all attributes (not just w,h,x,y) [1286](https://github.com/gridstack/gridstack.js/issues/1286)
+- add `save()` and `load()` to serialize grids from JSON, saving all attributes (not just w,h,x,y) [1286](https://github.com/gridstack/gridstack.js/issues/1286)
 - add `margin` to replace `verticalMargin` which affects both dimensions in code, rather than one in code the other in CSS.
 You can now have perfect square cells (default) [723](https://github.com/gridstack/gridstack.js/issues/723)
 - fix [1299](https://github.com/gridstack/gridstack.js/pull/1299) many columns round-off error

doc/README.md

@@ -39,6 +39,7 @@ gridstack.js API
   - [getGridItems(): GridItemHTMLElement[]](#getgriditems-griditemhtmlelement)
   - [getMargin()](#getmargin)
   - [isAreaEmpty(x, y, width, height)](#isareaemptyx-y-width-height)
+  - [load(layout: GridStackWidget[], boolean | ((w: GridStackWidget, add: boolean) => void)  = true)](#loadlayout-gridstackwidget-boolean--w-gridstackwidget-add-boolean--void---true)
   - [locked(el, val)](#lockedel-val)
   - [makeWidget(el)](#makewidgetel)
   - [margin(value: numberOrString)](#marginvalue-numberorstring)
@@ -52,7 +53,6 @@ gridstack.js API
   - [removeAll([removeDOM])](#removeallremovedom)
   - [resize(el, width, height)](#resizeel-width-height)
   - [resizable(el, val)](#resizableel-val)
-  - [restore(layout: GridStackWidget[], addAndRemove?: boolean)](#restorelayout-gridstackwidget-addandremove-boolean)
   - [save(): GridStackWidget[]](#save-gridstackwidget)
   - [setAnimation(doAnimate)](#setanimationdoanimate)
   - [setStatic(staticValue)](#setstaticstaticvalue)
@@ -383,6 +383,15 @@ returns current margin value.
 
 Checks if specified area is empty.
 
+### load(layout: GridStackWidget[], boolean | ((w: GridStackWidget, add: boolean) => void)  = true)
+
+- load the widgets from a list (see `save()`). This will call `update()` on each (matching by id) or add/remove widgets that are not there.
+- Optional `addAndRemove` boolean (default true) or callback method can be passed to control if and how missing widgets can be added/removed, giving the user control of insertion.
+
+- used to restore a grid layout for a saved layout list (see `save()`).
+- `addAndRemove` boolean (default true) or callback method can be passed to control if and how missing widgets can be added/removed, giving the user control of insertion.
+- see [example](http://gridstackjs.com/demo/serialization.html)
+
 ### locked(el, val)
 
 Locks/unlocks widget.
@@ -488,15 +497,9 @@ Enables/Disables resizing.
 - `el` - widget to modify
 - `val` - if `true` widget will be resizable.
 
-### restore(layout: GridStackWidget[], addAndRemove?: boolean)
-
-- used to restore a grid layout for a saved layout list (see `save()`).
-- Optional `addAndRemove` can be passed if new widgets should be added or removed if the are not present (`id` is used to look items up)
-- see [example](http://gridstackjs.com/demo/serialization.html)
-
 ### save(): GridStackWidget[]
 
-- returns the layout of the grid that can be serialized (list of item non default attributes, not just w,y,x,y but also min/max and id). See `restore()`
+- returns the layout of the grid that can be serialized (list of item non default attributes, not just w,y,x,y but also min/max and id). See `load()`
 - see [example](http://gridstackjs.com/demo/serialization.html)
 
 ### setAnimation(doAnimate)

spec/gridstack-spec.ts

@@ -1504,7 +1504,7 @@ describe('gridstack', function() {
 
   });
 
-  describe('save & restore', function() {
+  describe('save & load', function() {
     beforeEach(function() {
       document.body.insertAdjacentHTML('afterbegin', gridstackHTML);
     });
@@ -1516,23 +1516,29 @@ describe('gridstack', function() {
       let layout = grid.save();
       expect(layout).toEqual([{x:0, y:0, width:4, height:2, id:'item1'}, {x:4, y:0, width:4, height:4, id:'item2'}]);
     });
-    it('restore size 1 item', function() {
+    it('load move 1 item, delete others', function() {
       let grid = GridStack.init();
-      grid.restore([{height:3, id:'item1'}]);
+      grid.load([{x:2, height:1, id:'item2'}]);
       let layout = grid.save();
-      expect(layout).toEqual([{x:0, y:0, width:4, height:3, id:'item1'}, {x:4, y:0, width:4, height:4, id:'item2'}]);
+      expect(layout).toEqual([{x:2, y:0, width:4, height:1, id:'item2'}]);
     });
-    it('restore move 1 item, delete others', function() {
+    it('load add new, delete others', function() {
       let grid = GridStack.init();
-      grid.restore([{x:2, height:1, id:'item2'}], true);
+      grid.load([{width:2, height:1, id:'item3'}], true);
       let layout = grid.save();
-      expect(layout).toEqual([{x:2, y:0, width:4, height:1, id:'item2'}]);
+      expect(layout).toEqual([{x:0, y:0, width:2, height:1, id:'item3'}]);
     });
-    it('restore add new, delete others', function() {
+    it('load size 1 item only', function() {
       let grid = GridStack.init();
-      grid.restore([{width:2, height:1, id:'item3'}], true);
+      grid.load([{height:3, id:'item1'}], false);
       let layout = grid.save();
-      expect(layout).toEqual([{x:0, y:0, width:2, height:1, id:'item3'}]);
+      expect(layout).toEqual([{x:0, y:0, width:4, height:3, id:'item1'}, {x:4, y:0, width:4, height:4, id:'item2'}]);
+    });
+    it('load size 1 item only with callback', function() {
+      let grid = GridStack.init();
+      grid.load([{height:3, id:'item1'}], () => {});
+      let layout = grid.save();
+      expect(layout).toEqual([{x:0, y:0, width:4, height:3, id:'item1'}, {x:4, y:0, width:4, height:4, id:'item2'}]);
     });
   });
 

src/gridstack.ts

@@ -349,17 +349,29 @@ export class GridStack {
   /** saves the current layout returning a list of widgets for serialization */
   public save(): GridStackWidget[] { return this.engine.save(); }
 
-  /** restore the widgets from a list. This will call update() on each (matching by id),
-   * or optionally add/remove widgets that are not there (either a boolean or a callback method) */
-  public restore(layout: GridStackWidget[], addAndRemove?: boolean) {
+  /**
+   * load the widgets from a list. This will call update() on each (matching by id) or add/remove widgets that are not there.
+   *
+   * @param layout list of widgets definition to update/create
+   * @param addAndRemove boolean (default true) or callback method can be passed to control if and how missing widgets can be added/removed, giving
+   * the user control of insertion.
+   *
+   * @example
+   * see http://gridstackjs.com/demo/serialization.html
+   **/
+  public load(layout: GridStackWidget[], addAndRemove: boolean | ((w: GridStackWidget, add: boolean) => void)  = true) {
     let items = GridStack.Utils.sort(layout);
     this.batchUpdate();
     // see if any items are missing from new layout and need to be removed first
     if (addAndRemove) {
       this.engine.nodes.forEach(n => {
         let item = items.find(w => n.id === w.id);
         if (!item) {
-          this.removeWidget(n.el);
+          if (typeof(addAndRemove) === 'function') {
+            addAndRemove(n, false);
+          } else {
+            this.removeWidget(n.el);
+          }
         }
       });
     }
@@ -369,7 +381,11 @@ export class GridStack {
       if (item) {
         this.update(item.el, w.x, w.y, w.width, w.height); // TODO: full update
       } else if (addAndRemove) {
-        this.addWidget('<div><div class="grid-stack-item-content"></div></div>', w);
+        if (typeof(addAndRemove) === 'function') {
+          addAndRemove(w, true);
+        } else {
+          this.addWidget('<div><div class="grid-stack-item-content"></div></div>', w);
+        }
       }
     });
     this.commit();