addWidget(el, options) with object param

* new addWidget(el, options) to pass object so you don't have to spell 10 params
* updated TS file, test case, some samples

Author: Alain Dumesny

demo/float.html

@@ -75,8 +75,7 @@ <h1>Float grid demo</h1>
                 width: 1 + 3 * Math.random(),
                 height: 1 + 3 * Math.random()
               };
-          this.grid.addWidget($('<div><div class="grid-stack-item-content"></div></div>'),
-            node.x, node.y, node.width, node.height);
+          this.grid.addWidget($('<div><div class="grid-stack-item-content"></div></div>'), node);
           return false;
         }.bind(this);
 

demo/responsive.html

@@ -107,8 +107,7 @@ <h1>Responsive grid demo</h1>
           this.grid.removeAll();
           var items = GridStackUI.Utils.sort(this.serializedData);
           items.forEach(function (node, i) {
-            this.grid.addWidget($('<div><div class="grid-stack-item-content">' + i + '</div></div>'),
-              node.x, node.y, node.width, node.height);
+            this.grid.addWidget($('<div><div class="grid-stack-item-content">' + i + '</div></div>'), node);
           }.bind(this));
           return false;
         }.bind(this);

demo/serialization.html

@@ -77,8 +77,7 @@ <h1>Serialization demo</h1>
                     this.grid.removeAll();
                     var items = GridStackUI.Utils.sort(this.serializedData);
                     items.forEach(function (node) {
-                        this.grid.addWidget($('<div><div class="grid-stack-item-content"></div></div>'),
-                            node.x, node.y, node.width, node.height);
+                        this.grid.addWidget($('<div><div class="grid-stack-item-content"></div></div>'), node);
                     }, this);
                     return false;
                 }.bind(this);

demo/two.html

@@ -129,8 +129,7 @@ <h1>Two grids demo</h1>
                 var grid = $(this).data('gridstack');
 
                 items.forEach(function (node) {
-                    grid.addWidget($('<div><div class="grid-stack-item-content"></div></div>'),
-                        node.x, node.y, node.width, node.height);
+                    grid.addWidget($('<div><div class="grid-stack-item-content"></div></div>'), node);
                 });
             });
 

doc/CHANGES.md

