Skip to content

Commit 84cca97

Browse files
adumesnyadumesny
committed
updated doc with static methods
1 parent cc9b22d commit 84cca97

File tree

1 file changed

+105
-77
lines changed

1 file changed

+105
-77
lines changed

‎doc/README.md‎

Lines changed: 105 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -22,41 +22,44 @@ gridstack.js API
2222
- [resizestart(event, el)](#resizestartevent-el)
2323
- [resize(event, el)](#resizeevent-el)
2424
- [resizestop(event, el)](#resizestopevent-el)
25+
- [API Global (static)](#api-global-static)
26+
- [`init(options: GridStackOptions = {}, elOrString: GridStackElement = '.grid-stack'): GridStack`](#initoptions-gridstackoptions---elorstring-gridstackelement--grid-stack-gridstack)
27+
- [`initAll(options: GridStackOptions = {}, selector = '.grid-stack'): GridStack[]`](#initalloptions-gridstackoptions---selector--grid-stack-gridstack)
28+
- [`addGrid(parent: HTMLElement, opt: GridStackOptions = {}): GridStack `](#addgridparent-htmlelement-opt-gridstackoptions---gridstack-)
29+
- [`setupDragIn(dragIn?: string, dragInOptions?: DDDragInOpt)`](#setupdragindragin-string-draginoptions-dddraginopt)
2530
- [API](#api)
26-
- [addGrid(parent: HTMLElement, opt: GridStackOptions)](#addgridparent-htmlelement-opt-gridstackoptions)
27-
- [addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)](#addwidgetel-gridstackwidget--gridstackelement-options-gridstackwidget)
28-
- [batchUpdate()](#batchupdate)
29-
- [compact()](#compact)
30-
- [cellHeight(val: number, update = true)](#cellheightval-number-update--true)
31-
- [cellWidth()](#cellwidth)
32-
- [commit()](#commit)
33-
- [column(column: number, layout: ColumnOptions = 'moveScale')](#columncolumn-number-layout-columnoptions--movescale)
34-
- [destroy([removeDOM])](#destroyremovedom)
35-
- [disable()](#disable)
36-
- [enable()](#enable)
37-
- [enableMove(doEnable, includeNewWidgets)](#enablemovedoenable-includenewwidgets)
38-
- [enableResize(doEnable, includeNewWidgets)](#enableresizedoenable-includenewwidgets)
39-
- [float(val?)](#floatval)
40-
- [getCellHeight()](#getcellheight)
41-
- [getCellFromPixel(position[, useOffset])](#getcellfrompixelposition-useoffset)
42-
- [getGridItems(): GridItemHTMLElement[]](#getgriditems-griditemhtmlelement)
43-
- [getMargin()](#getmargin)
44-
- [isAreaEmpty(x, y, width, height)](#isareaemptyx-y-width-height)
45-
- [load(layout: GridStackWidget[], boolean | ((w: GridStackWidget, add: boolean) => void) = true)](#loadlayout-gridstackwidget-boolean--w-gridstackwidget-add-boolean--void---true)
46-
- [makeWidget(el)](#makewidgetel)
47-
- [margin(value: numberOrString)](#marginvalue-numberorstring)
48-
- [movable(el, val)](#movableel-val)
49-
- [removeWidget(el, removeDOM = true, triggerEvent = true)](#removewidgetel-removedom--true-triggerevent--true)
50-
- [removeAll(removeDOM = true)](#removeallremovedom--true)
51-
- [resizable(el, val)](#resizableel-val)
52-
- [save(saveContent = true): GridStackWidget[]](#savesavecontent--true-gridstackwidget)
53-
- [setAnimation(doAnimate)](#setanimationdoanimate)
54-
- [setStatic(staticValue)](#setstaticstaticvalue)
55-
- [GridStack.setupDragIn(dragIn?: string, dragInOptions?: DDDragInOpt)](#gridstacksetupdragindragin-string-draginoptions-dddraginopt)
56-
- [update(el: GridStackElement, opts: GridStackWidget)](#updateel-gridstackelement-opts-gridstackwidget)
57-
- [willItFit(x, y, width, height, autoPosition)](#willitfitx-y-width-height-autoposition)
31+
- [`addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)`](#addwidgetel-gridstackwidget--gridstackelement-options-gridstackwidget)
32+
- [`batchUpdate()`](#batchupdate)
33+
- [`compact()`](#compact)
34+
- [`cellHeight(val: number, update = true)`](#cellheightval-number-update--true)
35+
- [`cellWidth()`](#cellwidth)
36+
- [`commit()`](#commit)
37+
- [`column(column: number, layout: ColumnOptions = 'moveScale')`](#columncolumn-number-layout-columnoptions--movescale)
38+
- [`destroy([removeDOM])`](#destroyremovedom)
39+
- [`disable()`](#disable)
40+
- [`enable()`](#enable)
41+
- [`enableMove(doEnable, includeNewWidgets)`](#enablemovedoenable-includenewwidgets)
42+
- [`enableResize(doEnable, includeNewWidgets)`](#enableresizedoenable-includenewwidgets)
43+
- [`float(val?)`](#floatval)
44+
- [`getCellHeight()`](#getcellheight)
45+
- [`getCellFromPixel(position[, useOffset])`](#getcellfrompixelposition-useoffset)
46+
- [`getGridItems(): GridItemHTMLElement[]`](#getgriditems-griditemhtmlelement)
47+
- [`getMargin()`](#getmargin)
48+
- [`isAreaEmpty(x, y, width, height)`](#isareaemptyx-y-width-height)
49+
- [`load(layout: GridStackWidget[], boolean | ((w: GridStackWidget, add: boolean) => void) = true)`](#loadlayout-gridstackwidget-boolean--w-gridstackwidget-add-boolean--void---true)
50+
- [`makeWidget(el)`](#makewidgetel)
51+
- [`margin(value: numberOrString)`](#marginvalue-numberorstring)
52+
- [`movable(el, val)`](#movableel-val)
53+
- [`removeWidget(el, removeDOM = true, triggerEvent = true)`](#removewidgetel-removedom--true-triggerevent--true)
54+
- [`removeAll(removeDOM = true)`](#removeallremovedom--true)
55+
- [`resizable(el, val)`](#resizableel-val)
56+
- [`save(saveContent = true): GridStackWidget[]`](#savesavecontent--true-gridstackwidget)
57+
- [`setAnimation(doAnimate)`](#setanimationdoanimate)
58+
- [`setStatic(staticValue)`](#setstaticstaticvalue)
59+
- [`update(el: GridStackElement, opts: GridStackWidget)`](#updateel-gridstackelement-opts-gridstackwidget)
60+
- [`willItFit(x, y, width, height, autoPosition)`](#willitfitx-y-width-height-autoposition)
5861
- [Utils](#utils)
59-
- [GridStack.Utils.sort(nodes[, dir[, width]])](#gridstackutilssortnodes-dir-width)
62+
- [`GridStack.Utils.sort(nodes[, dir[, width]])`](#gridstackutilssortnodes-dir-width)
6063

6164
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
6265

@@ -276,14 +279,48 @@ grid.on('resizestop', function(event: Event, el: GridItemHTMLElement) {
276279
```
277280

278281

279-
## API
282+
## API Global (static)
283+
284+
### `init(options: GridStackOptions = {}, elOrString: GridStackElement = '.grid-stack'): GridStack`
285+
286+
* initializing the HTML element, or selector string, into a grid will return the grid. Calling it again will
287+
simply return the existing instance (ignore any passed options). There is also an initAll() version that support multiple grids initialization at once. Or you can use addGrid() to create the entire grid from JSON.
288+
* @param options grid options (optional)
289+
* @param elOrString element or CSS selector (first one used) to convert to a grid (default to `'.grid-stack'` class selector)
290+
```js
291+
let grid = GridStack.init();
292+
// Note: the HTMLElement (of type GridHTMLElement) will store a `gridstack: GridStack` value that can be retrieve later
293+
let grid = document.querySelector('.grid-stack').gridstack;
294+
```
295+
296+
### `initAll(options: GridStackOptions = {}, selector = '.grid-stack'): GridStack[]`
297+
298+
* Will initialize a list of elements (given a selector) and return an array of grids.
299+
* @param options grid options (optional)
300+
* @param selector elements selector to convert to grids (default to '.grid-stack' class selector)
301+
302+
```js
303+
let grids = GridStack.initAll();
304+
grids.forEach(...)
305+
```
306+
307+
### `addGrid(parent: HTMLElement, opt: GridStackOptions = {}): GridStack `
280308

281-
### addGrid(parent: HTMLElement, opt: GridStackOptions)
309+
* call to create a grid with the given options, including loading any children from JSON structure. This will call `GridStack.init()`, then `grid.load()` on any passed children (recursively). Great alternative to calling `init()` if you want entire grid to come from JSON serialized data, including options.
310+
* @param parent HTML element parent to the grid
311+
* @param opt grids options used to initialize the grid, and list of children
312+
* see [nested.html](https://github.com/gridstack/gridstack.js/blob/develop/demo/nested.html) demo
282313

283-
create a grid under given parent, with given options and loading children recursively (for nested grids), instead of `init() + load()`. Used by `load()` to supports nested grids creation.
284-
see [nested.html](https://github.com/gridstack/gridstack.js/blob/develop/demo/nested.html) demo
314+
### `setupDragIn(dragIn?: string, dragInOptions?: DDDragInOpt)`
285315

286-
### addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)
316+
* call to setup dragging in from the outside (say toolbar), by specifying the class selection and options.
317+
Called during `GridStack.init()` as options, but can also be called directly (last param are cached) in case the toolbar is dynamically create and needs to change later.
318+
* @param dragIn string selector (ex: `'.sidebar .grid-stack-item'`)
319+
* @param dragInOptions options - see `DDDragInOpt`. (default: `{revert: 'invalid', handle: '.grid-stack-item-content', scroll: false, appendTo: 'body'}`
320+
321+
## API
322+
323+
### `addWidget(el?: GridStackWidget | GridStackElement, options?: GridStackWidget)`
287324

288325
Creates new widget and returns it. Options is an object containing the fields x,y,width,height,etc...
289326

@@ -302,31 +339,31 @@ grid.addWidget({w: 3, content: 'hello'});
302339
grid.addWidget('<div class="grid-stack-item"><div class="grid-stack-item-content">hello</div></div>', {w: 3});
303340
```
304341

305-
### batchUpdate()
342+
### `batchUpdate()`
306343

307344
starts batch updates. You will see no changes until `commit()` method is called.
308345

309-
### compact()
346+
### `compact()`
310347

311348
re-layout grid items to reclaim any empty space.
312349

313-
### cellHeight(val: number, update = true)
350+
### `cellHeight(val: number, update = true)`
314351

315352
Update current cell height (see - `cellHeight` options format). This method rebuilds an internal CSS stylesheet (unless optional update=false). Note: You can expect performance issues if call this method too often.
316353

317354
```js
318355
grid.cellHeight(grid.cellWidth() * 1.2);
319356
```
320357

321-
### cellWidth()
358+
### `cellWidth()`
322359

323360
Gets current cell width (grid width / # of columns).
324361

325-
### commit()
362+
### `commit()`
326363

327364
Ends batch updates. Updates DOM nodes. You must call it after `batchUpdate()`.
328365

329-
### column(column: number, layout: ColumnOptions = 'moveScale')
366+
### `column(column: number, layout: ColumnOptions = 'moveScale')`
330367

331368
set/get the number of columns in the grid. Will update existing widgets to conform to new number of columns,
332369
as well as cache the original layout so you can revert back to previous positions without loss.
@@ -340,15 +377,15 @@ Possible values: 'moveScale' | 'move' | 'scale' | 'none' | (column: number, oldC
340377
A custom function option takes new/old column count, and array of new/old positions.
341378
Note: new list may be partially already filled if we have a partial cache of the layout at that size (items were added later). If complete cache is present this won't get called at all.
342379

343-
### destroy([removeDOM])
380+
### `destroy([removeDOM])`
344381

345382
Destroys a grid instance.
346383

347384
Parameters:
348385

349386
- `removeDOM` - if `false` nodes and grid will not be removed from the DOM (Optional. Default `true`).
350387

351-
### disable()
388+
### `disable()`
352389

353390
Disables widgets moving/resizing. This is a shortcut for:
354391

@@ -357,7 +394,7 @@ grid.enableMove(false);
357394
grid.enableResize(false);
358395
```
359396

360-
### enable()
397+
### `enable()`
361398

362399
Enables widgets moving/resizing. This is a shortcut for:
363400

@@ -366,7 +403,7 @@ grid.enableMove(true);
366403
grid.enableResize(true);
367404
```
368405

369-
### enableMove(doEnable, includeNewWidgets)
406+
### `enableMove(doEnable, includeNewWidgets)`
370407

371408
Enables/disables widget moving. `includeNewWidgets` will force new widgets to be draggable as per `doEnable`'s value by changing the `disableDrag` grid option (default: true). This is a shortcut for:
372409

@@ -375,7 +412,7 @@ grid.movable('.grid-stack-item', doEnable);
375412
grid.opts.disableDrag = !doEnable;
376413
```
377414

378-
### enableResize(doEnable, includeNewWidgets)
415+
### `enableResize(doEnable, includeNewWidgets)`
379416

380417
Enables/disables widget resizing. `includeNewWidgets` will force new widgets to be resizable as per `doEnable`'s value by changing the `disableResize` grid option (default: true). This is a shortcut for:
381418

@@ -384,18 +421,18 @@ grid.resizable('.grid-stack-item', doEnable);
384421
grid.opts.disableResize = !doEnable;
385422
```
386423

387-
### float(val?)
424+
### `float(val?)`
388425

389426
set/get floating widgets (default: `false`)
390427

391428
- `val` - boolean to set true/false, else get the current value
392429

393-
### getCellHeight()
430+
### `getCellHeight()`
394431

395432
Gets current cell height.
396433

397434

398-
### getCellFromPixel(position[, useOffset])
435+
### `getCellFromPixel(position[, useOffset])`
399436

400437
Get the position of the cell under a pixel on screen.
401438

@@ -406,19 +443,19 @@ Parameters :
406443

407444
Returns an object with properties `x` and `y` i.e. the column and row in the grid.
408445

409-
### getGridItems(): GridItemHTMLElement[]
446+
### `getGridItems(): GridItemHTMLElement[]`
410447

411448
Return list of GridItem HTML dom elements (excluding temporary placeholder)
412449

413-
### getMargin()
450+
### `getMargin()`
414451

415452
returns current margin value (undefined if all 4 sides don't match).
416453

417-
### isAreaEmpty(x, y, width, height)
454+
### `isAreaEmpty(x, y, width, height)`
418455

419456
Checks if specified area is empty.
420457

421-
### load(layout: GridStackWidget[], boolean | ((w: GridStackWidget, add: boolean) => void) = true)
458+
### `load(layout: GridStackWidget[], boolean | ((w: GridStackWidget, add: boolean) => void) = true)`
422459

423460
- load the widgets from a list (see `save()`). This will call `update()` on each (matching by id) or add/remove widgets that are not there.
424461
- Optional `addAndRemove` boolean (default true) or callback method can be passed to control if and how missing widgets can be added/removed, giving the user control of insertion.
@@ -427,7 +464,7 @@ Checks if specified area is empty.
427464
- `addAndRemove` boolean (default true) or callback method can be passed to control if and how missing widgets can be added/removed, giving the user control of insertion.
428465
- see [example](http://gridstackjs.com/demo/serialization.html)
429466

430-
### makeWidget(el)
467+
### `makeWidget(el)`
431468

432469
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.
433470
Makes the given element a widget and returns it.
@@ -442,22 +479,22 @@ grid.el.appendChild('<div id="gsi-1" gs-x="0" gs-y="0" gs-w="3" gs-h="2" gs-auto
442479
grid.makeWidget('#gsi-1');
443480
```
444481

445-
### margin(value: numberOrString)
482+
### `margin(value: numberOrString)`
446483

447484
gap between grid item and content (default?: 10). This will set all 4 sides and support the CSS formats below
448485
- an `integer` (px)
449486
- a string with possible units (ex: `'5'`, `'2em'`, `'20px'`, `'2rem'`)
450487
- string with space separated values (ex: `'5px 10px 0 20px'` for all 4 sides, or `'5em 10em'` for top/bottom and left/right pairs like CSS).
451488
- Note: all sides must have same units (last one wins, default px)
452489

453-
### movable(el, val)
490+
### `movable(el, val)`
454491

455492
Enables/Disables moving.
456493

457494
- `el` - widget to modify
458495
- `val` - if `true` widget will be draggable.
459496

460-
### removeWidget(el, removeDOM = true, triggerEvent = true)
497+
### `removeWidget(el, removeDOM = true, triggerEvent = true)`
461498

462499
Removes widget from the grid.
463500

@@ -467,48 +504,39 @@ Parameters:
467504
- `removeDOM` - if `false` node won't be removed from the DOM (Optional. Default `true`).
468505
- `triggerEvent` if `false` (quiet mode) element will not be added to removed list and no 'removed' callbacks will be called (Default `true`).
469506

470-
### removeAll(removeDOM = true)
507+
### `removeAll(removeDOM = true)`
471508

472509
Removes all widgets from the grid.
473510

474511
Parameters:
475512

476513
- `removeDOM` - if `false` nodes won't be removed from the DOM (Optional. Default `true`).
477514

478-
### resizable(el, val)
515+
### `resizable(el, val)`
479516

480517
Enables/Disables resizing.
481518

482519
- `el` - widget to modify
483520
- `val` - if `true` widget will be resizable.
484521

485-
### save(saveContent = true): GridStackWidget[]
522+
### `save(saveContent = true): GridStackWidget[]`
486523

487524
- returns the layout of the grid (and optionally the html content as well) that can be serialized (list of item non default attributes, not just w,y,x,y but also min/max and id). See `load()`
488525
- see [example](http://gridstackjs.com/demo/serialization.html)
489526

490-
### setAnimation(doAnimate)
527+
### `setAnimation(doAnimate)`
491528

492529
Toggle the grid animation state. Toggles the `grid-stack-animate` class.
493530

494531
- `doAnimate` - if `true` the grid will animate.
495532

496-
### setStatic(staticValue)
533+
### `setStatic(staticValue)`
497534

498535
Toggle the grid static state. Also toggle the `grid-stack-static` class.
499536

500537
- `staticValue` - if `true` the grid becomes static.
501538

502-
### GridStack.setupDragIn(dragIn?: string, dragInOptions?: DDDragInOpt)
503-
504-
* call to setup dragging in from the outside (say toolbar), by specifying the class selection and options.
505-
* Called during `GridStack.init()` as options, but can also be called directly (last param are cached) in case the toolbar
506-
* is dynamically create and needs to change later.
507-
* `dragIn` string selector (ex: `'.sidebar .grid-stack-item'`)
508-
* `dragInOptions` options - see `DDDragInOpt`. (default: `{revert: 'invalid', handle: '.grid-stack-item-content', scroll: false, appendTo: 'body'}`
509-
510-
511-
### update(el: GridStackElement, opts: GridStackWidget)
539+
### `update(el: GridStackElement, opts: GridStackWidget)`
512540

513541
Parameters:
514542

@@ -517,7 +545,7 @@ Parameters:
517545

518546
Updates widget position/size and other info. Note: if you need to call this on all nodes, use load() instead which will update what changed and more.
519547

520-
### willItFit(x, y, width, height, autoPosition)
548+
### `willItFit(x, y, width, height, autoPosition)`
521549

522550
Returns `true` if the `height` of the grid will be less the vertical constraint. Always returns `true` if grid doesn't
523551
have `height` constraint.
@@ -533,7 +561,7 @@ else {
533561

534562
## Utils
535563

536-
### GridStack.Utils.sort(nodes[, dir[, width]])
564+
### `GridStack.Utils.sort(nodes[, dir[, width]])`
537565

538566
Sorts array of nodes
539567

0 commit comments

Comments
 (0)