better save() doc

adumesny · adumesny · commit 2299ca5c9375 · 2021-07-11T07:26:13.000-07:00
* fixed documentation for save() fix gridstack#1795
diff --git a/demo/nested.html b/demo/nested.html
@@ -65,7 +65,7 @@ <h1>Nested grids demo</h1>
         y: Math.round(5 * Math.random()),
         w: Math.round(1 + 1 * Math.random()),
         h: Math.round(1 + 1 * Math.random()),
-        content: count++
+        content: String(count++)
       };
       subGrid.addWidget(node);
       return false;
diff --git a/doc/CHANGES.md b/doc/CHANGES.md
@@ -63,6 +63,7 @@ Change log
 
 * fix [#1784](https://github.com/gridstack/gridstack.js/issues/1784) `removable:true` working by itself (without needing `acceptWidgets:true`)
 * fix [#1791](https://github.com/gridstack/gridstack.js/pull/1791) removed drag flicker and scroll issue. Thanks [@nelsieborja](https://github.com/nelsieborja)
+* better doc for save [#1795](https://github.com/gridstack/gridstack.js/issues/1795)
 
 ## 4.2.5 (2021-5-31)
 
diff --git a/doc/README.md b/doc/README.md
@@ -53,7 +53,7 @@ gridstack.js API
   - [`removeWidget(el, removeDOM = true, triggerEvent = true)`](#removewidgetel-removedom--true-triggerevent--true)
   - [`removeAll(removeDOM = true)`](#removeallremovedom--true)
   - [`resizable(el, val)`](#resizableel-val)
-  - [`save(saveContent = true): GridStackWidget[]`](#savesavecontent--true-gridstackwidget)
+  - [`save(saveContent = true, saveGridOpt = false): GridStackWidget[] | GridStackOptions`](#savesavecontent--true-savegridopt--false-gridstackwidget--gridstackoptions)
   - [`setAnimation(doAnimate)`](#setanimationdoanimate)
   - [`setStatic(staticValue)`](#setstaticstaticvalue)
   - [`update(el: GridStackElement, opts: GridStackWidget)`](#updateel-gridstackelement-opts-gridstackwidget)
@@ -522,10 +522,13 @@ Enables/Disables user resizing of specific grid element. If you want all items,
 - `el` - widget to modify
 - `val` - if `true` widget will be resizable.
 
-### `save(saveContent = true): GridStackWidget[]`
+### `save(saveContent = true, saveGridOpt = false): GridStackWidget[] | GridStackOptions`
 
-- returns the layout of the grid (and optionally the html content as well) 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)
+saves the current layout returning a list of widgets for serialization which might include any nested grids.
+- `saveContent` if true (default) the latest html inside `.grid-stack-content` will be saved to `GridStackWidget.content` field, else it will be left unchanged for initial load values.
+- `saveGridOpt` if true (default `false`), save the grid options itself, so you can call the new `GridStack.addGrid()` to recreate everything from scratch. GridStackOptions.children would then contain the widget list instead.
+- returns list of widgets or full grid option, including .children list of widgets
+- see [serialization](http://gridstackjs.com/demo/serialization.html) and [nested](http://gridstackjs.com/demo/nested.html)
 
 ### `setAnimation(doAnimate)`
 
diff --git a/src/gridstack-engine.ts b/src/gridstack-engine.ts
@@ -664,24 +664,24 @@ export class GridStackEngine {
     return this;
   }
 
-  /** saves the current layout returning a list of widgets for serialization */
+  /** saves a copy of the current layout returning a list of widgets for serialization */
   public save(saveElement = true): GridStackNode[] {
-    let widgets: GridStackNode[] = [];
+    let list: GridStackNode[] = [];
     this._sortNodes();
     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
-      if (!saveElement) delete w.el;
       delete w.grid;
+      if (!saveElement) delete w.el;
       // 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);
+      list.push(w);
     });
-    return widgets;
+    return list;
   }
 
   /** @internal called whenever a node is added or moved - updates the cached layouts */
diff --git a/src/gridstack.ts b/src/gridstack.ts
@@ -440,9 +440,13 @@ export class GridStack {
   }
 
   /**
-   * saves the current layout returning a list of widgets for serialization (with default to save content), which might include any nested grids.
-   * Optionally you can also save the grid with options itself, so you can call the new GridStack.addGrid()
-   * to recreate everything from scratch. GridStackOptions.children would then contain the widget list.
+  /**
+   * saves the current layout returning a list of widgets for serialization which might include any nested grids.
+   * @param saveContent if true (default) the latest html inside .grid-stack-content will be saved to GridStackWidget.content field, else it will
+   * be left unchanged for initial load values.
+   * @param saveGridOpt if true (default false), save the grid options itself, so you can call the new GridStack.addGrid()
+   * to recreate everything from scratch. GridStackOptions.children would then contain the widget list instead.
+   * @returns list of widgets or full grid option, including .children list of widgets
    */
   public save(saveContent = true, saveGridOpt = false): GridStackWidget[] | GridStackOptions {
     // return copied nodes we can modify at will...
