gridstack
Version:
TypeScript/JS lib for dashboard layout and creation, responsive, mobile support, no external dependencies, with many wrappers (React, Angular, Vue, Ember, knockout...)
1,079 lines (1,078 loc) • 121 kB
JavaScript
/*!
* GridStack 12.0.0
* https://gridstackjs.com/
*
* Copyright (c) 2021-2024 Alain Dumesny
* see root license https://github.com/gridstack/gridstack.js/tree/master/LICENSE
*/
import { GridStackEngine } from './gridstack-engine';
import { Utils, obsolete } from './utils';
import { gridDefaults } from './types';
/*
* and include D&D by default
* TODO: while we could generate a gridstack-static.js at smaller size - saves about 31k (41k -> 72k)
* I don't know how to generate the DD only code at the remaining 31k to delay load as code depends on Gridstack.ts
* also it caused loading issues in prod - see https://github.com/gridstack/gridstack.js/issues/2039
*/
import { DDGridStack } from './dd-gridstack';
import { isTouch } from './dd-touch';
import { DDManager } from './dd-manager';
const dd = new DDGridStack;
// export all dependent file as well to make it easier for users to just import the main file
export * from './types';
export * from './utils';
export * from './gridstack-engine';
export * from './dd-gridstack';
/**
* Main gridstack class - you will need to call `GridStack.init()` first to initialize your grid.
* Note: your grid elements MUST have the following classes for the CSS layout to work:
* @example
* <div class="grid-stack">
* <div class="grid-stack-item">
* <div class="grid-stack-item-content">Item 1</div>
* </div>
* </div>
*/
class GridStack {
/**
* initializing the HTML element, or selector string, into a grid will return the grid. Calling it again will
* 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.
* @param options grid options (optional)
* @param elOrString element or CSS selector (first one used) to convert to a grid (default to '.grid-stack' class selector)
*
* @example
* const grid = GridStack.init();
*
* Note: the HTMLElement (of type GridHTMLElement) will store a `gridstack: GridStack` value that can be retrieve later
* const grid = document.querySelector('.grid-stack').gridstack;
*/
static init(options = {}, elOrString = '.grid-stack') {
if (typeof document === 'undefined')
return null; // temp workaround SSR
const el = GridStack.getGridElement(elOrString);
if (!el) {
if (typeof elOrString === 'string') {
console.error('GridStack.initAll() no grid was found with selector "' + elOrString + '" - element missing or wrong selector ?' +
'\nNote: ".grid-stack" is required for proper CSS styling and drag/drop, and is the default selector.');
}
else {
console.error('GridStack.init() no grid element was passed.');
}
return null;
}
if (!el.gridstack) {
el.gridstack = new GridStack(el, Utils.cloneDeep(options));
}
return el.gridstack;
}
/**
* Will initialize a list of elements (given a selector) and return an array of grids.
* @param options grid options (optional)
* @param selector elements selector to convert to grids (default to '.grid-stack' class selector)
*
* @example
* const grids = GridStack.initAll();
* grids.forEach(...)
*/
static initAll(options = {}, selector = '.grid-stack') {
const grids = [];
if (typeof document === 'undefined')
return grids; // temp workaround SSR
GridStack.getGridElements(selector).forEach(el => {
if (!el.gridstack) {
el.gridstack = new GridStack(el, Utils.cloneDeep(options));
}
grids.push(el.gridstack);
});
if (grids.length === 0) {
console.error('GridStack.initAll() no grid was found with selector "' + selector + '" - element missing or wrong selector ?' +
'\nNote: ".grid-stack" is required for proper CSS styling and drag/drop, and is the default selector.');
}
return grids;
}
/**
* 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.
* @param parent HTML element parent to the grid
* @param opt grids options used to initialize the grid, and list of children
*/
static addGrid(parent, opt = {}) {
if (!parent)
return null;
let el = parent;
if (el.gridstack) {
// already a grid - set option and load data
const grid = el.gridstack;
if (opt)
grid.opts = { ...grid.opts, ...opt };
if (opt.children !== undefined)
grid.load(opt.children);
return grid;
}
// create the grid element, but check if the passed 'parent' already has grid styling and should be used instead
const parentIsGrid = parent.classList.contains('grid-stack');
if (!parentIsGrid || GridStack.addRemoveCB) {
if (GridStack.addRemoveCB) {
el = GridStack.addRemoveCB(parent, opt, true, true);
}
else {
el = Utils.createDiv(['grid-stack', opt.class], parent);
}
}
// create grid class and load any children
const grid = GridStack.init(opt, el);
return grid;
}
/** call this method to register your engine instead of the default one.
* See instead `GridStackOptions.engineClass` if you only need to
* replace just one instance.
*/
static registerEngine(engineClass) {
GridStack.engineClass = engineClass;
}
/** @internal create placeholder DIV as needed */
get placeholder() {
if (!this._placeholder) {
this._placeholder = Utils.createDiv([this.opts.placeholderClass, gridDefaults.itemClass, this.opts.itemClass]);
const placeholderChild = Utils.createDiv(['placeholder-content'], this._placeholder);
if (this.opts.placeholderText) {
placeholderChild.textContent = this.opts.placeholderText;
}
}
return this._placeholder;
}
/**
* Construct a grid item from the given element and options
* @param el the HTML element tied to this grid after it's been initialized
* @param opts grid options - public for classes to access, but use methods to modify!
*/
constructor(el, opts = {}) {
this.el = el;
this.opts = opts;
/** time to wait for animation (if enabled) to be done so content sizing can happen */
this.animationDelay = 300 + 10;
/** @internal */
this._gsEventHandler = {};
/** @internal extra row added when dragging at the bottom of the grid */
this._extraDragRow = 0;
/** @internal meant to store the scale of the active grid */
this.dragTransform = { xScale: 1, yScale: 1, xOffset: 0, yOffset: 0 };
el.gridstack = this;
this.opts = opts = opts || {}; // handles null/undefined/0
if (!el.classList.contains('grid-stack')) {
this.el.classList.add('grid-stack');
}
// if row property exists, replace minRow and maxRow instead
if (opts.row) {
opts.minRow = opts.maxRow = opts.row;
delete opts.row;
}
const rowAttr = Utils.toNumber(el.getAttribute('gs-row'));
// flag only valid in sub-grids (handled by parent, not here)
if (opts.column === 'auto') {
delete opts.column;
}
// save original setting so we can restore on save
if (opts.alwaysShowResizeHandle !== undefined) {
opts._alwaysShowResizeHandle = opts.alwaysShowResizeHandle;
}
let bk = opts.columnOpts?.breakpoints;
// LEGACY: oneColumnMode stuff changed in v10.x - check if user explicitly set something to convert over
const oldOpts = opts;
if (oldOpts.oneColumnModeDomSort) {
delete oldOpts.oneColumnModeDomSort;
console.log('warning: Gridstack oneColumnModeDomSort no longer supported. Use GridStackOptions.columnOpts instead.');
}
if (oldOpts.oneColumnSize || oldOpts.disableOneColumnMode === false) {
const oneSize = oldOpts.oneColumnSize || 768;
delete oldOpts.oneColumnSize;
delete oldOpts.disableOneColumnMode;
opts.columnOpts = opts.columnOpts || {};
bk = opts.columnOpts.breakpoints = opts.columnOpts.breakpoints || [];
let oneColumn = bk.find(b => b.c === 1);
if (!oneColumn) {
oneColumn = { c: 1, w: oneSize };
bk.push(oneColumn, { c: 12, w: oneSize + 1 });
}
else
oneColumn.w = oneSize;
}
//...end LEGACY
// cleanup responsive opts (must have columnWidth | breakpoints) then sort breakpoints by size (so we can match during resize)
const resp = opts.columnOpts;
if (resp) {
if (!resp.columnWidth && !resp.breakpoints?.length) {
delete opts.columnOpts;
bk = undefined;
}
else {
resp.columnMax = resp.columnMax || 12;
}
}
if (bk?.length > 1)
bk.sort((a, b) => (b.w || 0) - (a.w || 0));
// elements DOM attributes override any passed options (like CSS style) - merge the two together
const defaults = {
...Utils.cloneDeep(gridDefaults),
column: Utils.toNumber(el.getAttribute('gs-column')) || gridDefaults.column,
minRow: rowAttr ? rowAttr : Utils.toNumber(el.getAttribute('gs-min-row')) || gridDefaults.minRow,
maxRow: rowAttr ? rowAttr : Utils.toNumber(el.getAttribute('gs-max-row')) || gridDefaults.maxRow,
staticGrid: Utils.toBool(el.getAttribute('gs-static')) || gridDefaults.staticGrid,
sizeToContent: Utils.toBool(el.getAttribute('gs-size-to-content')) || undefined,
draggable: {
handle: (opts.handleClass ? '.' + opts.handleClass : (opts.handle ? opts.handle : '')) || gridDefaults.draggable.handle,
},
removableOptions: {
accept: opts.itemClass || gridDefaults.removableOptions.accept,
decline: gridDefaults.removableOptions.decline
},
};
if (el.getAttribute('gs-animate')) { // default to true, but if set to false use that instead
defaults.animate = Utils.toBool(el.getAttribute('gs-animate'));
}
opts = Utils.defaults(opts, defaults);
this._initMargin(); // part of settings defaults...
// Now check if we're loading into !12 column mode FIRST so we don't do un-necessary work (like cellHeight = width / 12 then go 1 column)
this.checkDynamicColumn();
this._updateColumnVar(opts);
if (opts.rtl === 'auto') {
opts.rtl = (el.style.direction === 'rtl');
}
if (opts.rtl) {
this.el.classList.add('grid-stack-rtl');
}
// check if we're been nested, and if so update our style and keep pointer around (used during save)
const parentGridItem = this.el.closest('.' + gridDefaults.itemClass);
const parentNode = parentGridItem?.gridstackNode;
if (parentNode) {
parentNode.subGrid = this;
this.parentGridNode = parentNode;
this.el.classList.add('grid-stack-nested');
parentNode.el.classList.add('grid-stack-sub-grid');
}
this._isAutoCellHeight = (opts.cellHeight === 'auto');
if (this._isAutoCellHeight || opts.cellHeight === 'initial') {
// make the cell content square initially (will use resize/column event to keep it square)
this.cellHeight(undefined);
}
else {
// append unit if any are set
if (typeof opts.cellHeight == 'number' && opts.cellHeightUnit && opts.cellHeightUnit !== gridDefaults.cellHeightUnit) {
opts.cellHeight = opts.cellHeight + opts.cellHeightUnit;
delete opts.cellHeightUnit;
}
const val = opts.cellHeight;
delete opts.cellHeight; // force initial cellHeight() call to set the value
this.cellHeight(val);
}
// see if we need to adjust auto-hide
if (opts.alwaysShowResizeHandle === 'mobile') {
opts.alwaysShowResizeHandle = isTouch;
}
this._setStaticClass();
const engineClass = opts.engineClass || GridStack.engineClass || GridStackEngine;
this.engine = new engineClass({
column: this.getColumn(),
float: opts.float,
maxRow: opts.maxRow,
onChange: (cbNodes) => {
cbNodes.forEach(n => {
const el = n.el;
if (!el)
return;
if (n._removeDOM) {
if (el)
el.remove();
delete n._removeDOM;
}
else {
this._writePosAttr(el, n);
}
});
this._updateContainerHeight();
}
});
if (opts.auto) {
this.batchUpdate(); // prevent in between re-layout #1535 TODO: this only set float=true, need to prevent collision check...
this.engine._loading = true; // loading collision check
this.getGridItems().forEach(el => this._prepareElement(el));
delete this.engine._loading;
this.batchUpdate(false);
}
// load any passed in children as well, which overrides any DOM layout done above
if (opts.children) {
const children = opts.children;
delete opts.children;
if (children.length)
this.load(children); // don't load empty
}
this.setAnimation();
// dynamic grids require pausing during drag to detect over to nest vs push
if (opts.subGridDynamic && !DDManager.pauseDrag)
DDManager.pauseDrag = true;
if (opts.draggable?.pause !== undefined)
DDManager.pauseDrag = opts.draggable.pause;
this._setupRemoveDrop();
this._setupAcceptWidget();
this._updateResizeEvent();
}
_updateColumnVar(opts = this.opts) {
this.el.classList.add('gs-' + opts.column);
if (typeof opts.column === 'number')
this.el.style.setProperty('--gs-column-width', `${100 / opts.column}%`);
}
/**
* add a new widget and returns it.
*
* Widget will be always placed even if result height is more than actual grid height.
* You need to use `willItFit()` before calling addWidget for additional check.
* See also `makeWidget(el)` for DOM element.
*
* @example
* const grid = GridStack.init();
* grid.addWidget({w: 3, content: 'hello'});
*
* @param w GridStackWidget definition. used MakeWidget(el) if you have dom element instead.
*/
addWidget(w) {
if (typeof w === 'string') {
console.error('V11: GridStack.addWidget() does not support string anymore. see #2736');
return;
}
if (w.ELEMENT_NODE) {
console.error('V11: GridStack.addWidget() does not support HTMLElement anymore. use makeWidget()');
return this.makeWidget(w);
}
let el;
let node = w;
node.grid = this;
if (node?.el) {
el = node.el; // re-use element stored in the node
}
else if (GridStack.addRemoveCB) {
el = GridStack.addRemoveCB(this.el, w, true, false);
}
else {
el = this.createWidgetDivs(node);
}
if (!el)
return;
// if the caller ended up initializing the widget in addRemoveCB, or we stared with one already, skip the rest
node = el.gridstackNode;
if (node && el.parentElement === this.el && this.engine.nodes.find(n => n._id === node._id))
return el;
// Tempting to initialize the passed in opt with default and valid values, but this break knockout demos
// as the actual value are filled in when _prepareElement() calls el.getAttribute('gs-xyz') before adding the node.
// So make sure we load any DOM attributes that are not specified in passed in options (which override)
const domAttr = this._readAttr(el);
Utils.defaults(w, domAttr);
this.engine.prepareNode(w);
// this._writeAttr(el, w); why write possibly incorrect values back when makeWidget() will ?
this.el.appendChild(el);
this.makeWidget(el, w);
return el;
}
/** create the default grid item divs, and content (possibly lazy loaded) by using GridStack.renderCB() */
createWidgetDivs(n) {
const el = Utils.createDiv(['grid-stack-item', this.opts.itemClass]);
const cont = Utils.createDiv(['grid-stack-item-content'], el);
if (Utils.lazyLoad(n)) {
if (!n.visibleObservable) {
n.visibleObservable = new IntersectionObserver(([entry]) => {
if (entry.isIntersecting) {
n.visibleObservable?.disconnect();
delete n.visibleObservable;
GridStack.renderCB(cont, n);
n.grid?.prepareDragDrop(n.el);
}
});
window.setTimeout(() => n.visibleObservable?.observe(el)); // wait until callee sets position attributes
}
}
else
GridStack.renderCB(cont, n);
return el;
}
/**
* Convert an existing gridItem element into a sub-grid with the given (optional) options, else inherit them
* from the parent's subGrid options.
* @param el gridItem element to convert
* @param ops (optional) sub-grid options, else default to node, then parent settings, else defaults
* @param nodeToAdd (optional) node to add to the newly created sub grid (used when dragging over existing regular item)
* @param saveContent if true (default) the html inside .grid-stack-content will be saved to child widget
* @returns newly created grid
*/
makeSubGrid(el, ops, nodeToAdd, saveContent = true) {
let node = el.gridstackNode;
if (!node) {
node = this.makeWidget(el).gridstackNode;
}
if (node.subGrid?.el)
return node.subGrid; // already done
// find the template subGrid stored on a parent as fallback...
let subGridTemplate; // eslint-disable-next-line @typescript-eslint/no-this-alias
let grid = this;
while (grid && !subGridTemplate) {
subGridTemplate = grid.opts?.subGridOpts;
grid = grid.parentGridNode?.grid;
}
//... and set the create options
ops = Utils.cloneDeep({
// by default sub-grid inherit from us | parent, other than id, children, etc...
...this.opts, id: undefined, children: undefined, column: 'auto', columnOpts: undefined, layout: 'list', subGridOpts: undefined,
...(subGridTemplate || {}),
...(ops || node.subGridOpts || {})
});
node.subGridOpts = ops;
// if column special case it set, remember that flag and set default
let autoColumn;
if (ops.column === 'auto') {
autoColumn = true;
ops.column = Math.max(node.w || 1, nodeToAdd?.w || 1);
delete ops.columnOpts; // driven by parent
}
// if we're converting an existing full item, move over the content to be the first sub item in the new grid
let content = node.el.querySelector('.grid-stack-item-content');
let newItem;
let newItemOpt;
if (saveContent) {
this._removeDD(node.el); // remove D&D since it's set on content div
newItemOpt = { ...node, x: 0, y: 0 };
Utils.removeInternalForSave(newItemOpt);
delete newItemOpt.subGridOpts;
if (node.content) {
newItemOpt.content = node.content;
delete node.content;
}
if (GridStack.addRemoveCB) {
newItem = GridStack.addRemoveCB(this.el, newItemOpt, true, false);
}
else {
newItem = Utils.createDiv(['grid-stack-item']);
newItem.appendChild(content);
content = Utils.createDiv(['grid-stack-item-content'], node.el);
}
this.prepareDragDrop(node.el); // ... and restore original D&D
}
// if we're adding an additional item, make the container large enough to have them both
if (nodeToAdd) {
const w = autoColumn ? ops.column : node.w;
const h = node.h + nodeToAdd.h;
const style = node.el.style;
style.transition = 'none'; // show up instantly so we don't see scrollbar with nodeToAdd
this.update(node.el, { w, h });
setTimeout(() => style.transition = null); // recover animation
}
const subGrid = node.subGrid = GridStack.addGrid(content, ops);
if (nodeToAdd?._moving)
subGrid._isTemp = true; // prevent re-nesting as we add over
if (autoColumn)
subGrid._autoColumn = true;
// add the original content back as a child of hte newly created grid
if (saveContent) {
subGrid.makeWidget(newItem, newItemOpt);
}
// now add any additional node
if (nodeToAdd) {
if (nodeToAdd._moving) {
// create an artificial event even for the just created grid to receive this item
window.setTimeout(() => Utils.simulateMouseEvent(nodeToAdd._event, 'mouseenter', subGrid.el), 0);
}
else {
subGrid.makeWidget(node.el, node);
}
}
// if sizedToContent, we need to re-calc the size of ourself
this.resizeToContentCheck(false, node);
return subGrid;
}
/**
* called when an item was converted into a nested grid to accommodate a dragged over item, but then item leaves - return back
* to the original grid-item. Also called to remove empty sub-grids when last item is dragged out (since re-creating is simple)
*/
removeAsSubGrid(nodeThatRemoved) {
const pGrid = this.parentGridNode?.grid;
if (!pGrid)
return;
pGrid.batchUpdate();
pGrid.removeWidget(this.parentGridNode.el, true, true);
this.engine.nodes.forEach(n => {
// migrate any children over and offsetting by our location
n.x += this.parentGridNode.x;
n.y += this.parentGridNode.y;
pGrid.makeWidget(n.el, n);
});
pGrid.batchUpdate(false);
if (this.parentGridNode)
delete this.parentGridNode.subGrid;
delete this.parentGridNode;
// create an artificial event for the original grid now that this one is gone (got a leave, but won't get enter)
if (nodeThatRemoved) {
window.setTimeout(() => Utils.simulateMouseEvent(nodeThatRemoved._event, 'mouseenter', pGrid.el), 0);
}
}
/**
* saves the current layout returning a list of widgets for serialization which might include any nested grids.
* @param saveContent if true (default) the latest html inside .grid-stack-content will be saved to GridStackWidget.content field, else it will
* be removed.
* @param saveGridOpt if true (default false), save the grid options itself, so you can call the new GridStack.addGrid()
* to recreate everything from scratch. GridStackOptions.children would then contain the widget list instead.
* @param saveCB callback for each node -> widget, so application can insert additional data to be saved into the widget data structure.
* @returns list of widgets or full grid option, including .children list of widgets
*/
save(saveContent = true, saveGridOpt = false, saveCB = GridStack.saveCB) {
// return copied GridStackWidget (with optionally .el) we can modify at will...
const list = this.engine.save(saveContent, saveCB);
// check for HTML content and nested grids
list.forEach(n => {
if (saveContent && n.el && !n.subGrid && !saveCB) { // sub-grid are saved differently, not plain content
const itemContent = n.el.querySelector('.grid-stack-item-content');
n.content = itemContent?.innerHTML;
if (!n.content)
delete n.content;
}
else {
if (!saveContent && !saveCB) {
delete n.content;
}
// check for nested grid
if (n.subGrid?.el) {
const listOrOpt = n.subGrid.save(saveContent, saveGridOpt, saveCB);
n.subGridOpts = (saveGridOpt ? listOrOpt : { children: listOrOpt });
delete n.subGrid;
}
}
delete n.el;
});
// check if save entire grid options (needed for recursive) + children...
if (saveGridOpt) {
const o = Utils.cloneDeep(this.opts);
// delete default values that will be recreated on launch
if (o.marginBottom === o.marginTop && o.marginRight === o.marginLeft && o.marginTop === o.marginRight) {
o.margin = o.marginTop;
delete o.marginTop;
delete o.marginRight;
delete o.marginBottom;
delete o.marginLeft;
}
if (o.rtl === (this.el.style.direction === 'rtl')) {
o.rtl = 'auto';
}
if (this._isAutoCellHeight) {
o.cellHeight = 'auto';
}
if (this._autoColumn) {
o.column = 'auto';
}
const origShow = o._alwaysShowResizeHandle;
delete o._alwaysShowResizeHandle;
if (origShow !== undefined) {
o.alwaysShowResizeHandle = origShow;
}
else {
delete o.alwaysShowResizeHandle;
}
Utils.removeInternalAndSame(o, gridDefaults);
o.children = list;
return o;
}
return list;
}
/**
* load the widgets from a list. This will call update() on each (matching by id) or add/remove widgets that are not there.
*
* @param items list of widgets definition to update/create
* @param addRemove 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.
*
* @example
* see http://gridstackjs.com/demo/serialization.html
*/
load(items, addRemove = GridStack.addRemoveCB || true) {
items = Utils.cloneDeep(items); // so we can mod
const column = this.getColumn();
// make sure size 1x1 (default) is present as it may need to override current sizes
items.forEach(n => { n.w = n.w || 1; n.h = n.h || 1; });
// sort items. those without coord will be appended last
items = Utils.sort(items);
this.engine.skipCacheUpdate = this._ignoreLayoutsNodeChange = true; // skip layout update
// if we're loading a layout into for example 1 column and items don't fit, make sure to save
// the original wanted layout so we can scale back up correctly #1471
let maxColumn = 0;
items.forEach(n => { maxColumn = Math.max(maxColumn, (n.x || 0) + n.w); });
if (maxColumn > this.engine.defaultColumn)
this.engine.defaultColumn = maxColumn;
if (maxColumn > column) {
// if we're loading (from empty) into a smaller column, check for special responsive layout
if (this.engine.nodes.length === 0 && this.responseLayout) {
this.engine.nodes = items;
this.engine.columnChanged(maxColumn, column, this.responseLayout);
items = this.engine.nodes;
this.engine.nodes = [];
delete this.responseLayout;
}
else
this.engine.cacheLayout(items, maxColumn, true);
}
// if given a different callback, temporally set it as global option so creating will use it
const prevCB = GridStack.addRemoveCB;
if (typeof (addRemove) === 'function')
GridStack.addRemoveCB = addRemove;
const removed = [];
this.batchUpdate();
// if we are loading from empty temporarily remove animation
const blank = !this.engine.nodes.length;
if (blank)
this.setAnimation(false);
// see if any items are missing from new layout and need to be removed first
if (!blank && addRemove) {
const copyNodes = [...this.engine.nodes]; // don't loop through array you modify
copyNodes.forEach(n => {
if (!n.id)
return;
const item = Utils.find(items, n.id);
if (!item) {
if (GridStack.addRemoveCB)
GridStack.addRemoveCB(this.el, n, false, false);
removed.push(n); // batch keep track
this.removeWidget(n.el, true, false);
}
});
}
// now add/update the widgets - starting with removing items in the new layout we will reposition
// to reduce collision and add no-coord ones at next available spot
this.engine._loading = true; // help with collision
const updateNodes = [];
this.engine.nodes = this.engine.nodes.filter(n => {
if (Utils.find(items, n.id)) {
updateNodes.push(n);
return false;
} // remove if found from list
return true;
});
items.forEach(w => {
const item = Utils.find(updateNodes, w.id);
if (item) {
// if item sizes to content, re-use the exiting height so it's a better guess at the final size (same if width doesn't change)
if (Utils.shouldSizeToContent(item))
w.h = item.h;
// check if missing coord, in which case find next empty slot with new (or old if missing) sizes
this.engine.nodeBoundFix(w);
if (w.autoPosition || w.x === undefined || w.y === undefined) {
w.w = w.w || item.w;
w.h = w.h || item.h;
this.engine.findEmptyPosition(w);
}
// add back to current list BUT force a collision check if it 'appears' we didn't change to make sure we don't overlap others now
this.engine.nodes.push(item);
if (Utils.samePos(item, w) && this.engine.nodes.length > 1) {
this.moveNode(item, { ...w, forceCollide: true });
Utils.copyPos(w, item); // use possily updated values before update() is called next (no-op since already moved)
}
this.update(item.el, w);
if (w.subGridOpts?.children) { // update any sub grid as well
const sub = item.el.querySelector('.grid-stack');
if (sub && sub.gridstack) {
sub.gridstack.load(w.subGridOpts.children); // TODO: support updating grid options ?
}
}
}
else if (addRemove) {
this.addWidget(w);
}
});
delete this.engine._loading; // done loading
this.engine.removedNodes = removed;
this.batchUpdate(false);
// after commit, clear that flag
delete this._ignoreLayoutsNodeChange;
delete this.engine.skipCacheUpdate;
prevCB ? GridStack.addRemoveCB = prevCB : delete GridStack.addRemoveCB;
// delay adding animation back
if (blank && this.opts?.animate)
this.setAnimation(this.opts.animate, true);
return this;
}
/**
* use before calling a bunch of `addWidget()` to prevent un-necessary relayouts in between (more efficient)
* and get a single event callback. You will see no changes until `batchUpdate(false)` is called.
*/
batchUpdate(flag = true) {
this.engine.batchUpdate(flag);
if (!flag) {
this._updateContainerHeight();
this._triggerRemoveEvent();
this._triggerAddEvent();
this._triggerChangeEvent();
}
return this;
}
/**
* Gets current cell height.
*/
getCellHeight(forcePixel = false) {
if (this.opts.cellHeight && this.opts.cellHeight !== 'auto' &&
(!forcePixel || !this.opts.cellHeightUnit || this.opts.cellHeightUnit === 'px')) {
return this.opts.cellHeight;
}
// do rem/em/cm/mm to px conversion
if (this.opts.cellHeightUnit === 'rem') {
return this.opts.cellHeight * parseFloat(getComputedStyle(document.documentElement).fontSize);
}
if (this.opts.cellHeightUnit === 'em') {
return this.opts.cellHeight * parseFloat(getComputedStyle(this.el).fontSize);
}
if (this.opts.cellHeightUnit === 'cm') {
// 1cm = 96px/2.54. See https://www.w3.org/TR/css-values-3/#absolute-lengths
return this.opts.cellHeight * (96 / 2.54);
}
if (this.opts.cellHeightUnit === 'mm') {
return this.opts.cellHeight * (96 / 2.54) / 10;
}
// else get first cell height
const el = this.el.querySelector('.' + this.opts.itemClass);
if (el) {
const h = Utils.toNumber(el.getAttribute('gs-h')) || 1; // since we don't write 1 anymore
return Math.round(el.offsetHeight / h);
}
// else do entire grid and # of rows (but doesn't work if min-height is the actual constrain)
const rows = parseInt(this.el.getAttribute('gs-current-row'));
return rows ? Math.round(this.el.getBoundingClientRect().height / rows) : this.opts.cellHeight;
}
/**
* Update current cell height - see `GridStackOptions.cellHeight` for format.
* This method rebuilds an internal CSS style sheet.
* Note: You can expect performance issues if call this method too often.
*
* @param val the cell height. If not passed (undefined), cells content will be made square (match width minus margin),
* if pass 0 the CSS will be generated by the application instead.
*
* @example
* grid.cellHeight(100); // same as 100px
* grid.cellHeight('70px');
* grid.cellHeight(grid.cellWidth() * 1.2);
*/
cellHeight(val) {
// if not called internally, check if we're changing mode
if (val !== undefined) {
if (this._isAutoCellHeight !== (val === 'auto')) {
this._isAutoCellHeight = (val === 'auto');
this._updateResizeEvent();
}
}
if (val === 'initial' || val === 'auto') {
val = undefined;
}
// make item content be square
if (val === undefined) {
const marginDiff = -this.opts.marginRight - this.opts.marginLeft
+ this.opts.marginTop + this.opts.marginBottom;
val = this.cellWidth() + marginDiff;
}
const data = Utils.parseHeight(val);
if (this.opts.cellHeightUnit === data.unit && this.opts.cellHeight === data.h) {
return this;
}
this.opts.cellHeightUnit = data.unit;
this.opts.cellHeight = data.h;
// finally update var and container
this.el.style.setProperty('--gs-cell-height', `${this.opts.cellHeight}${this.opts.cellHeightUnit}`);
this._updateContainerHeight();
this.resizeToContentCheck();
return this;
}
/** Gets current cell width. */
cellWidth() {
return this._widthOrContainer() / this.getColumn();
}
/** return our expected width (or parent) , and optionally of window for dynamic column check */
_widthOrContainer(forBreakpoint = false) {
// use `offsetWidth` or `clientWidth` (no scrollbar) ?
// https://stackoverflow.com/questions/21064101/understanding-offsetwidth-clientwidth-scrollwidth-and-height-respectively
return forBreakpoint && this.opts.columnOpts?.breakpointForWindow ? window.innerWidth : (this.el.clientWidth || this.el.parentElement.clientWidth || window.innerWidth);
}
/** checks for dynamic column count for our current size, returning true if changed */
checkDynamicColumn() {
const resp = this.opts.columnOpts;
if (!resp || (!resp.columnWidth && !resp.breakpoints?.length))
return false;
const column = this.getColumn();
let newColumn = column;
const w = this._widthOrContainer(true);
if (resp.columnWidth) {
newColumn = Math.min(Math.round(w / resp.columnWidth) || 1, resp.columnMax);
}
else {
// find the closest breakpoint (already sorted big to small) that matches
newColumn = resp.columnMax;
let i = 0;
while (i < resp.breakpoints.length && w <= resp.breakpoints[i].w) {
newColumn = resp.breakpoints[i++].c || column;
}
}
if (newColumn !== column) {
const bk = resp.breakpoints?.find(b => b.c === newColumn);
this.column(newColumn, bk?.layout || resp.layout);
return true;
}
return false;
}
/**
* re-layout grid items to reclaim any empty space. Options are:
* 'list' keep the widget left->right order the same, even if that means leaving an empty slot if things don't fit
* 'compact' might re-order items to fill any empty space
*
* doSort - 'false' to let you do your own sorting ahead in case you need to control a different order. (default to sort)
*/
compact(layout = 'compact', doSort = true) {
this.engine.compact(layout, doSort);
this._triggerChangeEvent();
return this;
}
/**
* set the number of columns in the grid. Will update existing widgets to conform to new number of columns,
* as well as cache the original layout so you can revert back to previous positions without loss.
* @param column - Integer > 0 (default 12).
* @param layout specify the type of re-layout that will happen (position, size, etc...).
* Note: items will never be outside of the current column boundaries. default ('moveScale'). Ignored for 1 column
*/
column(column, layout = 'moveScale') {
if (!column || column < 1 || this.opts.column === column)
return this;
const oldColumn = this.getColumn();
this.opts.column = column;
if (!this.engine) {
// called in constructor, noting else to do but remember that breakpoint layout
this.responseLayout = layout;
return this;
}
this.engine.column = column;
this.el.classList.remove('gs-' + oldColumn);
this._updateColumnVar();
// update the items now
this.engine.columnChanged(oldColumn, column, layout);
if (this._isAutoCellHeight)
this.cellHeight();
this.resizeToContentCheck(true); // wait for width resizing
// and trigger our event last...
this._ignoreLayoutsNodeChange = true; // skip layout update
this._triggerChangeEvent();
delete this._ignoreLayoutsNodeChange;
return this;
}
/**
* get the number of columns in the grid (default 12)
*/
getColumn() { return this.opts.column; }
/** returns an array of grid HTML elements (no placeholder) - used to iterate through our children in DOM order */
getGridItems() {
return Array.from(this.el.children)
.filter((el) => el.matches('.' + this.opts.itemClass) && !el.matches('.' + this.opts.placeholderClass));
}
/** true if changeCB should be ignored due to column change, sizeToContent, loading, etc... which caller can ignore for dirty flag case */
isIgnoreChangeCB() { return this._ignoreLayoutsNodeChange; }
/**
* Destroys a grid instance. DO NOT CALL any methods or access any vars after this as it will free up members.
* @param removeDOM if `false` grid and items HTML elements will not be removed from the DOM (Optional. Default `true`).
*/
destroy(removeDOM = true) {
if (!this.el)
return; // prevent multiple calls
this.offAll();
this._updateResizeEvent(true);
this.setStatic(true, false); // permanently removes DD but don't set CSS class (we're going away)
this.setAnimation(false);
if (!removeDOM) {
this.removeAll(removeDOM);
this.el.removeAttribute('gs-current-row');
}
else {
this.el.parentNode.removeChild(this.el);
}
if (this.parentGridNode)
delete this.parentGridNode.subGrid;
delete this.parentGridNode;
delete this.opts;
delete this._placeholder?.gridstackNode;
delete this._placeholder;
delete this.engine;
delete this.el.gridstack; // remove circular dependency that would prevent a freeing
delete this.el;
return this;
}
/**
* enable/disable floating widgets (default: `false`) See [example](http://gridstackjs.com/demo/float.html)
*/
float(val) {
if (this.opts.float !== val) {
this.opts.float = this.engine.float = val;
this._triggerChangeEvent();
}
return this;
}
/**
* get the current float mode
*/
getFloat() {
return this.engine.float;
}
/**
* Get the position of the cell under a pixel on screen.
* @param position the position of the pixel to resolve in
* absolute coordinates, as an object with top and left properties
* @param useDocRelative if true, value will be based on document position vs parent position (Optional. Default false).
* Useful when grid is within `position: relative` element
*
* Returns an object with properties `x` and `y` i.e. the column and row in the grid.
*/
getCellFromPixel(position, useDocRelative = false) {
const box = this.el.getBoundingClientRect();
// console.log(`getBoundingClientRect left: ${box.left} top: ${box.top} w: ${box.w} h: ${box.h}`)
let containerPos;
if (useDocRelative) {
containerPos = { top: box.top + document.documentElement.scrollTop, left: box.left };
// console.log(`getCellFromPixel scrollTop: ${document.documentElement.scrollTop}`)
}
else {
containerPos = { top: this.el.offsetTop, left: this.el.offsetLeft };
// console.log(`getCellFromPixel offsetTop: ${containerPos.left} offsetLeft: ${containerPos.top}`)
}
const relativeLeft = position.left - containerPos.left;
const relativeTop = position.top - containerPos.top;
const columnWidth = (box.width / this.getColumn());
const rowHeight = (box.height / parseInt(this.el.getAttribute('gs-current-row')));
return { x: Math.floor(relativeLeft / columnWidth), y: Math.floor(relativeTop / rowHeight) };
}
/** returns the current number of rows, which will be at least `minRow` if set */
getRow() {
return Math.max(this.engine.getRow(), this.opts.minRow);
}
/**
* Checks if specified area is empty.
* @param x the position x.
* @param y the position y.
* @param w the width of to check
* @param h the height of to check
*/
isAreaEmpty(x, y, w, h) {
return this.engine.isAreaEmpty(x, y, w, h);
}
/**
* If you add elements to your grid by hand (or have some framework creating DOM), 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.
* @param els widget or single selector to convert.
* @param options widget definition to use instead of reading attributes or using default sizing values
*
* @example
* const grid = GridStack.init();
* grid.el.innerHtml = '<div id="1" gs-w="3"></div><div id="2"></div>';
* grid.makeWidget('1');
* grid.makeWidget('2', {w:2, content: 'hello'});
*/
makeWidget(els, options) {
const el = GridStack.getElement(els);
if (!el || el.gridstackNode)
return el;
if (!el.parentElement)
this.el.appendChild(el);
this._prepareElement(el, true, options);
const node = el.gridstackNode;
this._updateContainerHeight();
// see if there is a sub-grid to create
if (node.subGridOpts) {
this.makeSubGrid(el, node.subGridOpts, undefined, false); // node.subGrid will be used as option in method, no need to pass
}
// if we're adding an item into 1 column make sure
// we don't override the larger 12 column layout that was already saved. #1985
let resetIgnoreLayoutsNodeChange;
if (this.opts.column === 1 && !this._ignoreLayoutsNodeChange) {
resetIgnoreLayoutsNodeChange = this._ignoreLayoutsNodeChange = true;
}
this._triggerAddEvent();
this._triggerChangeEvent();
if (resetIgnoreLayoutsNodeChange)
delete this._ignoreLayoutsNodeChange;
return el;
}
on(name, callback) {
// check for array of names being passed instead
if (name.indexOf(' ') !== -1) {
const names = name.split(' ');
names.forEach(name => this.on(name, callback));
return this;
}
// native CustomEvent handlers - cash the generic handlers so we can easily remove
if (name === 'change' || name === 'added' || name === 'removed' || name === 'enable' || name === 'disable') {
const noData = (name === 'enable' || name === 'disable');
if (noData) {
this._gsEventHandler[name] = (event) => callback(event);
}
else {
this._gsEventHandler[name] = (event) => { if (event.detail)
callback(event, event.detail); };
}
this.el.addEventListener(name, this._gsEventHandler[name]);
}
else if (name === 'drag' || name === 'dragstart' || name === 'dragstop' || name === 'resizestart' || name === 'resize'
|| name === 'resizestop' || name === 'dropped' || name === 'resizecontent') {
// drag&drop stop events NEED to be call them AFTER we update node attributes so handle them ourself.
// do same for start event to make it easier...
this._gsEventHandler[name] = callback;
}
else {
console.error('GridStack.on(' + name + ') event not supported');
}
return this;
}
/**
* unsubscribe from the 'on' event GridStackEvent
* @param name of the event (see possible values) or list of names space separated
*/
off(name) {
// check for array of names being passed instead
if (name.indexOf(' ') !== -1) {
const names = name.split(' ');
names.forEach(name => this.off(name));
return this;
}
if (name === 'change' || name === 'added' || name === 'removed' || name === 'enable' || name === 'disable') {
// remove native CustomEvent handlers
if (this._gsEventHandler[name]) {
this.el.removeEventListener(name, this._gsEventHandler[name]);
}
}
delete this._gsEventHandler[name];
return this;
}
/** remove all event handlers */
offAll() {
Object.keys(this._gsEventHandler).forEach((key) => this.off(key));
return this;
}
/**
* Removes widget from the grid.
* @param el widget or selector to modify
* @param removeDOM if `false` DOM element won't be removed from the tree (Default? true).
* @param triggerEvent if `false` (quiet mode) element will not be added to removed list and no 'removed' callbacks will be called (Default? true).
*/
removeWidget(els, removeDOM = true, triggerEvent = true) {
if (!els) {
console.error('Error: GridStack.removeWidget(undefined) called');
return this;
}
GridStack.getElements(els).forEach(el => {
if (el.parentElement && el.parentElement !== this.el)
return; // not our child!
let node = el.gridstackNode;
// For Meteor support: https://github.com/gridstack/gridstack.js/pull/272
if (!node) {
node = this.engine.nodes.find(n => el === n.el);
}
if (!node)
return;
if (removeDOM && GridStack.addRemoveCB) {
GridStack.addRemoveCB(this.el, node, false, false);
}