options rename to columns & maxRows

* grid options `width` is now `columns`, and `height` is now `maxRows` which match what they are.
* Old names are still supported for now (with console warnings)
* updated test (required), samples (optional), readme
* re-wrote entire custom column section. Hopefully much easier to find/use now.

Author: Alain Dumesny

README.md

@@ -26,9 +26,8 @@ Join gridstack.js on Slack: https://gridstackjs.troolee.com
   - [API Documentation](#api-documentation)
   - [Touch devices support](#touch-devices-support)
   - [gridstack.js for specific frameworks](#gridstackjs-for-specific-frameworks)
-  - [Change grid width](#change-grid-width)
-  - [Extra CSS](#extra-css)
-    - [Different grid widths](#different-grid-widths)
+  - [Change grid columns](#change-grid-columns)
+  - [Custom columns CSS](#custom-columns-css)
   - [Override resizable/draggable options](#override-resizabledraggable-options)
   - [IE8 support](#ie8-support)
 - [Changes](#changes)
@@ -174,10 +173,31 @@ If you're still experiencing issues on touch devices please check [#444](https:/
 - ember: [gridstack-ember](https://github.com/yahoo/ember-gridstack)
 
 
-## Change grid width
+## Change grid columns
 
-To change grid width (columns count), in addition to setting the `width` grid option CSS rules
-for `.grid-stack-item[data-gs-width="X"]` and  `.grid-stack-item[data-gs-x="X"]` have to be changed accordingly.
+GridStack makes it very easy if you need [1-12] columns out of the box (default is 12), but you always need **2 things** if you need to customize this:
+
+1) Change the `columns` grid option when creating a grid to your number N
+```js
+$('.grid-stack').gridstack( {columns: N} );
+```
+
+2) and change your HTML accordingly if **N < 12** (else custom CSS section next). Without this, things will not render/work correctly.
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/gridstack-extra.css"/>
+
+<div class="grid-stack grid-stack-N">...</div>
+```
+
+Note `grid-stack-N` class was added.
+
+`gridstack-extra.css` (and `gridstack-extra.min.css`) defines CSS for grids with custom [1-12] columns. Anything more and you'll need to generate the SASS/CSS yourself (see next).
+
+See example: [2 grids demo](http://gridstack.github.io/gridstack.js/demo/two.html) with 6 columns
+
+## Custom columns CSS
+
+If you need > 12 columns or want to generate the CSS manually (else see above) you will need to generate CSS rules for `.grid-stack-item[data-gs-width="X"]` and `.grid-stack-item[data-gs-x="X"]`.
 
 For instance for 3-column grid you need to rewrite CSS to be:
 
@@ -205,7 +225,7 @@ For 4-column grid it should be:
 
 and so on.
 
-Here is a SASS code snippet which can make life easier (Thanks to @ascendantofrain, [#81](https://github.com/gridstack/gridstack.js/issues/81) and @StefanM98, [#868](https://github.com/gridstack/gridstack.js/issues/868)) and use a site like [sassmeister.com](https://www.sassmeister.com/) to generate CSS if you need to:
+Better yet, here is a SASS code snippet which can make life much easier (Thanks to @ascendantofrain, [#81](https://github.com/gridstack/gridstack.js/issues/81) and @StefanM98, [#868](https://github.com/gridstack/gridstack.js/issues/868)) and you can use sites like [sassmeister.com](https://www.sassmeister.com/) to generate the CSS for you instead:
 
 ```sass
 .grid-stack > .grid-stack-item {
@@ -223,25 +243,6 @@ Here is a SASS code snippet which can make life easier (Thanks to @ascendantofra
 }
 ```
 
-Or you can include `gridstack-extra.css` which include [1-12] column sizes. See below for more details.
-
-## Extra CSS
-
-There are few extra CSS batteries in `gridstack-extra.css` (`gridstack-extra.min.css`) that defines CSS for grids with [1-12] columns. Anything more and you'll need to generate the above SASS/CSS yourself.
-
-### Different grid widths
-
-You can use other than 12 grid width:
-
-```html
-<div class="grid-stack grid-stack-N">...</div>
-```
-```javascript
-$('.grid-stack').gridstack({width: N});
-```
-
-See example: [2 grids demo](http://gridstack.github.io/gridstack.js/demo/two.html)
-
 ## Override resizable/draggable options
 
 You can override default `resizable`/`draggable` options. For instance to enable other then bottom right resizing handle

demo/two.html

@@ -106,7 +106,7 @@ <h1>Two grids demo</h1>
   <script type="text/javascript">
     $(function () {
       var options = {
-        width: 6,
+        columns: 6,
         float: false,
         removable: '.trash',
         removeTimeout: 100,

doc/CHANGES.md

@@ -24,11 +24,11 @@ Change log
 
 ## v0.5.2-dev (upcoming changes)
 
+- grid options `width` is now `columns`, and `height` is now `maxRows` which match what they are. Old names are still supported for now (with console warnings). Also various fixes for custom # of columns 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)).
 - null values to addWidget() exception fix ([#1042](https://github.com/gridstack/gridstack.js/issues/1042)).
-- various fixes for custom # of columns (readme, safer code) ([#1053](https://github.com/gridstack/gridstack.js/issues/1053)).
 
 ## v0.5.2 (2019-11-13)
 

doc/README.md

@@ -77,7 +77,8 @@ gridstack.js API
 - `draggable` - allows to override jQuery UI draggable options. (default: `{handle: '.grid-stack-item-content', scroll: false, appendTo: 'body'}`)
 - `handle` - draggable handle selector (default: `'.grid-stack-item-content'`)
 - `handleClass` - draggable handle class (e.g. `'grid-stack-item-content'`). If set `handle` is ignored (default: `null`)
-- `height` - maximum rows amount. Default is `0` which means no maximum rows
+- `columns` - amount of columns (default: `12`)
+- `maxRows` - maximum rows amount. Default is `0` which means no maximum rows
 - `float` - enable floating widgets (default: `false`) See [example](http://gridstackjs.com/demo/float.html)
 - `itemClass` - widget class (default: `'grid-stack-item'`)
 - `minWidth` - minimal width. If window width is less than or equal to, grid will be shown in one-column mode (default: `768`)
@@ -93,13 +94,12 @@ gridstack.js API
 - `verticalMargin` - vertical gap size (default: `20`). Can be:
   * an integer (px)
   * a string (ex: '2em', '20px', '2rem')
-- `width` - amount of columns (default: `12`)
 
 ## Grid attributes
 
 - `data-gs-animate` - turns animation on
-- `data-gs-width` - amount of columns. Setting non-default value must be supported by equivalent change in CSS, [see docs here](https://github.com/gridstack/gridstack.js#change-grid-width).
-- `data-gs-height` - maximum rows amount. Default is `0` which means no maximum rows.
+- `data-gs-columns` - amount of columns. Setting non-default value must be supported by equivalent change in CSS, [see docs here](https://github.com/gridstack/gridstack.js#change-grid-columns).
+- `data-gs-maxRows` - maximum rows amount. Default is `0` which means no maximum rows.
 - `data-gs-current-height` - current rows amount. Set by the library only. Can be used by the CSS rules.
 
 ## Item attributes

spec/e2e/html/810-many-columns.html

@@ -49,7 +49,7 @@ <h1>Many Columns demo</h1>
       const COLUMNS = 30; // # of columns, also need to update CSS
       var count = 0;
       var options = {
-        width: COLUMNS,
+        columns: COLUMNS,
         cellHeight: 'auto',
         float: false
       };

spec/gridstack-engine-spec.js

@@ -17,9 +17,9 @@ describe('gridstack engine', function() {
     });
 
     it('should be setup properly', function() {
-      expect(engine.width).toEqual(12);
+      expect(engine.columns).toEqual(12);
       expect(engine.float).toEqual(false);
-      expect(engine.height).toEqual(0);
+      expect(engine.maxRows).toEqual(0);
       expect(engine.nodes).toEqual([]);
     });
   });

spec/gridstack-spec.js

@@ -7,14 +7,10 @@ describe('gridstack', function() {
   var gridstackHTML =
     '<div style="width: 992px; height: 800px" id="gs-cont">' +
     '  <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">' +
+    '    <div class="grid-stack-item" data-gs-x="0" data-gs-y="0" data-gs-width="4" data-gs-height="2">' +
     '      <div class="grid-stack-item-content"></div>' +
     '    </div>' +
-    '    <div class="grid-stack-item"' +
-    '      data-gs-x="4" data-gs-y="0"' +
-    '      data-gs-width="4" data-gs-height="4">' +
+    '    <div class="grid-stack-item" data-gs-x="4" data-gs-y="0" data-gs-width="4" data-gs-height="4">' +
     '      <div class="grid-stack-item-content"></div>' +
     '    </div>' +
     '  </div>' +
@@ -35,9 +31,9 @@ describe('gridstack', function() {
 
     it('should set default params correctly.', function() {
       e.call(w);
-      expect(w.width).toBeUndefined();
+      expect(w.columns).toBeUndefined();
       expect(w.float).toBe(false);
-      expect(w.height).toEqual(0);
+      expect(w.maxRows).toEqual(0);
       expect(w.nodes).toEqual([]);
       expect(typeof w.onchange).toBe('function');
       expect(w._updateCounter).toEqual(0);
@@ -49,9 +45,9 @@ describe('gridstack', function() {
       var arr = [1,2,3];
 
       e.call(w, 1, fkt, true, 2, arr);
-      expect(w.width).toEqual(1);
+      expect(w.columns).toEqual(1);
       expect(w.float).toBe(true);
-      expect(w.height).toEqual(2);
+      expect(w.maxRows).toEqual(2);
       expect(w.nodes).toEqual(arr);
       expect(w.onchange).toEqual(fkt);
       expect(w._updateCounter).toEqual(0);
@@ -75,27 +71,27 @@ describe('gridstack', function() {
 
   describe('sorting of nodes', function() {
 
-    it('should sort ascending with width.', function() {
+    it('should sort ascending with columns.', function() {
       w.nodes = [{x: 7, y: 0}, {x: 4, y: 4}, {x: 9, y: 0}, {x: 0, y: 1}];
       e.prototype._sortNodes.call(w, 1);
       expect(w.nodes).toEqual([{x: 0, y: 1}, {x: 7, y: 0}, {x: 4, y: 4}, {x: 9, y: 0}]);
     });
 
-    it('should sort descending with width.', function() {
+    it('should sort descending with columns.', function() {
       w.nodes = [{x: 7, y: 0}, {x: 4, y: 4}, {x: 9, y: 0}, {x: 0, y: 1}];
       e.prototype._sortNodes.call(w, -1);
       expect(w.nodes).toEqual([{x: 9, y: 0}, {x: 4, y: 4}, {x: 7, y: 0}, {x: 0, y: 1}]);
     });
 
-    it('should sort ascending without width.', function() {
-      w.width = false;
+    it('should sort ascending without columns.', function() {
+      w.columns = undefined;
       w.nodes = [{x: 7, y: 0, width: 1}, {x: 4, y: 4, width: 1}, {x: 9, y: 0, width: 1}, {x: 0, y: 1, width: 1}];
       e.prototype._sortNodes.call(w, 1);
       expect(w.nodes).toEqual([{x: 7, y: 0, width: 1}, {x: 9, y: 0, width: 1}, {x: 0, y: 1, width: 1}, {x: 4, y: 4, width: 1}]);
     });
 
-    it('should sort descending without width.', function() {
-      w.width = false;
+    it('should sort descending without columns.', function() {
+      w.columns = undefined;
       w.nodes = [{x: 7, y: 0, width: 1}, {x: 4, y: 4, width: 1}, {x: 9, y: 0, width: 1}, {x: 0, y: 1, width: 1}];
       e.prototype._sortNodes.call(w, -1);
       expect(w.nodes).toEqual([{x: 4, y: 4, width: 1}, {x: 0, y: 1, width: 1}, {x: 9, y: 0, width: 1}, {x: 7, y: 0, width: 1}]);
@@ -224,7 +220,7 @@ describe('gridstack', function() {
       var options = {
         cellHeight: 80,
         verticalMargin: 10,
-        width: 12
+        columns: 12
       };
       $('.grid-stack').gridstack(options);
       var grid = $('.grid-stack').data('gridstack');
@@ -235,7 +231,7 @@ describe('gridstack', function() {
       var options = {
         cellHeight: 80,
         verticalMargin: 10,
-        width: 10
+        columns: 10
       };
       $('.grid-stack').gridstack(options);
       var grid = $('.grid-stack').data('gridstack');
@@ -255,7 +251,7 @@ describe('gridstack', function() {
       var options = {
         cellHeight: 80,
         verticalMargin: 10,
-        width: 12
+        columns: 12
       };
       $('.grid-stack').gridstack(options);
       var grid = $('.grid-stack').data('gridstack');
@@ -266,7 +262,7 @@ describe('gridstack', function() {
       var options = {
         cellHeight: 80,
         verticalMargin: 10,
-        width: 10
+        columns: 10
       };
       $('.grid-stack').gridstack(options);
       var grid = $('.grid-stack').data('gridstack');

src/gridstack.d.ts

@@ -436,10 +436,15 @@ interface GridstackOptions {
     /** draggable handle class (e.g. 'grid-stack-item-content'). If set 'handle' is ignored (default?: null) */
     handleClass?: string;
 
+    /**
+    * 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
+    */
+    columns?: number;
+
     /**
     * maximum rows amount. Default? is 0 which means no maximum rows
     */
-    height?: number;
+    maxRows?: number;
 
     /**
     * enable floating widgets (default?: false) See example (http://gridstack.github.io/gridstack.js/demo/float.html)
@@ -513,10 +518,5 @@ interface GridstackOptions {
     * (internal?) unit for verticalMargin (default? 'px')
     */
     verticalMarginUnit?: string;
-
-    /**
-    * number of columns (default?: 12)
-    */
-    width?: number;
 }