renamed setGridWidth() to setColumn()

Alain Dumesny · Alain Dumesny · commit 3449bde71bec · 2019-11-19T12:22:04.000-08:00
part of #1053 changes * kept old method as stub with warning (no code break) * added new (hidden for now) column.html demo * updated test coverage
diff --git a/demo/column.html b/demo/column.html
@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <!--[if lt IE 9]>
+  <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+  <![endif]-->
+
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Column grid demo</title>
+
+  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css">
+  <link rel="stylesheet" href="../dist/gridstack.css"/>
+
+  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.js"></script>
+  <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js"></script>
+  <script src="../src/gridstack.js"></script>
+  <script src="../src/gridstack.jQueryUI.js"></script>
+
+  <style type="text/css">
+    .grid-stack {
+      background: lightgoldenrodyellow;
+    }
+
+    .grid-stack-item-content {
+      color: #2c3e50;
+      text-align: center;
+      background-color: #18bc9c;
+    }
+  </style>
+</head>
+<body>
+  <div class="container-fluid">
+    <h1>setColumn() grid demo</h1>
+    <div>
+      <a class="btn btn-primary" id="1column" href="#">1 Column</a>
+    </div>
+    <br><br>
+    <div class="grid-stack"></div>
+  </div>
+
+
+  <script type="text/javascript">
+    $(function () {
+      $('.grid-stack').gridstack();
+      var self = this;
+      this.grid = $('.grid-stack').data('gridstack');
+
+      var items = [
+        {x: 0, y: 0, width: 4, height: 2},
+        {x: 4, y: 0, width: 4, height: 1},
+      ];
+      items.forEach(function (node, i) {
+        self.grid.addWidget($('<div><div class="grid-stack-item-content">' + i + '</div></div>'), node);
+      });
+
+      $('#1column').click(function() {
+        oneColumn();
+      });
+
+      function oneColumn() {
+        self.grid.setColumn(1);
+      }
+    });
+  </script>
+</body>
+</html>
diff --git a/demo/responsive.html b/demo/responsive.html
@@ -72,13 +72,13 @@ <h1>Responsive grid demo</h1>
         if (isBreakpoint('xs')) {
           $('#grid-size').text('One column mode');
         } else if (isBreakpoint('sm')) {
-          grid.setGridWidth(3);
+          grid.setColumn(3);
           $('#grid-size').text(3);
         } else if (isBreakpoint('md')) {
-          grid.setGridWidth(6);
+          grid.setColumn(6);
           $('#grid-size').text(6);
         } else if (isBreakpoint('lg')) {
-          grid.setGridWidth(12);
+          grid.setColumn(12);
           $('#grid-size').text(12);
         }
       };
diff --git a/doc/CHANGES.md b/doc/CHANGES.md
@@ -24,7 +24,7 @@ Change log
 
 ## v0.5.2-dev (upcoming changes)
 
