new addGrid() method to create a grid + children

* added new API to create a grid and it's children
* load() will now recursively create nested grid
* updated nested.html to use new API
* fixed tests

TODO: next have save() work on nested grids (API will have to change)

Author: adumesny

demo/nested.html

@@ -25,47 +25,29 @@ <h1>Nested grids demo</h1>
     <a class="btn btn-primary" onClick="addNewWidget(grid2)" href="#">Add Widget Grid2</a>
     <br><br>
 
-    <div class="grid-stack top">
-      <div class="grid-stack-item" gs-x="0" gs-y="0" gs-w="1">
-        <div class="grid-stack-item-content">regular item</div>
-      </div>
-      <div class="grid-stack-item" gs-x="1" gs-y="0" gs-w="4" gs-h="4">
-        <div class="grid-stack-item-content">
-          nested 1 - can drag items out
-          <div class="grid-stack nested1">
-            <div class="grid-stack-item sub" gs-x="0" gs-y="0" gs-w="3"><div class="grid-stack-item-content">1</div></div>
-            <div class="grid-stack-item sub" gs-x="3" gs-y="0" gs-w="3"><div class="grid-stack-item-content">2</div></div>
-            <div class="grid-stack-item sub" gs-x="6" gs-y="0" gs-w="3"><div class="grid-stack-item-content">3</div></div>
-            <div class="grid-stack-item sub" gs-x="9" gs-y="0" gs-w="3"><div class="grid-stack-item-content">4</div></div>
-            <div class="grid-stack-item sub" gs-x="0" gs-y="1" gs-w="3"><div class="grid-stack-item-content">5</div></div>
-            <div class="grid-stack-item sub" gs-x="3" gs-y="1" gs-w="3"><div class="grid-stack-item-content">6</div></div>
-          </div>
-        </div>
-    </div>
-    <div class="grid-stack-item" gs-x="5" gs-y="0" gs-w="3" gs-h="4">
-      <div class="grid-stack-item-content">
-        nested 2 - constrained to parent (default)
-        <div class="grid-stack nested2">
-          <div class="grid-stack-item sub" gs-x="0" gs-y="0" gs-w="3"><div class="grid-stack-item-content">7</div></div>
-          <div class="grid-stack-item sub" gs-x="0" gs-y="3" gs-w="3"><div class="grid-stack-item-content">8</div></div>
-        </div>
-      </div>
-    </div>
+    <div class="grid-stack"></div>
   </div>
 
   <script type="text/javascript">
