#1286 new save()/restore() API

* added new api to save and relod  layouts and test cases showing usage
* GridstackWidget -> GridStackWidget typo fix

Author: adumesny

README.md

@@ -335,7 +335,7 @@ make sure to read v1.0.0 migration first!
 v2.x is a Typescript rewrite of 1.x, removing all jquery events, using classes and overall code cleanup. Your code might need to change from 1.x
 
 1. In general methods that used no args (getter) vs setter are not used in Typescript. 
-Also legacy methods that used to take tons of parameters will now take a single object (typically `GridstackOptions` or `GridstackWidget`).
+Also legacy methods that used to take tons of parameters will now take a single object (typically `GridstackOptions` or `GridStackWidget`).
 
 ```
 removed `addWidget(el, x, y, width, ...)` --> use the widget options version instead `addWidget(el, {with, ...})`

demo/serialization.html

@@ -14,9 +14,11 @@
     <h1>Serialization demo</h1>
     <a onClick="saveGrid()" class="btn btn-primary" href="#">Save</a>
     <a onClick="loadGrid()" class="btn btn-primary" href="#">Load</a>
+    <a onClick="saveGridManual()" class="btn btn-primary" href="#">Save Manual</a>
+    <a onClick="loadGridManual()" class="btn btn-primary" href="#">Load Manual</a>
     <a onClick="clearGrid()" class="btn btn-primary" href="#">Clear</a>
     <br/><br/>
-    <div class="grid-stack"></div>
+    <div class="grid-stack"></div>    
     <hr/>
     <textarea id="saved-data" cols="100" rows="20" readonly="readonly"></textarea>
   </div>
@@ -31,31 +33,56 @@ <h1>Serialization demo</h1>
     });
 
     let serializedData = [
-      {x: 0, y: 0, width: 2, height: 2},
-      {x: 3, y: 1, width: 1, height: 2},
-      {x: 4, y: 1, width: 1, height: 1},
-      {x: 2, y: 3, width: 3, height: 1},
-      {x: 1, y: 3, width: 1, height: 1}
+      {x: 0, y: 0, width: 2, height: 2, id: '0'},
+      {x: 3, y: 1, width: 1, height: 2, id: '1'},
+      {x: 4, y: 1, width: 1, height: 1, id: '2'},
+      {x: 2, y: 3, width: 3, height: 1, id: '3'},
+      {x: 1, y: 3, width: 1, height: 1, id: '4'}
     ];
 
+    // NEW 2.x method
     loadGrid = function() {
-      grid.removeAll();
+      grid.restore(serializedData, true);
+    }
+
+    // NEW 2.x method
+    saveGrid = function() {
+      serializedData = grid.save();
+      document.querySelector('#saved-data').value = JSON.stringify(serializedData, null, '  ');
+    }
+
+    // old (pre 2.x) way to manually load a grid
+    loadGridManual = function() {
       let items = GridStack.Utils.sort(serializedData);
       grid.batchUpdate();
-      items.forEach(function (node) {
-        grid.addWidget('<div><div class="grid-stack-item-content"></div></div>', node);
-      });
+
+      if (grid.engine.nodes.length === 0) {
+        // load from empty
+        items.forEach(function (item) {
+          grid.addWidget('<div><div class="grid-stack-item-content">' + item.id + '</div></div>', item);
+        });
+      } else {
+        // else update existing nodes (instead of calling grid.removeAll())
+        grid.engine.nodes.forEach(function (node) {
+          let item = items.find(function(e) { return e.id === node.id});
+          grid.update(node.el, item.x, item.y, item.width, item.height);
+        });
+      }
+
       grid.commit();
     };
 
-    saveGrid = function() {
+    // old (pre 2.x) way to manually save a grid
+    saveGridManual = function() {
       serializedData = [];
       grid.engine.nodes.forEach(function(node) {
         serializedData.push({
           x: node.x,
           y: node.y,
           width: node.width,
-          height: node.height
+          height: node.height,
+          id: node.id,
+          custom: 'save anything here'
         });
       });
       document.querySelector('#saved-data').value = JSON.stringify(serializedData, null, '  ');

doc/CHANGES.md

@@ -39,6 +39,7 @@ Change log
 - re-write to native Typescript, removing all JQuery from main code and API (drag&drop plugin still using for now)
 - 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)
 
 ## 1.1.2 (2020-05-17)
 

doc/README.md

@@ -36,6 +36,7 @@ gridstack.js API
   - [float(val?)](#floatval)
   - [getCellHeight()](#getcellheight)
   - [getCellFromPixel(position[, useOffset])](#getcellfrompixelposition-useoffset)
+  - [getGridItems(): GridItemHTMLElement[]](#getgriditems-griditemhtmlelement)
   - [isAreaEmpty(x, y, width, height)](#isareaemptyx-y-width-height)
   - [locked(el, val)](#lockedel-val)
   - [makeWidget(el)](#makewidgetel)
@@ -49,6 +50,8 @@ 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)
   - [update(el, x, y, width, height)](#updateel-x-y-width-height)
@@ -83,6 +86,8 @@ gridstack.js API
 - `disableDrag` - disallows dragging of widgets (default: `false`).
 - `disableOneColumnMode` - disables the onColumnMode when the grid width is less than minWidth (default: 'false')
 - `disableResize` - disallows resizing of widgets (default: `false`).
+- `dragIn` - specify the class of items that can be dragged into the grid (ex: dragIn: '.newWidget'
+- `dragInOptions` - options for items that can be dragged into the grid (ex: dragInOptions: { revert: 'invalid', scroll: false, appendTo: 'body', helper: 'clone' }
 - `draggable` - allows to override jQuery UI draggable options. (default: `{handle: '.grid-stack-item-content', scroll: false, appendTo: 'body', containment: null}`)
 - `dragOut` to let user drag nested grid items out of a parent or not (default false) See [example](http://gridstackjs.com/demo/nested.html)
 - `float` - enable floating widgets (default: `false`) See [example](http://gridstackjs.com/demo/float.html)
@@ -361,6 +366,10 @@ Parameters :
 
 Returns an object with properties `x` and `y` i.e. the column and row in the grid.
 
+### getGridItems(): GridItemHTMLElement[]
+
+Return list of GridItem HTML dom elements (excluding temporary placeholder)
+
 ### isAreaEmpty(x, y, width, height)
 
 Checks if specified area is empty.
@@ -464,6 +473,17 @@ 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()`
+- see [example](http://gridstackjs.com/demo/serialization.html)
+
 ### setAnimation(doAnimate)
 
 Toggle the grid animation state.  Toggles the `grid-stack-animate` class.

spec/gridstack-spec.ts

@@ -7,10 +7,10 @@ describe('gridstack', function() {
   // grid has 4x2 and 4x4 top-left aligned - used on most test cases
   let gridHTML =
   '<div class="grid-stack">' +
-  '  <div class="grid-stack-item" data-gs-x="0" data-gs-y="0" data-gs-width="4" data-gs-height="2" id="item1">' +
+  '  <div class="grid-stack-item" data-gs-x="0" data-gs-y="0" data-gs-width="4" data-gs-height="2" data-gs-id="item1" id="item1">' +
   '    <div class="grid-stack-item-content">item 1</div>' +
   '  </div>' +
-  '  <div class="grid-stack-item" data-gs-x="4" data-gs-y="0" data-gs-width="4" data-gs-height="4" id="item2">' +
+  '  <div class="grid-stack-item" data-gs-x="4" data-gs-y="0" data-gs-width="4" data-gs-height="4" data-gs-id="item2" id="item2">' +
   '    <div class="grid-stack-item-content">item 2</div>' +
   '  </div>' +
   '</div>';
@@ -1469,6 +1469,38 @@ describe('gridstack', function() {
 
   });
 
+  describe('save & restore', function() {
+    beforeEach(function() {
+      document.body.insertAdjacentHTML('afterbegin', gridstackHTML);
+    });
+    afterEach(function() {
+      document.body.removeChild(document.getElementById('gs-cont'));
+    });
+    it('save layout', function() {
+      let grid = GridStack.init();
+      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() {
+      let grid = GridStack.init();
+      grid.restore([{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'}]);
+    });
+    it('restore move 1 item, delete others', function() {
+      let grid = GridStack.init();
+      grid.restore([{x:2, height:1, id:'item2'}], true);
+      let layout = grid.save();
+      expect(layout).toEqual([{x:2, y:0, width:4, height:1, id:'item2'}]);
+    });
+    it('restore add new, delete others', function() {
+      let grid = GridStack.init();
+      grid.restore([{width:2, height:1, id:'item3'}], true);
+      let layout = grid.save();
+      expect(layout).toEqual([{x:0, y:0, width:2, height:1, id:'item3'}]);
+    });
+  });
+
  // ..and finally track log warnings at the end, instead of displaying them....
   describe('obsolete warnings', function() {
     console.warn = jasmine.createSpy('log'); // track warnings instead of displaying them

src/gridstack-engine.ts

@@ -7,7 +7,7 @@
 */
 
 import { Utils, obsolete } from './utils';
-import { GridStackNode } from './types';
+import { GridStackNode, GridStackWidget } from './types';
 
 export type onChangeCB = (nodes: GridStackNode[], removeDOM?: boolean) => void;
 
@@ -466,6 +466,26 @@ export class GridStackEngine {
     return this;
   }
 
+  /** saves the current layout returning a list of widgets for serialization */
+  public save(): GridStackWidget[] {
+    let widgets: GridStackWidget[] = [];
+    Utils.sort(this.nodes);
+    this.nodes.forEach(n => {
+      let w: GridStackNode = {};
+      for (let key in n) { if (key[0] !== '_' && n[key] !== null && n[key] !== undefined ) w[key] = n[key]; }
+      // delete other internals
+      delete w.el;
+      delete w.grid;
+      // delete default values (will be re-created on read)
+      if (!w.autoPosition) delete w.autoPosition;
+      if (!w.noResize) delete w.noResize;
+      if (!w.noMove) delete w.noMove;
+      if (!w.locked) delete w.locked;
+      widgets.push(w);
+    });
+    return widgets;
+  }
+
   /** @internal called whenever a node is added or moved - updates the cached layouts */
   public layoutsNodesChange(nodes: GridStackNode[]): GridStackEngine {
     if (!this._layouts || this._ignoreLayoutsNodeChange) return this;
@@ -614,7 +634,7 @@ export class GridStackEngine {
   private getGridHeight = obsolete(this, GridStackEngine.prototype.getRow, 'getGridHeight', 'getRow', 'v1.0.0');
 }
 
-/** @internal class to store per column layout bare minimal info (subset of GridstackWidget) */
+/** @internal class to store per column layout bare minimal info (subset of GridStackWidget) */
 interface Layout {
   x: number;
   y: number;

src/gridstack.ts

@@ -8,7 +8,7 @@
 
 import { GridStackEngine } from './gridstack-engine';
 import { obsoleteOpts, obsoleteOptsDel, obsoleteAttr, obsolete, Utils } from './utils';
-import { GridItemHTMLElement, GridstackWidget, GridStackNode, GridstackOptions, numberOrString } from './types';
+import { GridItemHTMLElement, GridStackWidget, GridStackNode, GridstackOptions, numberOrString } from './types';
 import { GridStackDragDropPlugin } from './gridstack-dragdrop-plugin';
 
 export type GridStackElement = string | HTMLElement | GridItemHTMLElement;
@@ -310,14 +310,14 @@ export class GridStack {
    * @param el html element or string definition to add
    * @param options widget position/size options (optional) - see GridStackWidget
    */
-  public addWidget(el: GridStackElement, options?: GridstackWidget): GridItemHTMLElement {
+  public addWidget(el: GridStackElement, options?: GridStackWidget): GridItemHTMLElement {
 
     // support legacy call for now ?
     if (arguments.length > 2) {
       console.warn('gridstack.ts: `addWidget(el, x, y, width...)` is deprecated. Use `addWidget(el, {x, y, width,...})`. It will be removed soon');
       // eslint-disable-next-line prefer-rest-params
       let a = arguments, i = 1,
-        opt: GridstackWidget = { x:a[i++], y:a[i++], width:a[i++], height:a[i++], autoPosition:a[i++],
+        opt: GridStackWidget = { x:a[i++], y:a[i++], width:a[i++], height:a[i++], autoPosition:a[i++],
           minWidth:a[i++], maxWidth:a[i++], minHeight:a[i++], maxHeight:a[i++], id:a[i++] };
       return this.addWidget(el, opt);
     }
@@ -342,6 +342,35 @@ export class GridStack {
     return this.makeWidget(el);
   }
 
+  /** 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) {
+    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);
+        }
+      });
+    }
+    // now add/update the widgets
+    items.forEach(w => {
+      let item = this.engine.nodes.find(n => n.id === w.id);
+      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);
+      }
+    });
+    this.commit();
+  }
+
   /**
    * Initializes batch updates. You will see no changes until `commit()` method is called.
    */
@@ -465,7 +494,7 @@ export class GridStack {
     return this.opts.column;
   }
 
-  /** returns an array of grid HTML elements (no placeholder) - used internally to iterate through our children */
+  /** returns an array of grid HTML elements (no placeholder) - used to iterate through our children */
   public getGridItems(): GridItemHTMLElement[] {
     return Array.from(this.el.children)
       .filter((el: HTMLElement) => el.matches('.' + this.opts.itemClass) && !el.matches('.' + this.opts.placeholderClass)) as GridItemHTMLElement[];
@@ -1380,7 +1409,7 @@ export class GridStack {
   }
 
   /** @internal call to write any default attributes back to element */
-  private _writeAttr(el: HTMLElement, node: GridstackWidget): GridStack {
+  private _writeAttr(el: HTMLElement, node: GridStackWidget): GridStack {
     if (!node) return this;
     this._writeAttrs(el, node.x, node.y, node.width, node.height);
 
@@ -1418,7 +1447,7 @@ export class GridStack {
   }
 
   /** @internal call to read any default attributes from element */
-  private _readAttr(el: HTMLElement, node: GridStackNode = {}): GridstackWidget {
+  private _readAttr(el: HTMLElement, node: GridStackNode = {}): GridStackWidget {
     node.x = Utils.toNumber(el.getAttribute('data-gs-x'));
     node.y = Utils.toNumber(el.getAttribute('data-gs-y'));
     node.width = Utils.toNumber(el.getAttribute('data-gs-width'));

src/types.ts

@@ -166,7 +166,7 @@ export interface GridstackOptions {
 /**
  * Gridstack Widget creation options
  */
-export interface GridstackWidget {
+export interface GridStackWidget {
   /** widget position x (default?: 0) */
   x?: number;
   /** widget position y (default?: 0) */
@@ -235,7 +235,7 @@ export interface DDDragInOpt extends DDDragOpt {
 /**
  * internal descriptions describing the items in the grid
  */
-export interface GridStackNode extends GridstackWidget {
+export interface GridStackNode extends GridStackWidget {
   /** pointer back to HTML element */
   el?: GridItemHTMLElement;
   /** pointer back to Grid instance */

src/utils.ts

@@ -6,7 +6,7 @@
  * gridstack.js may be freely distributed under the MIT license.
 */
 
-import { GridstackWidget, GridStackNode, GridstackOptions, numberOrString } from './types';
+import { GridStackWidget, GridStackNode, GridstackOptions, numberOrString } from './types';
 
 /** checks for obsolete method names */
 export function obsolete(self, f, oldName: string, newName: string, rev: string) {
@@ -51,7 +51,7 @@ export function obsoleteAttr(el: HTMLElement, oldName: string, newName: string,
 export class Utils {
 
   /** returns true if a and b overlap */
-  static isIntercepted(a: GridstackWidget, b: GridstackWidget): boolean {
+  static isIntercepted(a: GridStackWidget, b: GridStackWidget): boolean {
     return !(a.x + a.width <= b.x || b.x + b.width <= a.x || a.y + a.height <= b.y || b.y + b.height <= a.y);
   }