-- grid options `width` is now `column`, and `height` is now `maxRow` which match what they are. Old names are still supported for now (with console warnings). Also various fixes for custom # of column and re-wrote entire doc section ([#1053](https://github.com/gridstack/gridstack.js/issues/1053)).
+- grid options `width` is now `column`, and `height` is now `maxRow`, and method `setGridWidth()` is now `setColumn()` which match what they are. Old names are still supported for now (with console warnings). Also various fixes for custom # of column and re-wrote entire doc section ([#1053](https://github.com/gridstack/gridstack.js/issues/1053)).
 - fix widgets not animating when animate: true is used. on every move, styles were recreated-fix should slightly improve gridstack.js speed ([#937](https://github.com/gridstack/gridstack.js/issues/937)).
 - fix moving widgets when having multiple grids. jquery-ui workaround ([#1043](https://github.com/gridstack/gridstack.js/issues/1043)).
 - switch to eslint ([#763](https://github.com/gridstack/gridstack.js/issues/763)).
diff --git a/doc/README.md b/doc/README.md
@@ -47,7 +47,7 @@ gridstack.js API
   - [resize(el, width, height)](#resizeel-width-height)
   - [resizable(el, val)](#resizableel-val)
   - [setAnimation(doAnimate)](#setanimationdoanimate)
-  - [setGridWidth(gridWidth, doNotPropagate)](#setgridwidthgridwidth-donotpropagate)
+  - [setColumn(column, doNotPropagate)](#setcolumncolumn-donotpropagate)
   - [setStatic(staticValue)](#setstaticstaticvalue)
   - [update(el, x, y, width, height)](#updateel-x-y-width-height)
   - [verticalMargin()](#verticalmargin)
@@ -436,11 +436,11 @@ Toggle the grid animation state.  Toggles the `grid-stack-animate` class.
 
 - `doAnimate` - if `true` the grid will animate.
 
-### setGridWidth(gridWidth, doNotPropagate)
+### setColumn(column, doNotPropagate)
 
 (Experimental) Modify number of columns in the grid. Will attempt to update existing widgets to conform to new number of columns. Requires `gridstack-extra.css` or `gridstack-extra.min.css`.
 
-- `gridWidth` - Integer between 1 and 12.
+- `column` - Integer between 1 and 12.
 - `doNotPropagate` - if true existing widgets will not be updated.
 
 ### setStatic(staticValue)
diff --git a/spec/gridstack-spec.js b/spec/gridstack-spec.js
@@ -3,7 +3,7 @@ describe('gridstack', function() {
 
   var e;
   var w;
-  // grid has 4x2 and 4x4 top-left aligned - used all most test cases
+  // grid has 4x2 and 4x4 top-left aligned - used on most test cases
   var gridstackHTML =
     '<div style="width: 992px; height: 800px" id="gs-cont">' +
     '  <div class="grid-stack">' +
@@ -271,6 +271,62 @@ describe('gridstack', function() {
     });
   });
 
+  describe('grid.column', function() {
+    beforeEach(function() {
+      document.body.insertAdjacentHTML('afterbegin', gridstackHTML);
+    });
+    afterEach(function() {
+      document.body.removeChild(document.getElementById('gs-cont'));
+    });
+    it('should have no changes', function() {
+      var options = {
+        column: 12
+      };
+      $('.grid-stack').gridstack(options);
+      var grid = $('.grid-stack').data('gridstack');
+      expect(grid.opts.column).toBe(12);
+      grid.setColumn(12);
+      expect(grid.opts.column).toBe(12);
+      grid.setGridWidth(12); // old API
+      expect(grid.opts.column).toBe(12);
+    });
+    it('should change column number, no relayout', function() {
+      var options = {
+        column: 12
+      };
+      $('.grid-stack').gridstack(options);
+      var grid = $('.grid-stack').data('gridstack');
+      var items = $('.grid-stack-item');
+      
+      grid.setColumn(10, false);
+      expect(grid.opts.column).toBe(10);
+      for (var j = 0; j < items.length; j++) {
+        expect(parseInt($(items[j]).attr('data-gs-y'), 10)).toBe(0);
+      }
+      
+      grid.setColumn(9, true);
+      expect(grid.opts.column).toBe(9);
+      for (var j = 0; j < items.length; j++) {
+        expect(parseInt($(items[j]).attr('data-gs-y'), 10)).toBe(0);
+      }
+    });
+    it('should change column number and relayout items', function() {
+      var options = {
+        column: 12
+      };
+      $('.grid-stack').gridstack(options);
+      var grid = $('.grid-stack').data('gridstack');
+      var items = $('.grid-stack-item');
+      
+      grid.setColumn(1);
+      expect(grid.opts.column).toBe(1);
+      for (var j = 0; j < items.length; j++) {
+        expect(parseInt($(items[j]).attr('data-gs-x'), 10)).toBe(0);
+        // TODO: check Y position but I don't currently agree with order. [Alain]
+      }
+    });
+  });
+
   describe('grid.minWidth', function() {
     beforeEach(function() {
       document.body.insertAdjacentHTML('afterbegin', gridstackHTML);
diff --git a/src/gridstack.d.ts b/src/gridstack.d.ts
@@ -264,10 +264,10 @@ interface GridStack {
   /**
    * (Experimental) Modify number of columns in the grid. Will attempt to update existing widgets
    * to conform to new number of columns. Requires `gridstack-extra.css` or `gridstack-extra.min.css`.
-   * @param gridWidth - Integer between 1 and 12.
+   * @param column - Integer between 1 and 12.
    * @param doNotPropagate if true existing widgets will not be updated.
    */
-  setGridWidth(gridWidth: number, doNotPropagate: boolean): void;
+  setColumn(column: number, doNotPropagate: boolean): void;
 
   /**
    * Toggle the grid static state. Also toggle the grid-stack-static class.
diff --git a/src/gridstack.js b/src/gridstack.js
@@ -250,11 +250,8 @@
 
   /*eslint-disable camelcase */
   Utils.is_intercepted = obsolete(Utils.isIntercepted, 'is_intercepted', 'isIntercepted');
-
   Utils.create_stylesheet = obsolete(Utils.createStylesheet, 'create_stylesheet', 'createStylesheet');
-
   Utils.remove_stylesheet = obsolete(Utils.removeStylesheet, 'remove_stylesheet', 'removeStylesheet');
-
   Utils.insert_css_rule = obsolete(Utils.insertCSSRule, 'insert_css_rule', 'insertCSSRule');
   /*eslint-enable camelcase */
 
@@ -697,7 +694,7 @@
     opts.itemClass = opts.itemClass || 'grid-stack-item';
     var isNested = this.container.closest('.' + opts.itemClass).length > 0;
 
-    this.opts = Utils.defaults(opts || {}, {
+    this.opts = Utils.defaults(opts, {
       column: parseInt(this.container.attr('data-gs-column')) || 12,
       maxRow: parseInt(this.container.attr('data-gs-max-row')) || 0,
       itemClass: 'grid-stack-item',
@@ -1229,7 +1226,7 @@
         var distance = ui.position.top - node._prevYPix;
         node._prevYPix = ui.position.top;
         Utils.updateScrollPosition(el[0], ui, distance);
-        if (el.data('inTrashZone') || x < 0 || x >= self.grid.width || y < 0 ||
+        if (el.data('inTrashZone') || x < 0 || x >= self.grid.column || y < 0 ||
           (!self.grid.float && y > self.grid.getGridHeight())) {
           if (!node._temporaryRemoved) {
             if (self.opts.removable === true) {
@@ -1807,15 +1804,21 @@
     this.grid.commit();
   };
 
-  GridStack.prototype.setGridWidth = function(gridWidth,doNotPropagate) {
+  GridStack.prototype.setColumn = function(column, doNotPropagate) {
+    if (this.opts.column === column) { return; }
     this.container.removeClass('grid-stack-' + this.opts.column);
     if (doNotPropagate !== true) {
-      this._updateNodeWidths(this.opts.column, gridWidth);
+      this._updateNodeWidths(this.opts.column, column);
     }
-    this.opts.column = gridWidth;
-    this.grid.width = gridWidth;
-    this.container.addClass('grid-stack-' + gridWidth);
+    this.opts.column = this.grid.column = column;
+    this.container.addClass('grid-stack-' + column);
   };
+  // legacy call from <= 0.5.2 - use new method instead.
+  GridStack.prototype.setGridWidth = function(column, doNotPropagate) {
+    console.warn('gridstack.js: setGridWidth() is deprecated as of v0.5.3 and has been replaced ' +
+      'with setColumn(). It will be **completely** removed in v1.0.');
+    this.setColumn(column, doNotPropagate);
+  }
 
   /*eslint-disable camelcase */
   GridStackEngine.prototype.batch_update = obsolete(GridStackEngine.prototype.batchUpdate);
