Merge pull request #1053 from adumesny/bugfix/810

grid options renamed to `columns` & `maxRows`

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), to addition to `width` 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,13 +225,15 @@ 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)):
+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 {
 
   $gridstack-columns: 12;
 
+  min-width: (100% / $gridstack-columns);
+
   @for $i from 1 through $gridstack-columns {
     &[data-gs-width='#{$i}'] { width: (100% / $gridstack-columns) * $i; }
     &[data-gs-x='#{$i}'] { left: (100% / $gridstack-columns) * $i; }
@@ -221,25 +243,6 @@ Here is a SASS code snippet which can make life easier (Thanks to @ascendantofra
 }
 ```
 
-Or you can include `gridstack-extra.css`. See below for more details.
-
-## Extra CSS
-
-There are few extra CSS batteries in `gridstack-extra.css` (`gridstack-extra.min.css`).
-
-### 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,6 +24,7 @@ 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)).

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,21 +94,20 @@ 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
 
-- `data-gs-x`, `data-gs-y` - element position. Note: if one is missing this will `autoPosition` the item
-- `data-gs-width`, `data-gs-height` - element size
-- `data-gs-id`- good for quick identification (for example in change event)
-- `data-gs-max-width`, `data-gs-min-width`, `data-gs-max-height`, `data-gs-min-height` - element constraints
+- `data-gs-x`, `data-gs-y` - (number) element position in row/column. Note: if one is missing this will `autoPosition` the item
+- `data-gs-width`, `data-gs-height` - (number) element size in row/column
+- `data-gs-id`- (number | string) good for quick identification (for example in change event)
+- `data-gs-max-width`, `data-gs-min-width`, `data-gs-max-height`, `data-gs-min-height` - element constraints in row/column
 - `data-gs-no-resize` - disable element resizing
 - `data-gs-no-move` - disable element moving
 - `data-gs-auto-position` - tells to ignore `data-gs-x` and `data-gs-y` attributes and to place element to the first available position. Having either one missing will also do that.