-    let nestOptions = {
+    let sub1 = [ {w: 3}, {w: 3}, {w: 3}, {w: 3}, {w: 3}, {w: 3}];
+    let sub2 = [ {w: 3}, {x:0, y: 1, w: 3}];
+    let count = 0;
+    [...sub1, ...sub2].forEach(d => d.content = String(count++));
+    let subOptions = {
       acceptWidgets: '.grid-stack-item.sub', // only pink sub items can be inserted, otherwise grid-items causes all sort of issues
-      dragOut: true, // let us drag them out!
       disableOneColumnMode: true, // nested are small, but still want N columns
+      itemClass: 'sub',
       margin: 1
     };
-    let grid0 = GridStack.init({cellHeight: 70}, '.grid-stack.top');
-    let grid1 = GridStack.init(nestOptions, '.grid-stack.nested1');
-    nestOptions.dragOut = false;
-    let grid2 = GridStack.init(nestOptions, '.grid-stack.nested2');
+    let items = [
+      {w:1, content: 'regular item'},
+      {x:1, w:4, h:4, content: 'nested 1 - can drag items out', subGrid: {children: sub1, dragOut: true, class: 'nested1', ...subOptions}},
+      {x:5, w:4, h:4, content: 'nested 2 - constrained to parent (default)', subGrid: {children: sub2, class: 'nested2', ...subOptions}},
+    ];
+
+    let grid = GridStack.init({cellHeight: 70});
+    grid.load(items);
 
-    let count = 9;
     addNewWidget = function(grid) {
       let node = {
         x: Math.round(12 * Math.random()),

doc/CHANGES.md

@@ -44,7 +44,8 @@ Change log
 
 ## 3.3.0-dev
 
-- TBD
+- add new `addGrid(parent, opts)` to create a grid and load children, which is used by `load()` to supports nested grids creation. see [nested.html](https://github.com/gridstack/gridstack.js/blob/develop/demo/nested.html) demo.
+
 ## 3.3.0 (2020-11-29)
 
 - the big news is we finally have a native HTML5 drag&drop plugin (zero jquery)! Huge thanks to [@rhlin](https://github.com/rhlin) for creating this in stealth mode. Read all about it in main doc.

doc/README.md

@@ -74,7 +74,9 @@ gridstack.js API
   * a string (ex: '100px', '10em', '10rem', '10%', `10vh')
   * 0 or null, in which case the library will not generate styles for rows. Everything must be defined in CSS files.
   * `'auto'` - height will be square cells initially.
+- `children`?: GridStackWidget[] - list of children item to create when calling load() or addGrid()
 - `column` - number of columns (default: `12`) which can change on the fly with `column(N)` as well. See [example](http://gridstackjs.com/demo/column.html)
+- `class`?: string - additional class on top of '.grid-stack' (which is required for our CSS) to differentiate this instance
 - `disableDrag` - disallows dragging of widgets (default: `false`).
 - `disableOneColumnMode` - disables the onColumnMode when the grid width is less than minW (default: 'false')
 - `disableResize` - disallows resizing of widgets (default: `false`).
@@ -130,6 +132,7 @@ You need to add `noResize` and `noMove` attributes to completely lock the widget
 - `resizeHandles` - sets resize handles for a specific widget.
 - `id`- (number | string) good for quick identification (for example in change event)
 - `content` - (string) html content to be added when calling `grid.load()/addWidget()` as content inside the item
+- `subGrid`: GridStackOptions - optional nested grid options and list of children
 
 ## Item attributes
 

spec/gridstack-spec.ts

@@ -607,10 +607,10 @@ describe('gridstack', function() {
       let items = Utils.getElements('.grid-stack-item');
       for (let i = 0; i < items.length; i++) {
         grid
-          .minW(items[i], 2)
-          .maxW(items[i], 3)
-          .minH(items[i], 4)
-          .maxH(items[i], 5);
+          .minWidth(items[i], 2)
+          .maxWidth(items[i], 3)
+          .minHeight(items[i], 4)
+          .maxHeight(items[i], 5);
       }
       for (let j = 0; j < items.length; j++) {
         expect(parseInt(items[j].getAttribute('gs-min-w'), 10)).toBe(2);
@@ -620,10 +620,10 @@ describe('gridstack', function() {
       }
       // remove all constrain
       grid
-        .minW('grid-stack-item', 0)
-        .maxW('.grid-stack-item', null)
-        .minH('grid-stack-item', undefined)
-        .maxH(undefined, 0);
+        .minWidth('grid-stack-item', 0)
+        .maxWidth('.grid-stack-item', null)
+        .minHeight('grid-stack-item', undefined)
+        .maxHeight(undefined, 0);
       for (let j = 0; j < items.length; j++) {
         expect(items[j].getAttribute('gs-min-w')).toBe(null);
         expect(items[j].getAttribute('gs-max-w')).toBe(null);
@@ -1753,7 +1753,7 @@ describe('gridstack', function() {
     });
     it('load size 1 item only with callback', function() {
       let grid = GridStack.init();
-      grid.load([{h:3, id:'gsItem1'}], () => {});
+      grid.load([{h:3, id:'gsItem1'}], () => null);
       let layout = grid.save(false);
       expect(layout).toEqual([{x:0, y:0, w:4, h:3, id:'gsItem1'}, {x:4, y:0, w:4, h:4, id:'gsItem2'}]);
     });

src/gridstack.ts

@@ -329,7 +329,7 @@ export class GridStack {
       let content = els ? (els as GridStackWidget).content || '' : '';
       options = els;
       let doc = document.implementation.createHTMLDocument();
-      doc.body.innerHTML = `<div class="grid-stack-item"><div class="grid-stack-item-content">${content}</div></div>`;
+      doc.body.innerHTML = `<div class="grid-stack-item ${this.opts.itemClass || ''}"><div class="grid-stack-item-content">${content}</div></div>`;
       el = doc.body.children[0] as HTMLElement;
     } else {
       el = els as HTMLElement;
@@ -372,6 +372,28 @@ export class GridStack {
     return list;
   }
 
+  /**
+   * call to create a grid with the given options, including loading any children
+   * @param parent HTML element parent to the grid
+   * @param opt grids options used to initialize the grid, and list of children
+   */
+  public addGrid(parent: HTMLElement, opt: GridStackOptions = {}): GridStack {
+    if (!parent) { return null; }
+
+    // create the grid element
+    let doc = document.implementation.createHTMLDocument();
+    doc.body.innerHTML = `<div class="grid-stack ${opt.class || ''}"></div>`;
+    let el = doc.body.children[0] as HTMLElement;
+    parent.append(el);
+
+    // create grid class and load any children
+    let grid = GridStack.init(opt, el);
+    if (opt.children) {
+      grid.load(opt.children);
+    }
+    return grid;
+  }
+
   /**
    * load the widgets from a list. This will call update() on each (matching by id) or add/remove widgets that are not there.
    *
@@ -382,7 +404,7 @@ export class GridStack {
    * @example
    * see http://gridstackjs.com/demo/serialization.html
    **/
-  public load(layout: GridStackWidget[], addAndRemove: boolean | ((w: GridStackWidget, add: boolean) => void)  = true): GridStack {
+  public load(layout: GridStackWidget[], addAndRemove: boolean | ((g: GridStack, w: GridStackWidget, add: boolean) => GridItemHTMLElement)  = true): GridStack {
     let items = GridStack.Utils.sort(layout, -1, this._prevColumn || this.opts.column);
 
     // if we're loading a layout into 1 column (_prevColumn is set only when going to 1) and items don't fit, make sure to save
@@ -394,34 +416,47 @@ export class GridStack {
 
     let removed: GridStackNode[] = [];
     this.batchUpdate();
+
     // see if any items are missing from new layout and need to be removed first
     if (addAndRemove) {
       let copyNodes = [...this.engine.nodes]; // don't loop through array you modify
       copyNodes.forEach(n => {
         let item = items.find(w => n.id === w.id);
         if (!item) {
           if (typeof(addAndRemove) === 'function') {
-            addAndRemove(n, false);
+            addAndRemove(this, n, false);
           } else {
             removed.push(n); // batch keep track
             this.removeWidget(n.el, true, false);
           }
         }
       });
     }
+
     // now add/update the widgets
     items.forEach(w => {
       let item = (w.id || w.id === 0) ? this.engine.nodes.find(n => n.id === w.id) : undefined;
       if (item) {
         this.update(item.el, w);
+        if (w.subGrid && w.subGrid.children) { // update any sub grid as well
+          let sub = item.el.querySelector('.grid-stack') as GridHTMLElement;
+          if (sub && sub.gridstack) {
+            sub.gridstack.load(w.subGrid.children); // TODO: support updating grid options ?
+          }
+        }
       } else if (addAndRemove) {
         if (typeof(addAndRemove) === 'function') {
-          addAndRemove(w, true);
+          w = addAndRemove(this, w, true).gridstackNode;
         } else {
-          this.addWidget(w);
+          w = this.addWidget(w).gridstackNode;
+        }
+        if (w.subGrid) { // see if there is a sub-grid to create too
+          let content = w.el.querySelector('.grid-stack-item-content') as HTMLElement;
+          this.addGrid(content, w.subGrid);
         }
       }
     });
+
     this.engine.removedNodes = removed;
     this.commit();
 

src/types.ts

@@ -59,9 +59,15 @@ export interface GridStackOptions {
   /** (internal) unit for cellHeight (default? 'px') which is set when a string cellHeight with a unit is passed (ex: '10rem') */
   cellHeightUnit?: string;
 
+  /** list of children item to create when calling load() or addGrid() */
+  children?: GridStackWidget[];
+
   /** number of columns (default?: 12). Note: IF you change this, CSS also have to change. See https://github.com/gridstack/gridstack.js#change-grid-columns */
   column?: number;
 
+  /** additional class on top of '.grid-stack' (which is required for our CSS) to differentiate this instance */
+  class?: string;
+
   /** disallows dragging of widgets (default?: false) */
   disableDrag?: boolean;
 
@@ -212,6 +218,8 @@ export interface GridStackWidget {
   id?: numberOrString;
   /** html to append inside as content */
   content?: string;
+  /** optional nested grid options and list of children */
+  subGrid?: GridStackOptions;
 }
 
 /** Drag&Drop resize options */