@@ -26,7 +26,8 @@ Change log
 - undefined x,y position messes up grid ([#1017](https://github.com/gridstack/gridstack.js/issues/1017)).
 - changed code to 2 spaces.
 - fix minHeight during `onStartMoving()` ([#999](https://github.com/gridstack/gridstack.js/issues/999)).
-- TypeScript definition file now included - no need to include @types/gridstack, easier to update.
+- TypeScript definition file now included - no need to include @types/gridstack, easier to update ([#1036](https://github.com/gridstack/gridstack.js/pull/1036)).
+- new addWidget(el, options) to pass object so you don't have to spell 10 params. ([#907](https://github.com/gridstack/gridstack.js/issues/907)).
 
 ## v0.5.1 (2019-11-07)
 

doc/README.md

@@ -20,7 +20,8 @@ gridstack.js API
   - [resizestart(event, ui)](#resizestartevent-ui)
   - [gsresizestop(event, ui)](#gsresizestopevent-ui)
 - [API](#api)
-  - [addWidget(el[, x, y, width, height, autoPosition, minWidth, maxWidth, minHeight, maxHeight, id])](#addwidgetel-x-y-width-height-autoposition-minwidth-maxwidth-minheight-maxheight-id)
+  - [addWidget(el, [options])](#addwidgetel-options)
+  - [addWidget(el, [x, y, width, height, autoPosition, minWidth, maxWidth, minHeight, maxHeight, id])](#addwidgetel-x-y-width-height-autoposition-minwidth-maxwidth-minheight-maxheight-id)
   - [batchUpdate()](#batchupdate)
   - [cellHeight()](#cellheight)
   - [cellHeight(val, noUpdate)](#cellheightval-noupdate)
@@ -217,7 +218,11 @@ $('.grid-stack').on('gsresizestop', function(event, elem) {
 
 ## API
 
-### addWidget(el[, x, y, width, height, autoPosition, minWidth, maxWidth, minHeight, maxHeight, id])
+### addWidget(el, [options])
+
+Creates new widget and returns it. Options is an object containing the fields x,y,width,height,etc... described below.
+
+### addWidget(el, [x, y, width, height, autoPosition, minWidth, maxWidth, minHeight, maxHeight, id])
 
 Creates new widget and returns it.
 
@@ -238,7 +243,6 @@ before calling `addWidget` for additional check.
 
 ```javascript
 $('.grid-stack').gridstack();
-
 var grid = $('.grid-stack').data('gridstack');
 grid.addWidget(el, 0, 0, 3, 2, true);
 ```

spec/e2e/html/gridstack-with-height.html

@@ -63,8 +63,7 @@ <h1>gridstack.js tests</h1>
         items.forEach(function(node) {
           var w = $('<div><div class="grid-stack-item-content"></div></div>');
           w.attr('id', 'item-' + (++id));
-          this.grid.addWidget(w,
-            node.x, node.y, node.width, node.height);
+          this.grid.addWidget(w, node);
         }, this);
       };
     });

spec/gridstack-spec.js

@@ -864,18 +864,10 @@ describe('gridstack', function() {
     afterEach(function() {
       document.body.removeChild(document.getElementById('gs-cont'));
     });
-    it('should allow same x, y coordinates for widgets.', function() {
-      var options = {
-        cellHeight: 80,
-        verticalMargin: 10,
-        float: true
-      };
-      $('.grid-stack').gridstack(options);
+    it('should keep all widget options the same (autoPosition off', function() {
+      $('.grid-stack').gridstack({float: true});
       var grid = $('.grid-stack').data('gridstack');
-      var widgetHTML =
-        '  <div class="grid-stack-item">' +
-        '    <div class="grid-stack-item-content"></div>' +
-        '  </div>';
+      var widgetHTML = '<div class="grid-stack-item"><div class="grid-stack-item-content"></div></div>';
       var widget = grid.addWidget(widgetHTML, 6, 7, 2, 3, false, 1, 4, 2, 5, 'coolWidget');
       var $widget = $(widget);
       expect(parseInt($widget.attr('data-gs-x'), 10)).toBe(6);
@@ -900,23 +892,43 @@ describe('gridstack', function() {
       document.body.removeChild(document.getElementById('gs-cont'));
     });
     it('should change x, y coordinates for widgets.', function() {
-      var options = {
-        cellHeight: 80,
-        verticalMargin: 10
-      };
-      $('.grid-stack').gridstack(options);
+      $('.grid-stack').gridstack({float: true});
       var grid = $('.grid-stack').data('gridstack');
-      var widgetHTML =
-        '  <div class="grid-stack-item">' +
-        '    <div class="grid-stack-item-content"></div>' +
-        '  </div>';
+      var widgetHTML = '<div class="grid-stack-item"><div class="grid-stack-item-content"></div></div>';
       var widget = grid.addWidget(widgetHTML, 9, 7, 2, 3, true);
       var $widget = $(widget);
-      expect(parseInt($widget.attr('data-gs-x'), 10)).not.toBe(6);
+      expect(parseInt($widget.attr('data-gs-x'), 10)).not.toBe(9);
       expect(parseInt($widget.attr('data-gs-y'), 10)).not.toBe(7);
     });
   });
 
+  describe('grid method addWidget with widget options', function() {
+    beforeEach(function() {
+      document.body.insertAdjacentHTML(
+        'afterbegin', gridstackHTML);
+    });
+    afterEach(function() {
+      document.body.removeChild(document.getElementById('gs-cont'));
+    });
+    it('should keep all widget options the same (autoPosition off', function() {
+      $('.grid-stack').gridstack();
+      var grid = $('.grid-stack').data('gridstack');
+      var widgetHTML = '<div class="grid-stack-item"><div class="grid-stack-item-content"></div></div>';
+      var widget = grid.addWidget(widgetHTML, {x: 8, height: 2, id: 'optionWidget'});
+      var $widget = $(widget);
+      expect(parseInt($widget.attr('data-gs-x'), 10)).toBe(8);
+      expect(parseInt($widget.attr('data-gs-width'), 10)).toBe(1);
+      expect(parseInt($widget.attr('data-gs-height'), 10)).toBe(2);
+      expect($widget.attr('data-gs-auto-position')).toBe(undefined);
+      expect($widget.attr('data-gs-min-width')).toBe(undefined);
+      expect($widget.attr('data-gs-max-width')).toBe(undefined);
+      expect($widget.attr('data-gs-min-height')).toBe(undefined);
+      expect($widget.attr('data-gs-max-height')).toBe(undefined);
+      expect($widget.attr('data-gs-id')).toBe('optionWidget');
+    });
+  });
+
+
   describe('grid.destroy', function() {
     beforeEach(function() {
       document.body.insertAdjacentHTML(

src/gridstack.d.ts

@@ -9,7 +9,7 @@
 // TypeScript Version: 2.3
 
 interface JQuery {
-    gridstack(options: IGridstackOptions): JQuery;
+    gridstack(options: GridstackOptions): JQuery;
     data(key: 'gridstack'): GridStack;
 }
 
@@ -27,7 +27,21 @@ interface GridStack {
     *
     * Widget will be always placed even if result height is more than actual grid height.
     * You need to use willItFit method before calling addWidget for additional check.
-    * See also makeWidget.
+    * See also `makeWidget()`.
+    *
+    * @example
+    * $('.grid-stack').gridstack();
+    * var grid = $('.grid-stack').data('gridstack');
+    * grid.addWidget(el, {width: 3, autoPosition: true});
+    *
+    * @param {GridStackElement} el widget to add
+    * @param {GridstackWidget} options widget position/size options (optional)
+    */
+    addWidget(el: GridStackElement, options?: GridstackWidget): JQuery;
+
+    /**
+    * Creates new widget and returns it. 
+    * Legacy: Spelled out version of the widgets options, recommend use new version instead.
     *
     * @example
     * $('.grid-stack').gridstack();
@@ -60,7 +74,7 @@ interface GridStack {
     cellHeight(): number;
 
     /**
-    * Update current cell height - see `IGridstackOptions.cellHeight` for format.
+    * Update current cell height - see `GridstackOptions.cellHeight` for format.
     * This method rebuilds an internal CSS style sheet.
     * Note: You can expect performance issues if call this method too often.
     *
@@ -277,7 +291,7 @@ interface GridStack {
     verticalMargin(): number;
 
     /**
-    * Updates the vertical margin - see `IGridstackOptions.verticalMargin` for format options.
+    * Updates the vertical margin - see `GridstackOptions.verticalMargin` for format options.
     *
     * @param {number | string} value new vertical margin value
     * @param {boolean} noUpdate (optional) if true, styles will not be updated
@@ -313,13 +327,39 @@ interface MousePosition {
 }
 
 /**
- *   Defines the position of a cell inside the grid
+ * Defines the position of a cell inside the grid
  */
 interface CellPosition {
     x: number;
     y: number;
 }
 
+/**
+ * Gridstack Widget creation options
+ */
+interface GridstackWidget {
+    /** x position (default?: 0) */
+    x?: number;
+    /** y position (default?: 0) */
+    y?: number;
+    /** width (default?: 1) */
+    width?: number;
+    /** height (default?: 1) */
+    height?: number;
+    /** autoPosition if true then x, y parameters will be ignored and widget will be places on the first available position (default?: false) */
+    autoPosition?: boolean;
+    /** minimum width allowed during resize/creation (default?: undefined = un-constrained) */
+    minWidth?: number;
+    /** maximum width allowed during resize/creation (default?: undefined = un-constrained) */
+    maxWidth?: number;
+    /** minimum height allowed during resize/creation (default?: undefined = un-constrained) */
+    minHeight?: number;
+    /** maximum height allowed during resize/creation (default?: undefined = un-constrained) */
+    maxHeight?: number;
+    /** id value for `data-gs-id` stored on the widget (default?: undefined)*/
+    id?: number | string;
+}
+
 declare namespace GridStackUI {
     interface Utils {
         /**
@@ -336,7 +376,7 @@ declare namespace GridStackUI {
  * Gridstack Options
  * Defines the options for a Gridstack
  */
-interface IGridstackOptions {
+interface GridstackOptions {
     /**
     * if true of jquery selector the grid will accept widgets dragged from other grids or from
     * outside (default: false) See [example](http://gridstack.github.io/gridstack.js/demo/two.html)
@@ -479,3 +519,4 @@ interface IGridstackOptions {
     */
     width?: number;
 }
+

src/gridstack.js

@@ -394,7 +394,7 @@
 
   GridStackEngine.prototype._prepareNode = function(node, resizing) {
     node = node || {};
-    // if we're missing position, have grid position us automatically (before we set them to 0,0)
+    // if we're missing position, have the grid position us automatically (before we set them to 0,0)
     if (node.x === undefined || node.y === undefined) {
       node.autoPosition = true;
     }
@@ -1435,8 +1435,13 @@
     }
   };
 
-  GridStack.prototype.addWidget = function(el, x, y, width, height, autoPosition, minWidth, maxWidth,
-    minHeight, maxHeight, id) {
+  GridStack.prototype.addWidget = function(el, x, y, width, height, autoPosition, minWidth, maxWidth, minHeight, maxHeight, id) {
+
+    // instead of passing all the params, the user might pass an object with all fields instead, if so extract them and call us back
+    if (typeof x === 'object') {
+      return this.addWidget(el, x.x, x.y, x.width, x.height, x.autoPosition, x.minWidth, x.maxWidth, x.minHeight, x.maxHeight, x.id);
+    }
+
     el = $(el);
     if (typeof x != 'undefined') { el.attr('data-gs-x', x); }
     if (typeof y != 'undefined') { el.attr('data-gs-y', y); }