move API doc from readme
This commit is contained in:
Pavel Reznikov
parent
7c586417fb
commit
100860d262
11
Gruntfile.js
11
Gruntfile.js
|
|
@ -55,8 +55,15 @@ module.exports = function(grunt) {
|
|||
removeAd: false
|
||||
},
|
||||
readme: {
|
||||
target: './README.md'
|
||||
}
|
||||
options: {
|
||||
target: './README.md'
|
||||
}
|
||||
},
|
||||
doc: {
|
||||
options: {
|
||||
target: './doc/README.md'
|
||||
}
|
||||
},
|
||||
},
|
||||
|
||||
jshint: {
|
||||
|
|
|
|||
397
README.md
397
README.md
|
|
@ -20,48 +20,7 @@ Join gridstack.js on Slack: https://gridstackjs.troolee.com
|
|||
- [Install](#install)
|
||||
- [Basic usage](#basic-usage)
|
||||
- [Migrating to v0.2.5](#migrating-to-v025)
|
||||
- [Options](#options)
|
||||
- [Grid attributes](#grid-attributes)
|
||||
- [Item attributes](#item-attributes)
|
||||
- [Events](#events)
|
||||
- [onchange(items)](#onchangeitems)
|
||||
- [ondragstart(event, ui)](#ondragstartevent-ui)
|
||||
- [ondragstop(event, ui)](#ondragstopevent-ui)
|
||||
- [onresizestart(event, ui)](#onresizestartevent-ui)
|
||||
- [onresizestop(event, ui)](#onresizestopevent-ui)
|
||||
- [disable(event)](#disableevent)
|
||||
- [enable(event)](#enableevent)
|
||||
- [API](#api)
|
||||
- [addWidget(el, x, y, width, height, autoPosition)](#addwidgetel-x-y-width-height-autoposition)
|
||||
- [batchUpdate()](#batchupdate)
|
||||
- [cellHeight()](#cellheight)
|
||||
- [cellHeight(val)](#cellheightval)
|
||||
- [cellWidth()](#cellwidth)
|
||||
- [commit()](#commit)
|
||||
- [destroy()](#destroy)
|
||||
- [disable()](#disable)
|
||||
- [enable()](#enable)
|
||||
- [enableMove(doEnable, includeNewWidgets)](#enablemovedoenable-includenewwidgets)
|
||||
- [enableResize(doEnable, includeNewWidgets)](#enableresizedoenable-includenewwidgets)
|
||||
- [getCellFromPixel(position)](#getcellfrompixelposition)
|
||||
- [isAreaEmpty(x, y, width, height)](#isareaemptyx-y-width-height)
|
||||
- [locked(el, val)](#lockedel-val)
|
||||
- [makeWidget(el)](#makewidgetel)
|
||||
- [maxHeight(el, val)](#maxheightel-val)
|
||||
- [minHeight(el, val)](#minheightel-val)
|
||||
- [maxWidth(el, val)](#maxwidthel-val)
|
||||
- [minWidth(el, val)](#minwidthel-val)
|
||||
- [movable(el, val)](#movableel-val)
|
||||
- [move(el, x, y)](#moveel-x-y)
|
||||
- [removeWidget(el, detachNode)](#removewidgetel-detachnode)
|
||||
- [removeAll()](#removeall)
|
||||
- [resize(el, width, height)](#resizeel-width-height)
|
||||
- [resizable(el, val)](#resizableel-val)
|
||||
- [setStatic(staticValue)](#setstaticstaticvalue)
|
||||
- [update(el, x, y, width, height)](#updateel-x-y-width-height)
|
||||
- [willItFit(x, y, width, height, autoPosition)](#willitfitx-y-width-height-autoposition)
|
||||
- [Utils](#utils)
|
||||
- [GridStackUI.Utils.sort(nodes[, dir[, width]])](#gridstackuiutilssortnodes-dir-width)
|
||||
- [API Documentation](#api-documentation)
|
||||
- [Touch devices support](#touch-devices-support)
|
||||
- [Use with knockout.js](#use-with-knockoutjs)
|
||||
- [Use with angular.js](#use-with-angularjs)
|
||||
|
|
@ -161,359 +120,9 @@ As of v0.2.5 all methods and parameters are in camel case to respect [JavaScript
|
|||
All old methods and parameters are marked as deprecated and still available but a warning will be displayed in js console. They will be available until v1.0
|
||||
when they will be completely removed.
|
||||
|
||||
## Options
|
||||
## API Documentation
|
||||
|
||||
- `alwaysShowResizeHandle` - if `true` the resizing handles are shown even if the user is not hovering over the widget
|
||||
(default: `false`)
|
||||
- `animate` - turns animation on (default: `false`)
|
||||
- `auto` - if `false` gridstack will not initialize existing items (default: `true`)
|
||||
- `cellHeight` - one cell height (default: `60`). Can be:
|
||||
- an integer (px)
|
||||
- a string (ex: '10em', '100px', '10rem')
|
||||
- 0 or null, in which case the library will not generate styles for rows. Everything will have to be defined in CSS files.
|
||||
- `disableDrag` - disallows dragging of widgets (default: `false`).
|
||||
- `disableResize` - disallows resizing of widgets (default: `false`).
|
||||
- `draggable` - allows to override jQuery UI draggable options. (default: `{handle: '.grid-stack-item-content', scroll: true, 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
|
||||
- `float` - enable floating widgets (default: `false`) See [example](http://troolee.github.io/gridstack.js/demo/float.html)
|
||||
- `itemClass` - widget class (default: `'grid-stack-item'`)
|
||||
- `minWidth` - minimal width. If window width is less, grid will be shown in one-column mode. You need also update your css file (`@media (max-width: 768px) {...}`) with corresponding value (default: `768`)
|
||||
- `placeholderClass` - class for placeholder (default: `'grid-stack-placeholder'`)
|
||||
- `placeholderText` - placeholder default content (default: `''`)
|
||||
- `resizable` - allows to override jQuery UI resizable options. (default: `{autoHide: true, handles: 'se'}`)
|
||||
- `staticGrid` - makes grid static (default `false`). If true widgets are not movable/resizable. You don't even need jQueryUI draggable/resizable. A CSS class `grid-stack-static` is also added to the container.
|
||||
- `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
|
||||
- `data-gs-height` - 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
|
||||
- `data-gs-width`, `data-gs-height` - element size
|
||||
- `data-gs-max-width`, `data-gs-min-width`, `data-gs-max-height`, `data-gs-min-height` - element constraints
|
||||
- `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
|
||||
- `data-gs-locked` - the widget will be locked. It means another widget wouldn't be able to move it during dragging or resizing.
|
||||
The widget can still be dragged or resized. You need to add `data-gs-no-resize` and `data-gs-no-move` attributes
|
||||
to completely lock the widget.
|
||||
|
||||
## Events
|
||||
|
||||
### onchange(items)
|
||||
|
||||
Occurs when adding/removing widgets or existing widgets change their position/size
|
||||
|
||||
```javascript
|
||||
var serializeWidgetMap = function (items) {
|
||||
console.log(items);
|
||||
};
|
||||
|
||||
$('.grid-stack').on('change', function (e, items) {
|
||||
serializeWidgetMap(items);
|
||||
});
|
||||
```
|
||||
|
||||
### ondragstart(event, ui)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('dragstart', function (event, ui) {
|
||||
var grid = this;
|
||||
var element = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### ondragstop(event, ui)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('dragstop', function (event, ui) {
|
||||
var grid = this;
|
||||
var element = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### onresizestart(event, ui)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('resizestart', function (event, ui) {
|
||||
var grid = this;
|
||||
var element = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### onresizestop(event, ui)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('resizestop', function (event, ui) {
|
||||
var grid = this;
|
||||
var element = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### disable(event)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('disable', function(event) {
|
||||
var grid = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### enable(event)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('enable', function(event) {
|
||||
var grid = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### addWidget(el, x, y, width, height, autoPosition)
|
||||
|
||||
Creates new widget and returns it.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to add
|
||||
- `x`, `y`, `width`, `height` - widget position/dimensions (Optional)
|
||||
- `autoPosition` - if `true` then `x`, `y` parameters will be ignored and widget will be places on the first available
|
||||
position
|
||||
|
||||
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.
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').gridstack();
|
||||
|
||||
var grid = $('.grid-stack').data('gridstack');
|
||||
grid.addWidget(el, 0, 0, 3, 2, true);
|
||||
```
|
||||
|
||||
### batchUpdate()
|
||||
|
||||
Initailizes batch updates. You will see no changes until `commit` method is called.
|
||||
|
||||
### cellHeight()
|
||||
|
||||
Gets current cell height.
|
||||
|
||||
### cellHeight(val)
|
||||
|
||||
Update current cell height. This method rebuilds an internal CSS stylesheet. Note: You can expect performance issues if
|
||||
call this method too often.
|
||||
|
||||
```javascript
|
||||
grid.cellHeight(grid.cellWidth() * 1.2);
|
||||
```
|
||||
|
||||
### cellWidth()
|
||||
|
||||
Gets current cell width.
|
||||
|
||||
### commit()
|
||||
|
||||
Finishes batch updates. Updates DOM nodes. You must call it after `batchUpdate`.
|
||||
|
||||
### destroy()
|
||||
|
||||
Destroys a grid instance.
|
||||
|
||||
### disable()
|
||||
|
||||
Disables widgets moving/resizing. This is a shortcut for:
|
||||
|
||||
```javascript
|
||||
grid.movable('.grid-stack-item', false);
|
||||
grid.resizable('.grid-stack-item', false);
|
||||
```
|
||||
|
||||
### enable()
|
||||
|
||||
Enables widgets moving/resizing. This is a shortcut for:
|
||||
|
||||
```javascript
|
||||
grid.movable('.grid-stack-item', true);
|
||||
grid.resizable('.grid-stack-item', true);
|
||||
```
|
||||
|
||||
### enableMove(doEnable, includeNewWidgets)
|
||||
|
||||
Enables/disables widget moving. `includeNewWidgets` will force new widgets to be draggable as per `doEnable`'s value by changing the `disableDrag` grid option. This is a shortcut for:
|
||||
|
||||
```javascript
|
||||
grid.movable(this.container.children('.' + this.opts.itemClass), doEnable);
|
||||
```
|
||||
|
||||
### enableResize(doEnable, includeNewWidgets)
|
||||
|
||||
Enables/disables widget resizing. `includeNewWidgets` will force new widgets to be resizable as per `doEnable`'s value by changing the `disableResize` grid option. This is a shortcut for:
|
||||
|
||||
```javascript
|
||||
grid.resizable(this.container.children('.' + this.opts.itemClass), doEnable);
|
||||
```
|
||||
|
||||
### getCellFromPixel(position)
|
||||
|
||||
Get the position of the cell under a pixel on screen.
|
||||
|
||||
Parameters :
|
||||
|
||||
- `position` - the position of the pixel to resolve in absolute coordinates, as an object with `top` and `left`properties
|
||||
|
||||
Returns an object with properties `x` and `y` i.e. the column and row in the grid.
|
||||
|
||||
### isAreaEmpty(x, y, width, height)
|
||||
|
||||
Checks if specified area is empty.
|
||||
|
||||
### locked(el, val)
|
||||
|
||||
Locks/unlocks widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - if `true` widget will be locked.
|
||||
|
||||
### makeWidget(el)
|
||||
|
||||
If you add elements to your gridstack container by hand, you have to tell gridstack afterwards to make them widgets. If you want gridstack to add the elements for you, use `addWidget` instead.
|
||||
Makes the given element a widget and returns it.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - element to convert to a widget
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').gridstack();
|
||||
|
||||
$('.grid-stack').append('<div id="gsi-1" data-gs-x="0" data-gs-y="0" data-gs-width="3" data-gs-height="2" data-gs-auto-position="1"></div>')
|
||||
var grid = $('.grid-stack').data('gridstack');
|
||||
grid.makeWidget('gsi-1');
|
||||
```
|
||||
|
||||
### maxHeight(el, val)
|
||||
|
||||
Set the `maxHeight` for a widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - A numeric value of the number of rows
|
||||
|
||||
### minHeight(el, val)
|
||||
|
||||
Set the `minHeight` for a widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - A numeric value of the number of rows
|
||||
|
||||
### maxWidth(el, val)
|
||||
|
||||
Set the `maxWidth` for a widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - A numeric value of the number of columns
|
||||
|
||||
### minWidth(el, val)
|
||||
|
||||
Set the `minWidth` for a widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - A numeric value of the number of columns
|
||||
|
||||
### movable(el, val)
|
||||
|
||||
Enables/Disables moving.
|
||||
|
||||
- `el` - widget to modify
|
||||
- `val` - if `true` widget will be draggable.
|
||||
|
||||
### move(el, x, y)
|
||||
|
||||
Changes widget position
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to move
|
||||
- `x`, `y` - new position. If value is `null` or `undefined` it will be ignored.
|
||||
|
||||
### removeWidget(el, detachNode)
|
||||
|
||||
Removes widget from the grid.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to remove.
|
||||
- `detachNode` - if `false` DOM node won't be removed from the tree (Optional. Default `true`).
|
||||
|
||||
### removeAll()
|
||||
|
||||
Removes all widgets from the grid.
|
||||
|
||||
### resize(el, width, height)
|
||||
|
||||
Changes widget size
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to resize
|
||||
- `width`, `height` - new dimensions. If value is `null` or `undefined` it will be ignored.
|
||||
|
||||
### resizable(el, val)
|
||||
|
||||
Enables/Disables resizing.
|
||||
|
||||
- `el` - widget to modify
|
||||
- `val` - if `true` widget will be resizable.
|
||||
|
||||
### setStatic(staticValue)
|
||||
|
||||
Toggle the grid static state. Also toggle the `grid-stack-static` class.
|
||||
|
||||
- `staticValue` - if `true` the grid become static.
|
||||
|
||||
### update(el, x, y, width, height)
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to move
|
||||
- `x`, `y` - new position. If value is `null` or `undefined` it will be ignored.
|
||||
- `width`, `height` - new dimensions. If value is `null` or `undefined` it will be ignored.
|
||||
|
||||
Updates widget position/size.
|
||||
|
||||
### willItFit(x, y, width, height, autoPosition)
|
||||
|
||||
Returns `true` if the `height` of the grid will be less the vertical constraint. Always returns `true` if grid doesn't
|
||||
have `height` constraint.
|
||||
|
||||
```javascript
|
||||
if (grid.willItFit(newNode.x, newNode.y, newNode.width, newNode.height, true)) {
|
||||
grid.addWidget(newNode.el, newNode.x, newNode.y, newNode.width, newNode.height, true);
|
||||
}
|
||||
else {
|
||||
alert('Not enough free space to place the widget');
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Utils
|
||||
|
||||
### GridStackUI.Utils.sort(nodes[, dir[, width]])
|
||||
|
||||
Sorts array of nodes
|
||||
|
||||
- `nodes` - array to sort
|
||||
- `dir` - `1` for asc, `-1` for desc (optional)
|
||||
- `width` - width of the grid. If `undefined` the width will be calculated automatically (optional).
|
||||
Please check out `doc/README.md` for more information about gridstack.js API.
|
||||
|
||||
## Touch devices support
|
||||
|
||||
|
|
|
|||
405
doc/README.md
Normal file
405
doc/README.md
Normal file
|
|
@ -0,0 +1,405 @@
|
|||
gridstack.js API
|
||||
================
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
|
||||
|
||||
- [Options](#options)
|
||||
- [Grid attributes](#grid-attributes)
|
||||
- [Item attributes](#item-attributes)
|
||||
- [Events](#events)
|
||||
- [onchange(items)](#onchangeitems)
|
||||
- [ondragstart(event, ui)](#ondragstartevent-ui)
|
||||
- [ondragstop(event, ui)](#ondragstopevent-ui)
|
||||
- [onresizestart(event, ui)](#onresizestartevent-ui)
|
||||
- [onresizestop(event, ui)](#onresizestopevent-ui)
|
||||
- [disable(event)](#disableevent)
|
||||
- [enable(event)](#enableevent)
|
||||
- [API](#api)
|
||||
- [addWidget(el, x, y, width, height, autoPosition)](#addwidgetel-x-y-width-height-autoposition)
|
||||
- [batchUpdate()](#batchupdate)
|
||||
- [cellHeight()](#cellheight)
|
||||
- [cellHeight(val)](#cellheightval)
|
||||
- [cellWidth()](#cellwidth)
|
||||
- [commit()](#commit)
|
||||
- [destroy()](#destroy)
|
||||
- [disable()](#disable)
|
||||
- [enable()](#enable)
|
||||
- [enableMove(doEnable, includeNewWidgets)](#enablemovedoenable-includenewwidgets)
|
||||
- [enableResize(doEnable, includeNewWidgets)](#enableresizedoenable-includenewwidgets)
|
||||
- [getCellFromPixel(position)](#getcellfrompixelposition)
|
||||
- [isAreaEmpty(x, y, width, height)](#isareaemptyx-y-width-height)
|
||||
- [locked(el, val)](#lockedel-val)
|
||||
- [makeWidget(el)](#makewidgetel)
|
||||
- [maxHeight(el, val)](#maxheightel-val)
|
||||
- [minHeight(el, val)](#minheightel-val)
|
||||
- [maxWidth(el, val)](#maxwidthel-val)
|
||||
- [minWidth(el, val)](#minwidthel-val)
|
||||
- [movable(el, val)](#movableel-val)
|
||||
- [move(el, x, y)](#moveel-x-y)
|
||||
- [removeWidget(el, detachNode)](#removewidgetel-detachnode)
|
||||
- [removeAll()](#removeall)
|
||||
- [resize(el, width, height)](#resizeel-width-height)
|
||||
- [resizable(el, val)](#resizableel-val)
|
||||
- [setStatic(staticValue)](#setstaticstaticvalue)
|
||||
- [update(el, x, y, width, height)](#updateel-x-y-width-height)
|
||||
- [willItFit(x, y, width, height, autoPosition)](#willitfitx-y-width-height-autoposition)
|
||||
- [Utils](#utils)
|
||||
- [GridStackUI.Utils.sort(nodes[, dir[, width]])](#gridstackuiutilssortnodes-dir-width)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Options
|
||||
|
||||
- `alwaysShowResizeHandle` - if `true` the resizing handles are shown even if the user is not hovering over the widget
|
||||
(default: `false`)
|
||||
- `animate` - turns animation on (default: `false`)
|
||||
- `auto` - if `false` gridstack will not initialize existing items (default: `true`)
|
||||
- `cellHeight` - one cell height (default: `60`). Can be:
|
||||
- an integer (px)
|
||||
- a string (ex: '10em', '100px', '10rem')
|
||||
- 0 or null, in which case the library will not generate styles for rows. Everything will have to be defined in CSS files.
|
||||
- `disableDrag` - disallows dragging of widgets (default: `false`).
|
||||
- `disableResize` - disallows resizing of widgets (default: `false`).
|
||||
- `draggable` - allows to override jQuery UI draggable options. (default: `{handle: '.grid-stack-item-content', scroll: true, 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
|
||||
- `float` - enable floating widgets (default: `false`) See [example](http://troolee.github.io/gridstack.js/demo/float.html)
|
||||
- `itemClass` - widget class (default: `'grid-stack-item'`)
|
||||
- `minWidth` - minimal width. If window width is less, grid will be shown in one-column mode. You need also update your css file (`@media (max-width: 768px) {...}`) with corresponding value (default: `768`)
|
||||
- `placeholderClass` - class for placeholder (default: `'grid-stack-placeholder'`)
|
||||
- `placeholderText` - placeholder default content (default: `''`)
|
||||
- `resizable` - allows to override jQuery UI resizable options. (default: `{autoHide: true, handles: 'se'}`)
|
||||
- `staticGrid` - makes grid static (default `false`). If true widgets are not movable/resizable. You don't even need jQueryUI draggable/resizable. A CSS class `grid-stack-static` is also added to the container.
|
||||
- `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
|
||||
- `data-gs-height` - 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
|
||||
- `data-gs-width`, `data-gs-height` - element size
|
||||
- `data-gs-max-width`, `data-gs-min-width`, `data-gs-max-height`, `data-gs-min-height` - element constraints
|
||||
- `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
|
||||
- `data-gs-locked` - the widget will be locked. It means another widget wouldn't be able to move it during dragging or resizing.
|
||||
The widget can still be dragged or resized. You need to add `data-gs-no-resize` and `data-gs-no-move` attributes
|
||||
to completely lock the widget.
|
||||
|
||||
## Events
|
||||
|
||||
### onchange(items)
|
||||
|
||||
Occurs when adding/removing widgets or existing widgets change their position/size
|
||||
|
||||
```javascript
|
||||
var serializeWidgetMap = function (items) {
|
||||
console.log(items);
|
||||
};
|
||||
|
||||
$('.grid-stack').on('change', function (e, items) {
|
||||
serializeWidgetMap(items);
|
||||
});
|
||||
```
|
||||
|
||||
### ondragstart(event, ui)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('dragstart', function (event, ui) {
|
||||
var grid = this;
|
||||
var element = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### ondragstop(event, ui)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('dragstop', function (event, ui) {
|
||||
var grid = this;
|
||||
var element = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### onresizestart(event, ui)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('resizestart', function (event, ui) {
|
||||
var grid = this;
|
||||
var element = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### onresizestop(event, ui)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('resizestop', function (event, ui) {
|
||||
var grid = this;
|
||||
var element = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### disable(event)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('disable', function(event) {
|
||||
var grid = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
### enable(event)
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').on('enable', function(event) {
|
||||
var grid = event.target;
|
||||
});
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### addWidget(el, x, y, width, height, autoPosition)
|
||||
|
||||
Creates new widget and returns it.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to add
|
||||
- `x`, `y`, `width`, `height` - widget position/dimensions (Optional)
|
||||
- `autoPosition` - if `true` then `x`, `y` parameters will be ignored and widget will be places on the first available
|
||||
position
|
||||
|
||||
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.
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').gridstack();
|
||||
|
||||
var grid = $('.grid-stack').data('gridstack');
|
||||
grid.addWidget(el, 0, 0, 3, 2, true);
|
||||
```
|
||||
|
||||
### batchUpdate()
|
||||
|
||||
Initailizes batch updates. You will see no changes until `commit` method is called.
|
||||
|
||||
### cellHeight()
|
||||
|
||||
Gets current cell height.
|
||||
|
||||
### cellHeight(val)
|
||||
|
||||
Update current cell height. This method rebuilds an internal CSS stylesheet. Note: You can expect performance issues if
|
||||
call this method too often.
|
||||
|
||||
```javascript
|
||||
grid.cellHeight(grid.cellWidth() * 1.2);
|
||||
```
|
||||
|
||||
### cellWidth()
|
||||
|
||||
Gets current cell width.
|
||||
|
||||
### commit()
|
||||
|
||||
Finishes batch updates. Updates DOM nodes. You must call it after `batchUpdate`.
|
||||
|
||||
### destroy()
|
||||
|
||||
Destroys a grid instance.
|
||||
|
||||
### disable()
|
||||
|
||||
Disables widgets moving/resizing. This is a shortcut for:
|
||||
|
||||
```javascript
|
||||
grid.movable('.grid-stack-item', false);
|
||||
grid.resizable('.grid-stack-item', false);
|
||||
```
|
||||
|
||||
### enable()
|
||||
|
||||
Enables widgets moving/resizing. This is a shortcut for:
|
||||
|
||||
```javascript
|
||||
grid.movable('.grid-stack-item', true);
|
||||
grid.resizable('.grid-stack-item', true);
|
||||
```
|
||||
|
||||
### enableMove(doEnable, includeNewWidgets)
|
||||
|
||||
Enables/disables widget moving. `includeNewWidgets` will force new widgets to be draggable as per `doEnable`'s value by changing the `disableDrag` grid option. This is a shortcut for:
|
||||
|
||||
```javascript
|
||||
grid.movable(this.container.children('.' + this.opts.itemClass), doEnable);
|
||||
```
|
||||
|
||||
### enableResize(doEnable, includeNewWidgets)
|
||||
|
||||
Enables/disables widget resizing. `includeNewWidgets` will force new widgets to be resizable as per `doEnable`'s value by changing the `disableResize` grid option. This is a shortcut for:
|
||||
|
||||
```javascript
|
||||
grid.resizable(this.container.children('.' + this.opts.itemClass), doEnable);
|
||||
```
|
||||
|
||||
### getCellFromPixel(position)
|
||||
|
||||
Get the position of the cell under a pixel on screen.
|
||||
|
||||
Parameters :
|
||||
|
||||
- `position` - the position of the pixel to resolve in absolute coordinates, as an object with `top` and `left`properties
|
||||
|
||||
Returns an object with properties `x` and `y` i.e. the column and row in the grid.
|
||||
|
||||
### isAreaEmpty(x, y, width, height)
|
||||
|
||||
Checks if specified area is empty.
|
||||
|
||||
### locked(el, val)
|
||||
|
||||
Locks/unlocks widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - if `true` widget will be locked.
|
||||
|
||||
### makeWidget(el)
|
||||
|
||||
If you add elements to your gridstack container by hand, you have to tell gridstack afterwards to make them widgets. If you want gridstack to add the elements for you, use `addWidget` instead.
|
||||
Makes the given element a widget and returns it.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - element to convert to a widget
|
||||
|
||||
```javascript
|
||||
$('.grid-stack').gridstack();
|
||||
|
||||
$('.grid-stack').append('<div id="gsi-1" data-gs-x="0" data-gs-y="0" data-gs-width="3" data-gs-height="2" data-gs-auto-position="1"></div>')
|
||||
var grid = $('.grid-stack').data('gridstack');
|
||||
grid.makeWidget('gsi-1');
|
||||
```
|
||||
|
||||
### maxHeight(el, val)
|
||||
|
||||
Set the `maxHeight` for a widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - A numeric value of the number of rows
|
||||
|
||||
### minHeight(el, val)
|
||||
|
||||
Set the `minHeight` for a widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - A numeric value of the number of rows
|
||||
|
||||
### maxWidth(el, val)
|
||||
|
||||
Set the `maxWidth` for a widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - A numeric value of the number of columns
|
||||
|
||||
### minWidth(el, val)
|
||||
|
||||
Set the `minWidth` for a widget.
|
||||
|
||||
- `el` - widget to modify.
|
||||
- `val` - A numeric value of the number of columns
|
||||
|
||||
### movable(el, val)
|
||||
|
||||
Enables/Disables moving.
|
||||
|
||||
- `el` - widget to modify
|
||||
- `val` - if `true` widget will be draggable.
|
||||
|
||||
### move(el, x, y)
|
||||
|
||||
Changes widget position
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to move
|
||||
- `x`, `y` - new position. If value is `null` or `undefined` it will be ignored.
|
||||
|
||||
### removeWidget(el, detachNode)
|
||||
|
||||
Removes widget from the grid.
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to remove.
|
||||
- `detachNode` - if `false` DOM node won't be removed from the tree (Optional. Default `true`).
|
||||
|
||||
### removeAll()
|
||||
|
||||
Removes all widgets from the grid.
|
||||
|
||||
### resize(el, width, height)
|
||||
|
||||
Changes widget size
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to resize
|
||||
- `width`, `height` - new dimensions. If value is `null` or `undefined` it will be ignored.
|
||||
|
||||
### resizable(el, val)
|
||||
|
||||
Enables/Disables resizing.
|
||||
|
||||
- `el` - widget to modify
|
||||
- `val` - if `true` widget will be resizable.
|
||||
|
||||
### setStatic(staticValue)
|
||||
|
||||
Toggle the grid static state. Also toggle the `grid-stack-static` class.
|
||||
|
||||
- `staticValue` - if `true` the grid become static.
|
||||
|
||||
### update(el, x, y, width, height)
|
||||
|
||||
Parameters:
|
||||
|
||||
- `el` - widget to move
|
||||
- `x`, `y` - new position. If value is `null` or `undefined` it will be ignored.
|
||||
- `width`, `height` - new dimensions. If value is `null` or `undefined` it will be ignored.
|
||||
|
||||
Updates widget position/size.
|
||||
|
||||
### willItFit(x, y, width, height, autoPosition)
|
||||
|
||||
Returns `true` if the `height` of the grid will be less the vertical constraint. Always returns `true` if grid doesn't
|
||||
have `height` constraint.
|
||||
|
||||
```javascript
|
||||
if (grid.willItFit(newNode.x, newNode.y, newNode.width, newNode.height, true)) {
|
||||
grid.addWidget(newNode.el, newNode.x, newNode.y, newNode.width, newNode.height, true);
|
||||
}
|
||||
else {
|
||||
alert('Not enough free space to place the widget');
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Utils
|
||||
|
||||
### GridStackUI.Utils.sort(nodes[, dir[, width]])
|
||||
|
||||
Sorts array of nodes
|
||||
|
||||
- `nodes` - array to sort
|
||||
- `dir` - `1` for asc, `-1` for desc (optional)
|
||||
- `width` - width of the grid. If `undefined` the width will be calculated automatically (optional).
|
||||
Loading…
Reference in a new issue